phewsh 0.15.40 → 0.15.41

package/bin/phewsh.js

@@ -189,13 +189,22 @@ async function maybeFirstRunIntro() {
   } catch { /* the intro is a nicety — never let it block the session */ }
 }
 
+// Always-on, frictionless: on the first interactive use, auto-enable ambient
+// across every installed harness (unless the user opted out); on every run
+// after, self-heal so each tool's context files are present and fresh. All
+// best-effort and non-blocking — a launch must never wait on or fail from this.
+async function ambientSelfHeal() {
+  try { await require('../commands/ambient').ensureAuto(); } catch { /* never block launch */ }
+  // Refresh-only: keep already-present context files fresh, but never CREATE
+  // them just because phewsh was opened here — that would dirty a clean repo.
+  try { require('../lib/selfheal').syncContextFiles({ createMissing: false }); } catch { /* never block launch */ }
+  try { require('../lib/selfheal').refreshGlobalBaseFilesIfApplied(); } catch { /* never block launch */ }
+}
+
 if (!command) {
   // Bare `phewsh` — first run gets the intro, then drop into the session.
   // Session handles missing API key gracefully with /login and /key commands.
-  // Propagate any global-base-file guidance fixes for users who opted in
-  // (silent, idempotent, only if ambient was already applied).
-  try { require('../lib/selfheal').refreshGlobalBaseFilesIfApplied(); } catch { /* never block launch */ }
-  maybeFirstRunIntro().then(() => COMMANDS.session());
+  ambientSelfHeal().finally(() => maybeFirstRunIntro().then(() => COMMANDS.session()));
 } else if (command === 'help' || command === '--help' || command === '-h') {
   showHelp();
   exitAfterUpdate(0);
@@ -209,12 +218,7 @@ 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 */ }
-  try { require('../lib/selfheal').refreshGlobalBaseFilesIfApplied(); } catch { /* never block launch */ }
-  maybeFirstRunIntro().then(() => COMMANDS.session());
+  ambientSelfHeal().finally(() => maybeFirstRunIntro().then(() => COMMANDS.session()));
 } else {
   console.error(`\n  Unknown command: ${command}\n  Run 'phewsh help' for available commands.\n`);
   process.exit(1);

package/commands/ambient.js

@@ -156,7 +156,12 @@ async function turnOn(skipConfirm) {
   if (!skipConfirm) {
     const ok = await confirm(`  ${b('Apply?')} ${slate('[y/N] ')}`);
     if (!ok) {
-      console.log(`  ${sage('Nothing changed.')}`);
+      // A declined prompt is a deliberate opt-out — record it so the first-run
+      // auto-enable never overrides the user's "no" on a later command.
+      const led = loadLedger();
+      led.disabled = true;
+      saveLedger(led);
+      console.log(`  ${sage('Nothing changed.')} ${slate('(phewsh won\'t auto-enable; run `phewsh ambient on` anytime.)')}`);
       console.log('');
       return;
     }
@@ -180,6 +185,7 @@ async function turnOn(skipConfirm) {
     };
   }
   ledger.seenHarnesses = harnesses.filter(h => h.installed).map(h => h.id);
+  ledger.disabled = false; // explicit enable clears any prior opt-out
   saveLedger(ledger);
 
   console.log('');
@@ -201,6 +207,8 @@ function turnOff() {
   const ledger = loadLedger();
   delete ledger.applied['claude-code'];
   delete ledger.applied.globalBase;
+  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) {
@@ -271,6 +279,59 @@ function status() {
   console.log('');
 }
 
+// First-run / always-on. The first time phewsh is used interactively, wire
+// ambient automatically across every installed harness — so the user never has
+// to run `phewsh ambient on`. Idempotent and self-limiting:
+//   • respects an explicit opt-out (ledger.disabled — set by `ambient off` or
+//     declining the consent prompt); never re-enables behind the user's back.
+//   • no-op once it has run (autoEnabledAt) — the per-run self-heal keeps files
+//     fresh after that.
+//   • if NO harness is installed yet, does nothing and re-checks next run.
+// Transparent: prints a one-time notice naming what changed and how to undo —
+// informed consent after the fact, fully reversible. Never throws/blocks.
+async function ensureAuto() {
+  const ledger = loadLedger();
+  const interacted = ledger.disabled || ledger.autoEnabledAt ||
+    (ledger.applied && (ledger.applied['claude-code'] || ledger.applied.globalBase));
+  if (interacted) return;
+
+  const harnesses = listHarnesses();
+  const installed = harnesses.filter(h => h.installed);
+  if (installed.length === 0) return; // nothing to enhance yet — try again next run
+
+  const hasClaude = installed.some(h => h.id === 'claude-code');
+  const changes = hasClaude ? applyClaudeHooks() : [];
+  const { written } = selfheal.syncGlobalBaseFiles();
+  // 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 */ }
+
+  const now = new Date().toISOString();
+  if (hasClaude) {
+    ledger.applied['claude-code'] = {
+      at: now, file: CLAUDE_SETTINGS, changes,
+      captures: '~/.phewsh/ambient-sessions.jsonl — timestamp, project, cwd only',
+      undo: 'phewsh ambient off',
+    };
+  }
+  if (written.length > 0) {
+    ledger.applied.globalBase = { at: now, files: written, undo: 'phewsh ambient off' };
+  }
+  ledger.disabled = false;
+  ledger.autoEnabledAt = now;
+  ledger.seenHarnesses = installed.map(h => h.id);
+  saveLedger(ledger);
+
+  if ((changes.length || written.length) && process.stdout.isTTY) {
+    console.log('');
+    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')}`);
+    console.log('');
+  }
+}
+
 async function main() {
   const sub = process.argv[3] || 'status';
   const skipConfirm = process.argv.includes('--yes');
@@ -280,3 +341,4 @@ async function main() {
 }
 
 module.exports = main;
+module.exports.ensureAuto = ensureAuto;

package/lib/selfheal.js

@@ -151,7 +151,12 @@ function removeBlock(filePath) {
 
 // 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 } = {}) {
+// createMissing:false = refresh-only. Used by per-launch self-heal so merely
+// opening phewsh in a repo never CREATES context files (which would dirty a
+// clean tree unexpectedly) — it only keeps already-present ones fresh. File
+// creation stays with deliberate acts (a real session's SessionEnd, /reconcile,
+// `seq`), where the user is actually working in the project.
+function syncContextFiles({ cwd = process.cwd(), targets = TARGET_FILES, createMissing = true } = {}) {
   try {
     const intentDir = path.join(cwd, '.intent');
     if (!fs.existsSync(intentDir)) return { synced: [], reason: 'no-intent' };
@@ -181,7 +186,9 @@ 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), core, footer, file)) synced.push(file);
+      const fp = path.join(cwd, file);
+      if (!createMissing && !fs.existsSync(fp)) continue; // refresh-only: don't seed a clean repo
+      if (upsertBlock(fp, core, footer, file)) synced.push(file);
     }
     return { synced };
   } catch (err) { return { synced: [], reason: err && err.message ? err.message : 'error' }; }

package/package.json

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