phewsh 0.15.36 → 0.15.37

package/bin/phewsh.js

@@ -194,6 +194,10 @@ if (!command) {
   // 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;
+  // Keep every tool's context file current before handing off — so a user who
+  // only ever launches (say) Codex via phewsh still has a fresh AGENTS.md, even
+  // though Codex has no SessionEnd hook to trigger the sync. Silent, best-effort.
+  try { require('../lib/selfheal').syncContextFiles(); } catch { /* never block launch */ }
   maybeFirstRunIntro().then(() => COMMANDS.session());
 } else {
   console.error(`\n  Unknown command: ${command}\n  Run 'phewsh help' for available commands.\n`);

package/commands/ambient.js

@@ -18,6 +18,7 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const { listHarnesses } = require('../lib/harnesses');
+const selfheal = require('../lib/selfheal');
 
 const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
 const LEDGER_FILE = path.join(PHEWSH_DIR, 'ambient.json');
@@ -101,7 +102,7 @@ function showConsentScreen(harnesses) {
   console.log('');
   console.log(`  ${sage('Detected on this machine:')}`);
   for (const h of harnesses.filter(h => h.installed)) {
-    const note = h.id === 'claude-code' ? teal('enhanceable now') : slate('detection only in v1 — `phewsh sequence` + `phewsh mcp setup` work today');
+    const note = h.id === 'claude-code' ? teal('live hook + base file') : slate('base file + project context sync (no live hook to install)');
     console.log(`    ${green('✓')} ${cream(h.label.padEnd(14))} ${note}`);
   }
   console.log('');
@@ -110,8 +111,20 @@ function showConsentScreen(harnesses) {
   console.log(`                     ${sage('(vision, next steps, constraints) is injected at session start.')}`);
   console.log(`    ${teal('Session capture')}  ${sage('SessionEnd hook — appends one metadata line (time, project, cwd)')}`);
   console.log(`                     ${sage('to')} ${cream('~/.phewsh/ambient-sessions.jsonl')}${sage('.')} ${b(sage('Never transcript contents.'))}`);
+
+  const globalTargets = selfheal.detectGlobalTargets();
+  if (globalTargets.length > 0) {
+    console.log('');
+    console.log(`  ${b('Machine-wide awareness (every tool, even outside a phewsh project):')}`);
+    console.log(`    ${sage('A small, marked, reversible block is written into each tool\'s base file so')}`);
+    console.log(`    ${sage('it knows phewsh exists and leaves the')} 😮‍💨🤫 ${sage('signature when it helps:')}`);
+    for (const t of globalTargets) {
+      console.log(`      ${teal('+')} ${cream(path.join('~', t.dir, t.file).padEnd(22))} ${slate('(' + t.label + ')')}`);
+    }
+    console.log(`    ${sage('Only tools you already have are touched. Your own text is preserved.')}`);
+  }
   console.log('');
-  console.log(`  ${peach('Exactly what changes:')} ${sage('two hook entries in')} ${cream(CLAUDE_SETTINGS)}${sage('. Nothing else is touched.')}`);
+  console.log(`  ${peach('Exactly what changes:')} ${sage('two hook entries in')} ${cream(CLAUDE_SETTINGS)}${globalTargets.length ? sage(' + the base-file blocks above') : ''}${sage('.')}`);
   console.log(`  ${sage('Undo anytime:')} ${cream('phewsh ambient off')} ${sage('· full record:')} ${cream('phewsh ambient status')}`);
   console.log('');
 }
@@ -130,7 +143,11 @@ async function turnOn(skipConfirm) {
   const harnesses = listHarnesses();
   showConsentScreen(harnesses);
 
-  if (claudeApplied()) {
+  const globalPending = selfheal.detectGlobalTargets().length > 0;
+  // "Fully applied" now means BOTH the Claude hooks AND the machine-wide base
+  // files (when there are tools to write them to). Re-running tops up whatever
+  // is missing — e.g. you enabled hooks before global base files existed.
+  if (claudeApplied() && !globalPending) {
     console.log(`  ${green('Already applied.')} ${sage('Status:')} ${cream('phewsh ambient status')}`);
     console.log('');
     return;
@@ -146,6 +163,7 @@ async function turnOn(skipConfirm) {
   }
 
   const changes = applyClaudeHooks();
+  const { written } = selfheal.syncGlobalBaseFiles();
   const ledger = loadLedger();
   ledger.applied['claude-code'] = {
     at: new Date().toISOString(),
@@ -154,27 +172,41 @@ async function turnOn(skipConfirm) {
     captures: '~/.phewsh/ambient-sessions.jsonl — timestamp, project, cwd only',
     undo: 'phewsh ambient off',
   };
+  if (written.length > 0 || ledger.applied.globalBase) {
+    ledger.applied.globalBase = {
+      at: new Date().toISOString(),
+      files: written.length > 0 ? written : (ledger.applied.globalBase || {}).files || [],
+      undo: 'phewsh ambient off',
+    };
+  }
   ledger.seenHarnesses = harnesses.filter(h => h.installed).map(h => h.id);
   saveLedger(ledger);
 
   console.log('');
   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)')}`));
   console.log('');
   console.log(`  ${sage('Next Claude Code session in a project with')} ${cream('.intent/')} ${sage('starts pre-briefed.')}`);
+  if (written.length > 0) {
+    console.log(`  ${sage('Every detected tool now knows phewsh exists and leaves the')} 😮‍💨🤫 ${sage('signature.')}`);
+  }
   console.log(`  ${sage('You never have to launch phewsh for this to work.')}`);
   console.log('');
 }
 
 function turnOff() {
   const removed = removeClaudeHooks();
+  const { removed: removedGlobal } = selfheal.removeGlobalBaseFiles();
   const ledger = loadLedger();
   delete ledger.applied['claude-code'];
+  delete ledger.applied.globalBase;
   saveLedger(ledger);
   console.log('');
-  if (removed.length > 0) {
+  if (removed.length > 0 || removedGlobal.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)')}`));
     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.')}`);
@@ -199,10 +231,22 @@ function status() {
         console.log(`        ${slate('· captures: ' + entry.captures)}`);
       }
     } else {
-      console.log(`    ${slate('○')} ${cream(h.label.padEnd(14))} ${slate('detected — v1 enhances Claude Code only')}`);
+      console.log(`    ${slate('○')} ${cream(h.label.padEnd(14))} ${slate('detected — kept current via its context file (no live hook to install)')}`);
     }
   }
 
+  // Machine-wide base files — what phewsh wrote so every tool is aware.
+  const gb = ledger.applied.globalBase;
+  const detected = selfheal.detectGlobalTargets();
+  if (gb && (gb.files || []).length > 0) {
+    console.log('');
+    console.log(`    ${green('●')} ${cream('Machine-wide awareness'.padEnd(22))} ${teal('on')} ${slate('(applied ' + gb.at + ')')}`);
+    (gb.files || []).forEach(f => console.log(`        ${slate('· ' + f)}`));
+  } else if (detected.length > 0) {
+    console.log('');
+    console.log(`    ${yellow('○')} ${cream('Machine-wide awareness'.padEnd(22))} ${sage('available for ' + detected.map(t => t.label).join(', ') + ' — phewsh ambient on')}`);
+  }
+
   // New harnesses since last apply — the re-offer.
   const seen = ledger.seenHarnesses || [];
   const fresh = harnesses.filter(h => h.installed && !seen.includes(h.id));

package/commands/hook.js

@@ -125,13 +125,8 @@ function sessionStart() {
   // Ambient operating guidance: make phewsh *felt*, not invoked. The human may
   // not know a single slash command — translate intent into phewsh actions for
   // them, nudge gently, and leave a quiet signature so they feel the layer.
-  parts.push(`\n## Working with phewsh installed (ambient guidance)
-phewsh keeps this project's intent, decisions, and outcomes aligned across every AI tool — so nothing is lost when the human switches tools. Help it work *for* them without making them learn it:
-- Do their actual request first, and well.
-- When you make a real decision, ship something, or change direction, offer in plain language to keep the shared record current — e.g. "want me to reconcile this into phewsh so your other tools inherit it?" Never make them memorize slash commands; map their intent to phewsh actions yourself.
-- If the drift note above is present, mention it once, gently.
-- Keep nudges subtle and occasional — never nag, never block the work.
-- When phewsh context shaped your reply, sign off quietly with 😮‍💨🤫 (e.g. "— 😮‍💨🤫") so the human feels the continuity layer working in the background.`);
+  // Shared with the synced context files so every tool gets the same behavior.
+  parts.push('\n' + require('../lib/ambient-guidance').PROJECT_GUIDANCE);
 
   parts.push(`\n(Brief injected by PHEWSH ambient from .intent/. Honor the constraints above. The human can run \`phewsh\` for mission control — council, outcomes, the decision record.)`);
 

package/lib/ambient-guidance.js

@@ -0,0 +1,41 @@
+// Ambient guidance — the behavior phewsh asks every AI tool to adopt simply
+// because it's installed. ONE source of truth, used in three places:
+//
+//   1. The Claude Code SessionStart hook brief (cli/commands/hook.js)
+//   2. The per-project context files phewsh syncs from .intent/
+//      (CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules — cli/lib/selfheal.js)
+//   3. The machine-wide base files phewsh writes when ambient is on
+//      (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md)
+//
+// The whole point: most tools (Codex, Gemini, Cursor, …) have no SessionStart
+// hook like Claude Code — their integration IS the context file they auto-read.
+// So the guidance HAS to live in the file, not only in the hook, or the human
+// never feels phewsh in those tools. The 😮‍💨🤫 sign-off is the proof-of-life:
+// it's how the human sees the continuity layer working without invoking it.
+
+// In-project guidance — shown when the tool is working inside a phewsh project
+// (a brief / synced block accompanies it). Imperative about the sign-off, since
+// a soft "you may sign off" got skipped in practice.
+const PROJECT_GUIDANCE = `## Working with phewsh installed (ambient guidance)
+phewsh keeps this project's intent, decisions, and outcomes aligned across every AI tool — so nothing is lost when the human switches tools. Help it work *for* them without making them learn it:
+- Do their actual request first, and well.
+- When you make a real decision, ship something, or change direction, offer in plain language to keep the shared record current — e.g. "want me to reconcile this into phewsh so your other tools inherit it?" Never make them memorize slash commands; map their intent to phewsh actions yourself.
+- If a drift note is present above, mention it once, gently.
+- Keep nudges subtle and occasional — never nag, never block the work.
+- **Sign-off (do not skip):** when anything from this context shaped your reply — the project's intent, a drift note, the continuity line, or you acted on this project — end that message with \`— 😮‍💨🤫\` on its own line. This quiet signature is how the human sees phewsh is active and carrying their intent across tools.`;
+
+// Machine-wide guidance — written into each tool's GLOBAL base file so the tool
+// behaves like phewsh exists even outside a phewsh project (e.g. a fresh repo,
+// or the home directory). Project-agnostic on purpose.
+const GLOBAL_GUIDANCE = `# phewsh — continuity layer (installed on this machine)
+
+phewsh keeps a project's intent, decisions, and outcomes continuous across every AI coding tool, so nothing is lost when the human switches between you and another agent. It's installed here, so honor it in every session:
+
+- If the current project has a \`.intent/\` directory, treat it as the source of truth for what's being built and why. (Inside a phewsh project you'll also receive a fuller brief.)
+- If a project clearly needs durable, cross-tool intent and has none, you may offer **once**, in plain language: "want me to set this up with phewsh so it carries across your tools?" (it's \`phewsh intent --init\`). Never nag.
+- The human shouldn't need to know any commands — translate their intent into phewsh actions yourself.
+- **Sign-off (do not skip):** whenever phewsh context shaped your reply — this guidance, a project's \`.intent/\`, or its continuity record — end that message with \`— 😮‍💨🤫\` on its own line. That quiet signature is how the human sees the continuity layer is active.
+
+Run \`phewsh\` anytime for mission control (council, outcomes, the decision record). Undo this block: \`phewsh ambient off\`.`;
+
+module.exports = { PROJECT_GUIDANCE, GLOBAL_GUIDANCE };

package/lib/selfheal.js

@@ -10,6 +10,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 const INTENT_FILES_RE = /\.(md|json)$/;
 
@@ -89,15 +90,18 @@ const END_MARKER = '<!-- PHEWSH:END -->';
 function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 
 // Strip the volatile signed footer so timestamp-only changes don't cause churn.
+// Covers both the project ("synced by phewsh") and global ("installed by
+// phewsh") footers — otherwise the timestamp leaks into the diff and re-running
+// rewrites every file every time.
 function coreOf(text) {
-  return text.replace(/\n?>\s*—\s*synced by phewsh[\s\S]*$/m, '').trim();
+  return text.replace(/\n?>\s*—\s*(synced|installed) by phewsh[\s\S]*$/m, '').trim();
 }
 
 // Insert/replace the phewsh block between markers; create the file (with a
 // short header) if absent; preserve everything outside the markers. Writes
 // only when the substantive content changed (footer timestamp is ignored), so
 // re-running every session doesn't churn files. Returns true if written.
-function upsertBlock(filePath, core, footer, fileLabel) {
+function upsertBlock(filePath, core, footer, fileLabel, headerText) {
   try {
     const block = core.replace(/\s*$/, '') + '\n' + footer;
     const wrapped = `${START_MARKER}\n${block}\n${END_MARKER}`;
@@ -111,13 +115,40 @@ function upsertBlock(filePath, core, footer, fileLabel) {
     } else if (existing) {
       fs.writeFileSync(filePath, existing.replace(/\s*$/, '') + '\n\n' + wrapped + '\n');
     } else {
-      const header = `# ${fileLabel} — kept current by phewsh\n> Project context compiled from .intent/. The block below is auto-managed; edit outside the markers.\n\n`;
+      const header = headerText != null
+        ? headerText
+        : `# ${fileLabel} — kept current by phewsh\n> Project context compiled from .intent/. The block below is auto-managed; edit outside the markers.\n\n`;
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       fs.writeFileSync(filePath, header + wrapped + '\n');
     }
     return true;
   } catch { return false; }
 }
 
+// Remove phewsh's marker block from a file. If nothing but whitespace remains,
+// delete the file (phewsh created it). Returns true if the file changed.
+function removeBlock(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return false;
+    const existing = fs.readFileSync(filePath, 'utf-8');
+    if (!existing.includes(START_MARKER)) return false;
+    const re = new RegExp(escapeRe(START_MARKER) + '[\\s\\S]*?' + escapeRe(END_MARKER), 'g');
+    const next = existing.replace(re, '').trim();
+    // If all that's left is phewsh's own scaffolding (the global HTML-comment
+    // notice, or the generated "kept current by phewsh" header), phewsh created
+    // the whole file — remove it. Otherwise keep the user's surrounding content.
+    const residual = next
+      .replace(/<!--\s*phewsh writes only the marked block[\s\S]*?-->/gi, '')
+      .replace(/^#[^\n]*kept current by phewsh[^\n]*\n?/m, '')
+      .replace(/^>\s*Project context compiled from \.intent\/[^\n]*\n?/m, '')
+      .trim();
+    if (!residual) { fs.unlinkSync(filePath); return true; }
+    fs.writeFileSync(filePath, next + '\n');
+    return true;
+  } catch { return false; }
+}
+
 // Build the phewsh block once (from .intent/ via the sequencer) and write it
 // into every target tool's context file with a signed, timestamped footer.
 function syncContextFiles({ cwd = process.cwd(), targets = TARGET_FILES } = {}) {
@@ -134,6 +165,13 @@ function syncContextFiles({ cwd = process.cwd(), targets = TARGET_FILES } = {})
       if (cwd !== prev) { try { process.chdir(prev); } catch { /* best-effort */ } }
     }
     if (!output) return { synced: [], reason: 'no-output' };
+    // Append the ambient guidance so EVERY tool that reads its context file —
+    // not just Claude Code via the hook — gets the nudge-in-plain-language +
+    // 😮‍💨🤫 sign-off behavior. Without this, Codex/Gemini/Cursor read project
+    // facts but have no reason to act like phewsh is present. Static text, so
+    // coreOf() comparison stays churn-free.
+    const { PROJECT_GUIDANCE } = require('./ambient-guidance');
+    const core = output.replace(/\s*$/, '') + '\n\n' + PROJECT_GUIDANCE;
     let head = '';
     try {
       head = require('child_process').execFileSync('git', ['rev-parse', '--short', 'HEAD'],
@@ -143,12 +181,62 @@ function syncContextFiles({ cwd = process.cwd(), targets = TARGET_FILES } = {})
     const footer = `> — synced by phewsh 😮‍💨🤫 · ${stamp}${head ? ' · ' + head : ''}`;
     const synced = [];
     for (const file of targets) {
-      if (upsertBlock(path.join(cwd, file), output, footer, file)) synced.push(file);
+      if (upsertBlock(path.join(cwd, file), core, footer, file)) synced.push(file);
     }
     return { synced };
   } catch (err) { return { synced: [], reason: err && err.message ? err.message : 'error' }; }
 }
 
+// ── Layer 2: machine-wide base files ─────────────────────────────────────
+// So a tool behaves like phewsh exists even OUTSIDE a phewsh project (a fresh
+// repo, the home dir). We write the project-agnostic guidance into each tool's
+// GLOBAL base context file — but ONLY for tools whose config dir already exists
+// (honest: don't seed dirs for tools the user doesn't have). Marker-wrapped,
+// signed, fully reversible via removeGlobalBaseFiles().
+const GLOBAL_TARGETS = [
+  { dir: '.claude', file: 'CLAUDE.md', label: 'Claude Code' },
+  { dir: '.codex',  file: 'AGENTS.md', label: 'Codex' },
+  { 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();
+  return GLOBAL_TARGETS
+    .map(t => ({ ...t, path: path.join(home, t.dir, t.file) }))
+    .filter(t => fs.existsSync(path.join(home, t.dir)));
+}
+
+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();
+    const written = [];
+    for (const t of detectGlobalTargets()) {
+      if (upsertBlock(t.path, GLOBAL_GUIDANCE, footer, t.label, header)) {
+        written.push(path.join('~', t.dir, t.file));
+      }
+    }
+    return { written };
+  } catch (err) { return { written: [], reason: err && err.message ? err.message : 'error' }; }
+}
+
+function removeGlobalBaseFiles() {
+  const home = os.homedir();
+  const removed = [];
+  for (const t of GLOBAL_TARGETS) {
+    const fp = path.join(home, t.dir, t.file);
+    if (removeBlock(fp)) removed.push(path.join('~', t.dir, t.file));
+  }
+  return { removed };
+}
+
 // The deeper drift: code ships but .intent/ content never gets updated (the
 // exact failure that ate phewsh's own dogfood — 16 versions shipped while
 // next.md stayed days stale). Count git commits authored AFTER the newest
@@ -240,4 +328,5 @@ module.exports = {
   isStale, heal, newestIntentMs, newestNarrativeMs,
   commitsSinceIntent, worktreeChanges, wrapDraft, appendToNext,
   syncContextFiles, TARGET_FILES,
+  syncGlobalBaseFiles, removeGlobalBaseFiles, detectGlobalTargets,
 };

package/package.json

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