moflo 4.10.20 → 4.10.21

package/bin/lib/yaml-upgrader.mjs

@@ -22,6 +22,31 @@ import { readFileSync, writeFileSync, existsSync } from 'fs';
  * also add the same block here so existing users get it on their next session.
  */
 export const REQUIRED_SECTIONS = [
+  {
+    key: 'session_continuity',
+    block: `# Passive session-continuity — pick up where you left off across sessions.
+# capture: silently record a compact "where you left off" digest at turn-end.
+# inject:  surface the single most-relevant recent digest at session-start
+#          (relevance-gated by branch / changed files / recency, so an unrelated
+#          session shows nothing). Add "<private>" to a message to skip capturing
+#          that session. Set either to false to opt out.
+session_continuity:
+  capture: true
+  inject: true
+  max_age_hours: 72            # ignore digests older than this when injecting
+`,
+  },
+  {
+    key: 'auto_meditate',
+    block: `# Auto-meditate (#1198) — the automatic counterpart to /meditate. When enabled,
+# moflo recognizes durable lessons in the LIVE session (a tiny answer-first note
+# on course-corrections / errors / decisions) and distills them into long-term
+# memory at the next session-start via a cheap headless Haiku pass — deduped.
+# Ships ON; set false to opt out.
+auto_meditate:
+  enabled: true
+`,
+  },
   {
     key: 'sandbox',
     block: `# Spell step sandboxing (OS-level process isolation for bash steps)
@@ -37,6 +62,38 @@ sandbox:
   },
 ];
 
+/**
+ * Registry of top-level config sections RENAMED across a moflo version. On
+ * upgrade, an existing `<from>:` block in the user's moflo.yaml is renamed in
+ * place to `<to>:` — preserving the user's values (e.g. an opt-out) — so they
+ * keep their setting under the new key instead of a fresh default block being
+ * appended while the stale old one lingers.
+ */
+export const RENAMED_SECTIONS = [
+  // Auto-meditate rebrand — feature #1198 was renamed from "auto-reflect".
+  { from: 'auto_reflect', to: 'auto_meditate' },
+];
+
+/**
+ * Rename any registered top-level sections present under their OLD key to the
+ * NEW key, in place. Only the top-level key line is rewritten; the block body
+ * (the user's values) is preserved untouched. No-op when the old key is absent
+ * or the new key already exists. Returns the list of `from→to` renames applied.
+ */
+export function renameYamlSections(yamlPath, registry = RENAMED_SECTIONS) {
+  if (!existsSync(yamlPath)) return [];
+  let text = readFileSync(yamlPath, 'utf-8');
+  const applied = [];
+  for (const { from, to } of registry) {
+    if (hasTopLevelSection(text, from) && !hasTopLevelSection(text, to)) {
+      text = text.replace(new RegExp(`^${from}(\\s*:)`, 'm'), `${to}$1`);
+      applied.push(`${from}→${to}`);
+    }
+  }
+  if (applied.length > 0) writeFileSync(yamlPath, text, 'utf-8');
+  return applied;
+}
+
 /**
  * Return true if the YAML text already defines the given top-level key.
  * Matches `^<key>:` at column 0 on any line, which is how YAML roots look.
@@ -66,6 +123,11 @@ export function missingSections(yamlText, registry = REQUIRED_SECTIONS) {
 export function ensureYamlSections(yamlPath, registry = REQUIRED_SECTIONS) {
   if (!existsSync(yamlPath)) return [];
 
+  // Migrate any renamed sections in place BEFORE computing what's missing, so a
+  // renamed key (e.g. auto_reflect → auto_meditate) is recognised as present and
+  // not re-appended as a fresh default block alongside the stale old one.
+  renameYamlSections(yamlPath);
+
   const original = readFileSync(yamlPath, 'utf-8');
   const toAppend = registry.filter((entry) => !hasTopLevelSection(original, entry.key));
   if (toAppend.length === 0) return [];

package/bin/meditate-capture.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Auto-meditate Stage 1 — CAPTURE (#1198). One script, two hook entry points:
+ *
+ *   detect  (UserPromptSubmit) — mechanically score the user's prompt + recent
+ *           transcript tail for a strong signal (course-correction / error→fix /
+ *           decision). On a hit, and within rate limits, print an answer-first
+ *           directive asking the LIVE model — which has full context at the
+ *           moment of insight — to append ONE <meditate-capture> line IF a durable
+ *           lesson emerged. Stdout from a UserPromptSubmit hook is added to the
+ *           model's context (same mechanism as .claude/helpers/prompt-hook.mjs).
+ *
+ *   scrape  (Stop) — read the transcript tail, extract <meditate-capture> tags
+ *           from the last ASSISTANT message(s), and append the raw one-liners to
+ *           the JSON ledger (.moflo/meditate-ledger.json). No moflo.db write, no
+ *           dedup yet — the bounded Haiku distill (bin/meditate-distill.mjs) does
+ *           that later, writer-safe, via memory_store.
+ *
+ * Both modes early-return cheaply when auto-meditate is OFF or CLAUDE_CODE_HEADLESS
+ * is set — the distill's own headless session must never re-enter capture (#860).
+ * A hook must NEVER throw: every path is wrapped and degrades to a silent exit 0.
+ *
+ * Invoked by:
+ *   node .claude/scripts/meditate-capture.mjs meditate-detect   (UserPromptSubmit)
+ *   node .claude/scripts/meditate-capture.mjs meditate-scrape    (Stop)
+ *
+ * Cross-platform (Rule #1): Node fs/path primitives only; no shell.
+ */
+
+import { findProjectRoot } from './lib/moflo-paths.mjs';
+import { readHookStdin, readFileTail } from './lib/hook-io.mjs';
+import {
+  TRANSCRIPT_TAIL_BYTES,
+  readMeditateConfig,
+  isHeadless,
+  detectSignal,
+  recentTranscriptTurn,
+  buildCaptureDirective,
+  injectionAllowed,
+  readMeditateState,
+  recordInjection,
+  extractCapturesFromTranscript,
+  appendLedgerEntries,
+} from './lib/meditate.mjs';
+
+// Scrape needs to reliably catch the tag at the END of the assistant's reply,
+// which can be a single large JSONL line — read a generous tail. Detect only
+// needs recent error/decision markers, so the smaller shared window suffices.
+const SCRAPE_TAIL_BYTES = 262_144;
+
+function warn(msg) {
+  try { process.stderr.write(`moflo: meditate-capture ${msg}\n`); } catch { /* never throw from a hook */ }
+}
+
+/** Shared preamble: resolve root + config, applying the OFF / headless guards.
+ *  Returns null when the caller should early-exit. */
+function gate() {
+  if (isHeadless(process.env)) return null;          // #860 — never run inside the distill's own session
+  const projectRoot = findProjectRoot();
+  if (!readMeditateConfig(projectRoot).enabled) return null; // off (opt-out)
+  return { projectRoot };
+}
+
+async function detect() {
+  const ctx = gate();
+  if (!ctx) return;
+  const { projectRoot } = ctx;
+
+  const input = await readHookStdin();
+  const prompt = (input.prompt || input.user_prompt || '').trim();
+  // No real user prompt (system reminder / task-notification re-invocation) →
+  // there's no "moment" to attach a directive to. Skip — this is the dominant
+  // false-fire source the live dogfood surfaced.
+  if (!prompt) return;
+
+  // Cheapest path first: corrections + in-prompt decisions need only the prompt.
+  // Only when the prompt alone yields nothing do we read the transcript and scope
+  // to the MOST RECENT turn (post-last-user-message) — scanning the full tail
+  // re-fires on stale error/decision markers from earlier in the session.
+  let signal = detectSignal(prompt, '');
+  if (!signal.hit) {
+    const tail = readFileTail(input.transcript_path || input.transcriptPath, TRANSCRIPT_TAIL_BYTES);
+    if (tail) signal = detectSignal(prompt, recentTranscriptTurn(tail));
+  }
+  if (!signal.hit) return;
+
+  const sessionId = input.session_id || input.sessionId || null;
+  const now = Date.now();
+  const state = readMeditateState(projectRoot);
+  if (!injectionAllowed(state, sessionId, now)) return; // rate-limited
+
+  try {
+    process.stdout.write(buildCaptureDirective(signal.kind) + '\n');
+  } catch {
+    return; // broken stdout — don't record an injection that didn't land
+  }
+  recordInjection(projectRoot, sessionId, now, state);
+}
+
+async function scrape() {
+  const ctx = gate();
+  if (!ctx) return;
+  const { projectRoot } = ctx;
+
+  const input = await readHookStdin();
+  const tail = readFileTail(input.transcript_path || input.transcriptPath, SCRAPE_TAIL_BYTES);
+  if (!tail) return;
+
+  const lessons = extractCapturesFromTranscript(tail);
+  if (lessons.length === 0) return;
+
+  const sessionId = input.session_id || input.sessionId || null;
+  appendLedgerEntries(projectRoot, lessons.map((lesson) => ({ lesson, kind: 'captured', sessionId })));
+}
+
+const sub = process.argv[2];
+if (sub === 'meditate-detect') {
+  detect().catch((err) => warn(`detect failed (${err && err.message ? err.message : String(err)})`));
+} else if (sub === 'meditate-scrape') {
+  scrape().catch((err) => warn(`scrape failed (${err && err.message ? err.message : String(err)})`));
+} else {
+  warn(`unknown subcommand "${sub || ''}" (expected: meditate-detect | meditate-scrape)`);
+}

package/bin/meditate-distill.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Auto-meditate Stage 2 — DISTILL (#1198). Fired DETACHED by the session-start
+ * launcher (never inline — the launcher's contract is spawn-and-exit). Runs ONE
+ * bounded headless Haiku `claude --print` that executes #1187's /meditate
+ * distillation over the ledger one-liners (NOT the transcript): dedup-search
+ * `learnings` (≥0.80 → update same key), store via memory_store. Because the
+ * headless session calls memory_store itself, writes route through the daemon
+ * single-writer chokepoint (#981) — writer-safe, no raw cross-process db write.
+ *
+ * Haiku is a FORMATTER, not a judge: the durability gate already passed upstream
+ * in the live model when the lesson was captured, so this unattended pass cannot
+ * pollute `learnings` with junk it invented.
+ *
+ * GUARDS:
+ *   - off (auto_meditate.enabled: false) — exit immediately. Default is ON.
+ *   - CLAUDE_CODE_HEADLESS — exit immediately (defensive; the launcher already
+ *     won't fire us in headless, but self-guarding prevents any infinite spawn).
+ *   - empty ledger — exit without spawning anything.
+ *
+ * Only entries in the snapshot we hand to Haiku are marked distilled on success,
+ * so captures that arrive DURING the run survive for the next pass.
+ *
+ * Test seam: MOFLO_MEDITATE_DISTILL_NODE_STUB — when set to a path, the model
+ * call is `node <stub> --print <prompt>` instead of `claude --print <prompt>`,
+ * so the spawn is exercisable cross-platform without a real Claude CLI.
+ *
+ * Invoked by: node .claude/scripts/meditate-distill.mjs
+ *
+ * Cross-platform (Rule #1): Node child_process (arg arrays, no shell) + fs/path.
+ */
+
+import { spawn } from 'child_process';
+import { appendFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { findProjectRoot } from './lib/moflo-paths.mjs';
+import {
+  HAIKU_MODEL_ID,
+  readMeditateConfig,
+  isHeadless,
+  readLedger,
+  pendingEntries,
+  buildDistillPrompt,
+  markLedgerDistilled,
+} from './lib/meditate.mjs';
+
+/** Cap candidates per pass — keeps the Haiku prompt small (cheap, fast). Extra
+ *  pending entries roll into the next session's pass. */
+const DISTILL_BATCH_MAX = 25;
+/** Hard ceiling on the headless run; killed past this. */
+const DISTILL_TIMEOUT_MS = 120_000;
+
+function log(projectRoot, line) {
+  try {
+    const p = resolve(projectRoot, '.moflo', 'meditate-distill.log');
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, `[${new Date().toISOString()}] ${line}\n`, 'utf-8');
+  } catch { /* logging is best-effort — never throw */ }
+}
+
+/** Run the bounded headless distillation. Resolves { success, output }. */
+function runHeadless(projectRoot, prompt) {
+  return new Promise((res) => {
+    const stub = process.env.MOFLO_MEDITATE_DISTILL_NODE_STUB;
+    const cmd = stub ? process.execPath : 'claude';
+    const args = stub ? [stub, '--print', prompt] : ['--print', prompt];
+
+    const env = {
+      ...process.env,
+      CLAUDE_CODE_HEADLESS: 'true',     // mark the child so its own hooks no-op (#860)
+      ANTHROPIC_MODEL: HAIKU_MODEL_ID,  // cheap formatter model
+    };
+
+    let child;
+    try {
+      child = spawn(cmd, args, { cwd: projectRoot, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (err) {
+      res({ success: false, output: '', error: err && err.message ? err.message : String(err) });
+      return;
+    }
+
+    let out = '';
+    let done = false;
+    const finish = (r) => { if (done) return; done = true; clearTimeout(timer); res(r); };
+    const timer = setTimeout(() => {
+      try { child.kill('SIGTERM'); } catch { /* already gone */ }
+      finish({ success: false, output: out, error: `timed out after ${DISTILL_TIMEOUT_MS}ms` });
+    }, DISTILL_TIMEOUT_MS);
+
+    child.stdout?.on('data', (d) => { out += d.toString(); });
+    child.stderr?.on('data', (d) => { out += d.toString(); });
+    child.on('error', (err) => finish({ success: false, output: out, error: err && err.message ? err.message : String(err) }));
+    child.on('close', (code) => finish({ success: code === 0, output: out }));
+  });
+}
+
+async function main() {
+  if (isHeadless(process.env)) return;                       // #860 self-guard
+  const projectRoot = findProjectRoot();
+  if (!readMeditateConfig(projectRoot).enabled) return;       // off (opt-out)
+
+  const pending = pendingEntries(readLedger(projectRoot));
+  if (pending.length === 0) return;                          // nothing to do — no spawn
+
+  const batch = pending.slice(0, DISTILL_BATCH_MAX);
+  const prompt = buildDistillPrompt(batch);
+
+  const result = await runHeadless(projectRoot, prompt);
+  if (result.success) {
+    const marked = markLedgerDistilled(projectRoot, batch.map((e) => e.id));
+    const summary = String(result.output || '').trim().split('\n').filter(Boolean).pop() || '(no summary)';
+    log(projectRoot, `distilled ${batch.length} candidate(s), marked ${marked} — haiku: ${summary.slice(0, 200)}`);
+  } else {
+    // Leave the ledger untouched so the next session retries.
+    log(projectRoot, `distill failed (${result.error || 'non-zero exit'}) — ${batch.length} candidate(s) retained for retry`);
+  }
+}
+
+main().catch((err) => {
+  try { process.stderr.write(`moflo: meditate-distill failed (${err && err.message ? err.message : String(err)})\n`); } catch { /* ignore */ }
+});

package/bin/session-continuity.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Passive session-continuity CAPTURE (#1185).
+ *
+ * Wired to Claude Code's Stop hook (fires at the end of each assistant turn).
+ * On each fire it assembles a compact "where you left off" digest from data
+ * moflo already has — git state, recent `learnings`, the session goal — scrubs
+ * any secrets, and writes ONE record per session into the `.moflo/continuity/`
+ * JSON store. The matching injection runs at session-start inside
+ * session-start-launcher.mjs.
+ *
+ * Why a JSON store and not moflo.db: capture fires while the daemon is live, and
+ * the moflo.db writer audit requires cross-process DB writers to route through
+ * the daemon chokepoint. A dedicated JSON store sidesteps that — these digests
+ * are operational state, not semantic memory. We still READ moflo.db read-only
+ * for recent learnings (safe under WAL; reads never clobber).
+ *
+ * Why Stop (per-turn) and not only a clean SessionEnd: capturing on every turn
+ * makes the digest crash-robust — the latest state survives even if the session
+ * never exits cleanly ("closed my laptop"). A throttle keeps the real work to at
+ * most once per THROTTLE_MS so per-turn cost stays negligible across consumers.
+ *
+ * Invoked by: node .claude/scripts/session-continuity.mjs capture
+ *
+ * Cross-platform (Rule #1): Node fs/path/child_process primitives only.
+ */
+
+import { existsSync, readFileSync, writeFileSync, statSync, openSync, readSync, closeSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
+import { scrubSecrets } from './lib/pii-scrub.mjs';
+import { readHookStdin } from './lib/hook-io.mjs';
+import {
+  readContinuityConfig,
+  readGitState,
+  hasPrivateOptOut,
+  assembleDigestContent,
+  buildDigestMetadata,
+  writeDigest,
+  rotateDigests,
+} from './lib/session-continuity.mjs';
+
+const THROTTLE_MS = 30_000;     // skip the work if we captured <30s ago this session
+const LEARNINGS_SAMPLE = 5;     // how many recent learnings to fold in as "decisions"
+
+function warn(msg) {
+  try { process.stderr.write(`moflo: session-continuity ${msg}\n`); } catch { /* never throw from a hook */ }
+}
+
+/** First user message (the session goal) from a transcript JSONL head. */
+function extractFirstUserGoal(headText) {
+  for (const line of headText.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    let obj;
+    try { obj = JSON.parse(t); } catch { continue; }
+    const role = obj?.message?.role ?? obj?.role;
+    if (role !== 'user') continue;
+    let content = obj?.message?.content ?? obj?.content;
+    if (Array.isArray(content)) {
+      content = content.map((b) => (typeof b === 'string' ? b : b?.text || '')).join(' ');
+    }
+    if (typeof content !== 'string') continue;
+    const firstLine = content.replace(/\s+/g, ' ').trim();
+    // Skip slash-command / hook-noise openers — they aren't a goal statement.
+    if (!firstLine || firstLine.startsWith('<')) continue;
+    return firstLine.slice(0, 200);
+  }
+  return null;
+}
+
+/** Bounded transcript read: goal from the head, `<private>` opt-out scan over
+ *  head+tail. Large transcripts are read at the edges only. */
+function readTranscriptInfo(path) {
+  const info = { goal: null, optOut: false };
+  try {
+    if (!path || !existsSync(path)) return info;
+    const size = statSync(path).size;
+    let head;
+    let tail;
+    if (size <= 1_048_576) {
+      head = tail = readFileSync(path, 'utf-8');
+    } else {
+      const fd = openSync(path, 'r');
+      try {
+        const hb = Buffer.alloc(32_768);
+        readSync(fd, hb, 0, hb.length, 0);
+        head = hb.toString('utf-8');
+        const tlen = 131_072;
+        const tb = Buffer.alloc(tlen);
+        readSync(fd, tb, 0, tlen, Math.max(0, size - tlen));
+        tail = tb.toString('utf-8');
+      } finally {
+        closeSync(fd);
+      }
+    }
+    info.optOut = hasPrivateOptOut(head) || hasPrivateOptOut(tail);
+    info.goal = extractFirstUserGoal(head);
+  } catch {
+    // Transcript is best-effort context; never block capture on it.
+  }
+  return info;
+}
+
+/** Throttle gate — true if we should skip capturing this turn. */
+function shouldThrottle(statePath, sessionId, now) {
+  try {
+    if (!existsSync(statePath)) return false;
+    const s = JSON.parse(readFileSync(statePath, 'utf-8'));
+    return s.sessionId === sessionId && typeof s.lastCaptureMs === 'number' && now - s.lastCaptureMs < THROTTLE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function writeThrottleState(statePath, sessionId, now) {
+  try {
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeFileSync(statePath, JSON.stringify({ sessionId, lastCaptureMs: now }), 'utf-8');
+  } catch { /* non-fatal */ }
+}
+
+/** Recent learnings → short "decision" bullets. Read-only moflo.db access; safe
+ *  under WAL and never blocks the daemon. Best-effort: any failure → []. */
+async function readRecentDecisions(projectRoot, limit) {
+  let db;
+  try {
+    db = await openBackend(projectRoot, { create: false, readOnly: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  try {
+    const stmt = db.prepare(
+      `SELECT content FROM memory_entries WHERE namespace='learnings' AND status='active' ORDER BY created_at DESC LIMIT ?`,
+    );
+    stmt.bind([limit]);
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const firstLine = String(row.content || '')
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l && !l.startsWith('#') && !l.startsWith('---'));
+      if (firstLine) out.push(firstLine.slice(0, 120));
+    }
+    stmt.free();
+  } catch {
+    // learnings table may not exist yet, or DB mid-repair — optional source.
+  } finally {
+    try { if (typeof db.close === 'function') db.close(); } catch { /* already closed */ }
+  }
+  return out;
+}
+
+async function capture() {
+  const projectRoot = findProjectRoot();
+  const cfg = readContinuityConfig(projectRoot);
+  if (!cfg.capture) return;
+
+  const input = await readHookStdin();
+  const sessionId = input.session_id || input.sessionId || null;
+  const now = Date.now();
+
+  const statePath = resolve(projectRoot, '.moflo', 'continuity-state.json');
+  if (shouldThrottle(statePath, sessionId, now)) return;
+
+  const transcript = readTranscriptInfo(input.transcript_path || input.transcriptPath);
+  if (transcript.optOut) {
+    // User asked this session not to be remembered — record nothing, but stamp
+    // the throttle so we don't re-scan the transcript every turn.
+    writeThrottleState(statePath, sessionId, now);
+    return;
+  }
+
+  const gitState = readGitState(projectRoot);
+  const decisions = await readRecentDecisions(projectRoot, LEARNINGS_SAMPLE);
+
+  const content = scrubSecrets(
+    assembleDigestContent({ goal: transcript.goal, decisions, gitState }),
+  );
+  if (!content.trim()) {
+    writeThrottleState(statePath, sessionId, now);
+    return; // nothing substantive to remember
+  }
+
+  const metadata = buildDigestMetadata({ gitState, sessionId, endedAt: now });
+  const key = sessionId
+    ? `session-${sessionId}`
+    : `session-${gitState.branch || 'nobranch'}-${new Date(now).toISOString().slice(0, 10)}`;
+
+  try {
+    writeDigest(projectRoot, key, { content, metadata });
+    rotateDigests(projectRoot);
+    writeThrottleState(statePath, sessionId, now);
+  } catch (err) {
+    warn(`persist failed (${err && err.message ? err.message : String(err)})`);
+  }
+}
+
+const sub = process.argv[2];
+if (sub === 'capture') {
+  capture().catch((err) => warn(`failed (${err && err.message ? err.message : String(err)})`));
+} else {
+  warn(`unknown subcommand "${sub || ''}" (expected: capture)`);
+}