moflo 4.9.18 → 4.9.19

package/.claude/commands/simplify.md

@@ -34,20 +34,15 @@ Pick the smallest tier the diff genuinely fits.
 
 Critical-surface files (launcher, hooks, MCP wiring) raise the *care* of the agent prompt — sharper checklist, blast-radius framing — they do **not** automatically escalate to NORMAL. Risk-weighted ≠ headcount-weighted.
 
-## Phase 3: Route the model (skip for TRIVIAL)
+## Phase 3: Use the classifier's model (skip for TRIVIAL)
 
-Before spawning any Agent, ask the moflo router which model to use:
+The classifier returns the right model for the tier — no separate router call needed:
 
-```
-mcp__moflo__hooks_model-route — {
-  task: "Review N-line change in <files> for reuse, quality, efficiency",
-  preferCost: true
-}
-```
+- `sonnet` (default) — real logic edits, single agent or 3-agent fan-out.
+- `haiku` — mostly-relocation diffs (mechanical moves; pattern-matching beats deep reasoning).
+- `opus` — never returned. Code review is breadth-bound, not depth-bound; sonnet 3-way IS the high-effort tier.
 
-**Wording rules:** the router's complexity score is keyword-sensitive. Avoid `refactor`, `architect`, `audit`, `system`, `redesign`, `migrate` — those force opus even when scoring suggests sonnet. State LOC count, file count, and "review for reuse, quality, efficiency". Nothing more.
-
-**Hard rule for `/simplify`: opus is never correct.** Code review never needs Opus reasoning, even on critical surface. If the router returns `opus`, downgrade to `sonnet`. On router failure, default to `sonnet`. Comment trims and pure formatting → `haiku`.
+Pass the classifier's `model` field verbatim to Agent's `model` parameter. If you fell back to prose rules in Phase 2 (no classifier), default to `sonnet`.
 
 ## Phase 4: Validation pass (re-run after fixes from a prior simplify)
 
@@ -57,8 +52,11 @@ Escalate one tier (self-review → SMALL agent) only if the fix introduced a new
 
 ## Phase 5: Run the appropriate review
 
-### TRIVIAL / Validation
-Run the three category checks (reuse / quality / efficiency) yourself in one pass against the diff. Most TRIVIAL diffs are clean — confirm and exit. Budget: ~30 seconds, no Agent.
+### TRIVIAL
+Print one confirmation line (`simplify: TRIVIAL — N LOC, 1 file — stamped`) and exit. **Do not** walk the three-category check; the classifier already concluded the diff is below the review-value threshold. Budget: <5 seconds, no Agent.
+
+### Validation pass
+Run the three category checks against the post-fix diff in one pass. Most are clean — confirm and exit. Budget: ~30 seconds, no Agent.
 
 ### SMALL — one agent
 ```

package/.claude/helpers/gate.cjs

@@ -7,7 +7,7 @@ var cp = require('child_process');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -100,6 +100,79 @@ var EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE = /(?:^|[\\\/])(__tests__|__mocks__|tests?|
 // on purpose — those are inert for edit-reset (above) but not "documentation".
 var DOCS_ONLY_RE = /\.(md|markdown|txt|rst|adoc|html?|pdf|png|jpe?g|gif|svg|webp|ico|bmp)$/i;
 
+// Classifier-aware simplify gate skip. Returns a string reason if the gate
+// can be auto-passed, or null if /simplify must run. Uses simplify-classify.cjs
+// so the gate's "trivial" definition matches the skill's exactly.
+//
+// Two paths:
+//   1. snapshot path — /simplify ran earlier on this branch. Classify the diff
+//      between simplifySnapshotSha and current HEAD/working-tree. If TRIVIAL,
+//      the prior review still covers the branch — no re-run needed.
+//   2. baseline path — no snapshot (first time). Classify the entire branch
+//      diff vs merge-base. If TRIVIAL, the whole PR is below the threshold
+//      where /simplify provides value — auto-pass without ever invoking it.
+//
+// Fail-safe: any error (no classifier, no git, no merge-base) returns null,
+// which forces /simplify to run as today.
+function classifyForGateSkip(state) {
+  var classify;
+  try {
+    classify = require('./simplify-classify.cjs').classifyDiff;
+  } catch (e) { return null; }
+  if (typeof classify !== 'function') return null;
+
+  function tryClassify(diffText, label) {
+    try {
+      var dec = classify(diffText);
+      if (dec.tier === 'TRIVIAL') {
+        var loc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
+        return label + ' is TRIVIAL (' + loc + ' LOC, ' + (dec.stats.fileCount || 0) + ' file(s))';
+      }
+    } catch (e) { /* fall through */ }
+    return null;
+  }
+
+  function gitDiff(args) {
+    try {
+      return cp.execFileSync('git', args, {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 5000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 8 * 1024 * 1024
+      });
+    } catch (e) { return null; }
+  }
+
+  // Snapshot path: classify everything since /simplify last ran.
+  if (state.simplifySnapshotSha) {
+    var snapDiff = gitDiff(['diff', state.simplifySnapshotSha + '...HEAD']);
+    var workTreeA = gitDiff(['diff', 'HEAD']) || '';
+    if (snapDiff !== null) {
+      var combined = snapDiff + (workTreeA ? '\n' + workTreeA : '');
+      var hit = tryClassify(combined, 'delta since last /simplify');
+      if (hit) return hit;
+    }
+  }
+
+  // Baseline path: classify the whole branch vs merge-base.
+  var bases = ['origin/main', 'main', 'origin/master', 'master'];
+  for (var i = 0; i < bases.length; i++) {
+    var base;
+    try {
+      base = cp.execFileSync('git', ['merge-base', 'HEAD', bases[i]], {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+    } catch (e) { continue; }
+    if (!base) continue;
+    var branchDiff = gitDiff(['diff', base + '...HEAD']);
+    var workTreeB = gitDiff(['diff', 'HEAD']) || '';
+    if (branchDiff !== null) {
+      return tryClassify(branchDiff + (workTreeB ? '\n' + workTreeB : ''), 'branch diff');
+    }
+    break;
+  }
+  return null;
+}
+
 // Get the file list changed on the current branch vs the merge-base with origin/main
 // (falling back to local main). Returns an array of repo-relative paths, or null on
 // failure — in which case callers MUST fall through to the standard gate (fail-safe).
@@ -206,10 +279,19 @@ switch (command) {
   case 'record-skill-run': {
     if ((process.env.TOOL_INPUT_skill || '') === 'simplify') {
       var s = readState();
-      if (!s.simplifyRun) {
-        s.simplifyRun = true;
-        writeState(s);
-      }
+      var changed = false;
+      if (!s.simplifyRun) { s.simplifyRun = true; changed = true; }
+      // Snapshot HEAD so check-before-pr can classify delta-since-simplify and
+      // skip a redundant /simplify re-run when only trivial fixes followed.
+      // Non-fatal — gate falls through to current behaviour without the snapshot.
+      try {
+        var sha = cp.execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+          stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+        if (sha && s.simplifySnapshotSha !== sha) { s.simplifySnapshotSha = sha; changed = true; }
+      } catch (e) { /* no git or detached state — skip snapshot, gate still works */ }
+      if (changed) writeState(s);
     }
     break;
   }
@@ -249,6 +331,19 @@ switch (command) {
       break;
     }
     var s = readState();
+    // Classifier-aware skip: if delta-since-snapshot or whole-branch diff is
+    // TRIVIAL, satisfy the simplify gate silently. Reuses the same classifier
+    // the skill uses — same "trivial" definition, no drift. Same threshold that
+    // already maps to TRIVIAL=0 agents inside /simplify, so trusting it at the
+    // gate level is the same trust profile, just one decision earlier.
+    if (config.simplify_gate && !s.simplifyRun) {
+      var skipReason = classifyForGateSkip(s);
+      if (skipReason) {
+        s.simplifyRun = true;
+        writeState(s);
+        process.stdout.write('Simplify gate auto-passed: ' + skipReason + '\n');
+      }
+    }
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/simplify has not run since the last code edit');

package/.claude/helpers/simplify-classify.cjs

@@ -159,7 +159,10 @@ function decide(stats) {
     reasoning.push(
       `mostly relocation: ${stats.declAdded} decls added, ${stats.declRemoved} removed, net ${stats.netDecls >= 0 ? '+' : ''}${stats.netDecls}`,
     );
-    return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+    // Haiku is sufficient for mechanical moves: code already existed and worked,
+    // so review reduces to copy-paste-divergence / dead-after-move pattern checks
+    // — exactly haiku's strength. ~5x cheaper than sonnet on relocation-shape diffs.
+    return { tier: 'SMALL', model: 'haiku', agentCount: 1, reasoning, stats };
   }
 
   // Escalation triggers — any one trips NORMAL (3 agents).

package/.claude/skills/simplify/SKILL.md

@@ -42,13 +42,8 @@ Tier definitions the classifier encodes (for reference, not for re-derivation):
 
 Pick the **smallest tier** the diff genuinely fits. When in doubt, escalate one step (not two).
 
-### TRIVIAL — self-review, no agent spawn
-ALL of these must hold:
-- ≤10 net LOC changed (insertions + deletions, excluding pure whitespace)
-- Single file
-- No logic changes — only comments, formatting, renames of local vars, JSDoc, or string-literal edits
-- No new imports, no new exports, no new function/class declarations
-- No removed safety checks, error handlers, or guards
+### TRIVIAL — gate stamp, no review
+The classifier already proved the diff is below the threshold where review provides value (≤10 net LOC, single file, no declaration/import/export changes, no removed guards). **Stamp the gate with one line of confirmation and exit immediately.** Do not walk the three-category check yourself — the classifier IS the review at this tier, and at the gate level the classifier-aware skip (`bin/gate.cjs:classifyForGateSkip`) often satisfies the gate without invoking this skill at all.
 
 Examples that qualify: trimming a comment, fixing a typo in a log message, renaming a private helper, reformatting a single block.
 Examples that DON'T qualify: changing an `if` condition, reordering function args, deleting a try/catch.
@@ -88,14 +83,21 @@ Do **not** escalate to NORMAL on a validation pass. If the fix is so structural
 
 ## Phase 2.7: Model selection
 
-**Use the model the classifier returned** — always `sonnet` for `/simplify`. Opus is never correct here; the classifier enforces this. No router call needed; the classifier IS the router for this skill.
+**Use the model the classifier returned.** The classifier IS the router for this skill — no separate router call needed. Possible outputs:
+
+- `sonnet` (default) — real logic changes, single agent or three-agent fan-out.
+- `haiku` — mostly-relocation diffs (mechanical moves where pattern-matching beats deep reasoning, ~5x cheaper).
+- `opus` — never. Code review is breadth-bound, not depth-bound; the three-agent fan-out at sonnet is the high-effort tier.
 
-If you fell back to prose rules in Phase 2 (no classifier available), use `sonnet` unconditionally. Pass the model verbatim to Agent's `model` parameter.
+If you fell back to prose rules in Phase 2 (no classifier available), use `sonnet` unconditionally. Pass the classifier's `model` field verbatim to Agent's `model` parameter.
 
 ## Phase 3: Run the appropriate review
 
-### TRIVIAL / Validation: self-review
-Run the same three category checks (reuse / quality / efficiency) yourself, in one pass, against the diff. Most TRIVIAL and validation diffs will be clean — the goal is to confirm, not to fan out. If you find an issue, fix it; otherwise stamp clean. Total budget: ~30 seconds, no Agent calls. No router call needed.
+### TRIVIAL: stamp and exit
+The classifier proved the diff is below the review-value threshold. Print one confirmation line (e.g. `simplify: TRIVIAL — N LOC, 1 file — stamped`) and exit. **Do not** walk the three-category check; the classifier already concluded the answer is "clean." Budget: <5 seconds, no Agent calls.
+
+### Validation pass: confirm clean
+Run the three category checks (reuse / quality / efficiency) yourself, in one pass, against the post-fix diff. Most validation passes are clean — the goal is to confirm fixes didn't introduce new concerns, not to fan out. Budget: ~30 seconds, no Agent calls.
 
 ### SMALL: one agent (model from router)
 Launch a SINGLE Agent with subagent_type `reviewer`, passing the model returned by Phase 2.7's router call. Cap the agent's tool budget by being explicit:

package/bin/gate.cjs

@@ -7,7 +7,7 @@ var cp = require('child_process');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -100,6 +100,79 @@ var EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE = /(?:^|[\\\/])(__tests__|__mocks__|tests?|
 // on purpose — those are inert for edit-reset (above) but not "documentation".
 var DOCS_ONLY_RE = /\.(md|markdown|txt|rst|adoc|html?|pdf|png|jpe?g|gif|svg|webp|ico|bmp)$/i;
 
+// Classifier-aware simplify gate skip. Returns a string reason if the gate
+// can be auto-passed, or null if /simplify must run. Uses simplify-classify.cjs
+// so the gate's "trivial" definition matches the skill's exactly.
+//
+// Two paths:
+//   1. snapshot path — /simplify ran earlier on this branch. Classify the diff
+//      between simplifySnapshotSha and current HEAD/working-tree. If TRIVIAL,
+//      the prior review still covers the branch — no re-run needed.
+//   2. baseline path — no snapshot (first time). Classify the entire branch
+//      diff vs merge-base. If TRIVIAL, the whole PR is below the threshold
+//      where /simplify provides value — auto-pass without ever invoking it.
+//
+// Fail-safe: any error (no classifier, no git, no merge-base) returns null,
+// which forces /simplify to run as today.
+function classifyForGateSkip(state) {
+  var classify;
+  try {
+    classify = require('./simplify-classify.cjs').classifyDiff;
+  } catch (e) { return null; }
+  if (typeof classify !== 'function') return null;
+
+  function tryClassify(diffText, label) {
+    try {
+      var dec = classify(diffText);
+      if (dec.tier === 'TRIVIAL') {
+        var loc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
+        return label + ' is TRIVIAL (' + loc + ' LOC, ' + (dec.stats.fileCount || 0) + ' file(s))';
+      }
+    } catch (e) { /* fall through */ }
+    return null;
+  }
+
+  function gitDiff(args) {
+    try {
+      return cp.execFileSync('git', args, {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 5000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 8 * 1024 * 1024
+      });
+    } catch (e) { return null; }
+  }
+
+  // Snapshot path: classify everything since /simplify last ran.
+  if (state.simplifySnapshotSha) {
+    var snapDiff = gitDiff(['diff', state.simplifySnapshotSha + '...HEAD']);
+    var workTreeA = gitDiff(['diff', 'HEAD']) || '';
+    if (snapDiff !== null) {
+      var combined = snapDiff + (workTreeA ? '\n' + workTreeA : '');
+      var hit = tryClassify(combined, 'delta since last /simplify');
+      if (hit) return hit;
+    }
+  }
+
+  // Baseline path: classify the whole branch vs merge-base.
+  var bases = ['origin/main', 'main', 'origin/master', 'master'];
+  for (var i = 0; i < bases.length; i++) {
+    var base;
+    try {
+      base = cp.execFileSync('git', ['merge-base', 'HEAD', bases[i]], {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+    } catch (e) { continue; }
+    if (!base) continue;
+    var branchDiff = gitDiff(['diff', base + '...HEAD']);
+    var workTreeB = gitDiff(['diff', 'HEAD']) || '';
+    if (branchDiff !== null) {
+      return tryClassify(branchDiff + (workTreeB ? '\n' + workTreeB : ''), 'branch diff');
+    }
+    break;
+  }
+  return null;
+}
+
 // Get the file list changed on the current branch vs the merge-base with origin/main
 // (falling back to local main). Returns an array of repo-relative paths, or null on
 // failure — in which case callers MUST fall through to the standard gate (fail-safe).
@@ -206,10 +279,19 @@ switch (command) {
   case 'record-skill-run': {
     if ((process.env.TOOL_INPUT_skill || '') === 'simplify') {
       var s = readState();
-      if (!s.simplifyRun) {
-        s.simplifyRun = true;
-        writeState(s);
-      }
+      var changed = false;
+      if (!s.simplifyRun) { s.simplifyRun = true; changed = true; }
+      // Snapshot HEAD so check-before-pr can classify delta-since-simplify and
+      // skip a redundant /simplify re-run when only trivial fixes followed.
+      // Non-fatal — gate falls through to current behaviour without the snapshot.
+      try {
+        var sha = cp.execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+          stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+        if (sha && s.simplifySnapshotSha !== sha) { s.simplifySnapshotSha = sha; changed = true; }
+      } catch (e) { /* no git or detached state — skip snapshot, gate still works */ }
+      if (changed) writeState(s);
     }
     break;
   }
@@ -249,6 +331,19 @@ switch (command) {
       break;
     }
     var s = readState();
+    // Classifier-aware skip: if delta-since-snapshot or whole-branch diff is
+    // TRIVIAL, satisfy the simplify gate silently. Reuses the same classifier
+    // the skill uses — same "trivial" definition, no drift. Same threshold that
+    // already maps to TRIVIAL=0 agents inside /simplify, so trusting it at the
+    // gate level is the same trust profile, just one decision earlier.
+    if (config.simplify_gate && !s.simplifyRun) {
+      var skipReason = classifyForGateSkip(s);
+      if (skipReason) {
+        s.simplifyRun = true;
+        writeState(s);
+        process.stdout.write('Simplify gate auto-passed: ' + skipReason + '\n');
+      }
+    }
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/simplify has not run since the last code edit');

package/bin/simplify-classify.cjs

@@ -159,7 +159,10 @@ function decide(stats) {
     reasoning.push(
       `mostly relocation: ${stats.declAdded} decls added, ${stats.declRemoved} removed, net ${stats.netDecls >= 0 ? '+' : ''}${stats.netDecls}`,
     );
-    return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+    // Haiku is sufficient for mechanical moves: code already existed and worked,
+    // so review reduces to copy-paste-divergence / dead-after-move pattern checks
+    // — exactly haiku's strength. ~5x cheaper than sonnet on relocation-shape diffs.
+    return { tier: 'SMALL', model: 'haiku', agentCount: 1, reasoning, stats };
   }
 
   // Escalation triggers — any one trips NORMAL (3 agents).

package/dist/src/cli/commands/spell-credentials.js

@@ -0,0 +1,248 @@
+/**
+ * Spell Credentials CLI
+ *
+ * `moflo spell credentials list/set/unset/clear/passphrase` — manage the
+ * encrypted credential store the spell runner uses for unattended casts.
+ *
+ * Story #925 (epic #880).
+ */
+import { existsSync } from 'node:fs';
+import { output } from '../output.js';
+import { confirm, input } from '../prompt.js';
+import { CredentialStore, CredentialStoreError, MIN_PASSPHRASE_LENGTH, resolveCredentialFilePath, resolvePassphrase, } from '../spells/credentials/index.js';
+/**
+ * Build a CredentialStore using the runner's passphrase resolution.
+ * Returns null when no passphrase is available — caller surfaces the actionable error.
+ */
+function openStore() {
+    const filePath = resolveCredentialFilePath();
+    const passphrase = resolvePassphrase();
+    if (!passphrase)
+        return null;
+    try {
+        return new CredentialStore({ filePath, passphrase });
+    }
+    catch (err) {
+        output.printError(`Could not open credential store: ${err.message}`);
+        return null;
+    }
+}
+function noStoreError() {
+    output.printError('Credential store is locked.');
+    output.writeln('');
+    output.writeln('  Set MOFLO_CREDENTIALS_PASSPHRASE in your environment, or run:');
+    output.writeln('    flo spell credentials passphrase');
+    output.writeln('');
+    output.writeln('  to initialise a per-machine encryption key.');
+    return { success: false, exitCode: 1 };
+}
+const listCommand = {
+    name: 'list',
+    aliases: ['ls'],
+    description: 'List stored credential names (never values)',
+    action: async (ctx) => {
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        const meta = await store.list();
+        if (ctx.flags.format === 'json') {
+            output.printJson(meta);
+            return { success: true, data: meta };
+        }
+        if (meta.length === 0) {
+            output.printInfo('No credentials stored. Use `flo spell credentials set <name>` to add one.');
+            return { success: true };
+        }
+        output.writeln();
+        output.writeln(output.bold('Stored credentials'));
+        output.writeln();
+        output.printTable({
+            columns: [
+                { key: 'name', header: 'Name', width: 28 },
+                { key: 'description', header: 'Description', width: 35, format: (v) => v ? String(v) : '-' },
+                { key: 'updatedAt', header: 'Updated', width: 22, format: (v) => v ? new Date(String(v)).toLocaleString() : '-' },
+            ],
+            data: meta,
+        });
+        output.writeln();
+        output.printInfo(`${meta.length} credential${meta.length === 1 ? '' : 's'}`);
+        return { success: true, data: meta };
+    },
+};
+const setCommand = {
+    name: 'set',
+    description: 'Store a credential (prompts for the value with hidden input)',
+    options: [
+        { name: 'description', short: 'd', description: 'Optional description', type: 'string' },
+    ],
+    examples: [
+        { command: 'moflo spell credentials set GRAPH_ACCESS_TOKEN', description: 'Store the Graph token' },
+        { command: 'moflo spell credentials set SLACK_WEBHOOK_URL --description "OAP target"', description: 'With a description' },
+    ],
+    action: async (ctx) => {
+        const name = ctx.args[0];
+        if (!name) {
+            output.printError('Credential name is required (e.g. `flo spell credentials set TOKEN`)');
+            return { success: false, exitCode: 1 };
+        }
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        if (!ctx.interactive) {
+            output.printError('`set` requires an interactive TTY (the value is entered with hidden input).');
+            return { success: false, exitCode: 1 };
+        }
+        const value = await input({ message: `Value for ${name}:`, mask: true });
+        if (!value) {
+            output.printError('No value entered — credential not stored.');
+            return { success: false, exitCode: 1 };
+        }
+        const description = ctx.flags.description;
+        await store.store(name, value, description);
+        output.printSuccess(`Stored credential ${output.highlight(name)}.`);
+        return { success: true };
+    },
+};
+const unsetCommand = {
+    name: 'unset',
+    aliases: ['delete', 'rm'],
+    description: 'Remove a single credential',
+    action: async (ctx) => {
+        const name = ctx.args[0];
+        if (!name) {
+            output.printError('Credential name is required (e.g. `flo spell credentials unset TOKEN`)');
+            return { success: false, exitCode: 1 };
+        }
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        const removed = await store.delete(name);
+        if (!removed) {
+            output.printError(`Credential ${output.highlight(name)} not found.`);
+            return { success: false, exitCode: 1 };
+        }
+        output.printSuccess(`Removed credential ${output.highlight(name)}.`);
+        return { success: true };
+    },
+};
+const clearCommand = {
+    name: 'clear',
+    description: 'Remove all stored credentials',
+    options: [
+        { name: 'force', short: 'f', description: 'Skip confirmation', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        const meta = await store.list();
+        if (meta.length === 0) {
+            output.printInfo('No credentials to clear.');
+            return { success: true };
+        }
+        if (!ctx.flags.force) {
+            if (!ctx.interactive) {
+                output.printError('Refusing to clear without --force in non-interactive mode.');
+                return { success: false, exitCode: 1 };
+            }
+            const ok = await confirm({
+                message: `Delete all ${meta.length} stored credential${meta.length === 1 ? '' : 's'}?`,
+                default: false,
+            });
+            if (!ok) {
+                output.printInfo('Cancelled.');
+                return { success: true };
+            }
+        }
+        const removed = await store.clear();
+        output.printSuccess(`Removed ${removed} credential${removed === 1 ? '' : 's'}.`);
+        return { success: true };
+    },
+};
+const passphraseCommand = {
+    name: 'passphrase',
+    aliases: ['init', 'rotate'],
+    description: 'Initialise the credential store passphrase, or rotate an existing one',
+    action: async (ctx) => {
+        if (!ctx.interactive) {
+            output.printError('`passphrase` requires an interactive TTY.');
+            return { success: false, exitCode: 1 };
+        }
+        const filePath = resolveCredentialFilePath();
+        const exists = existsSync(filePath);
+        const minHint = `(min ${MIN_PASSPHRASE_LENGTH} chars)`;
+        if (!exists) {
+            const newPass = await input({ message: `Choose a passphrase ${minHint}:`, mask: true });
+            const confirmed = await input({ message: 'Confirm passphrase:', mask: true });
+            if (newPass !== confirmed) {
+                output.printError('Passphrases do not match.');
+                return { success: false, exitCode: 1 };
+            }
+            try {
+                const store = new CredentialStore({ filePath, passphrase: newPass });
+                // Force a salted file write so the chosen passphrase locks the store.
+                await store.store('__init__', 'init');
+                await store.delete('__init__');
+            }
+            catch (err) {
+                if (err instanceof CredentialStoreError && err.code === 'WEAK_PASSPHRASE') {
+                    output.printError(err.message);
+                    return { success: false, exitCode: 1 };
+                }
+                throw err;
+            }
+            output.printSuccess(`Initialised credential store at ${filePath}`);
+            output.printInfo('Set MOFLO_CREDENTIALS_PASSPHRASE in your environment to keep schedules running unattended.');
+            return { success: true };
+        }
+        const oldPass = await input({ message: 'Current passphrase:', mask: true });
+        const newPass = await input({ message: `New passphrase ${minHint}:`, mask: true });
+        const confirmed = await input({ message: 'Confirm new passphrase:', mask: true });
+        if (newPass !== confirmed) {
+            output.printError('Passphrases do not match.');
+            return { success: false, exitCode: 1 };
+        }
+        try {
+            const store = new CredentialStore({ filePath, passphrase: oldPass });
+            await store.rotate(oldPass, newPass);
+        }
+        catch (err) {
+            if (err instanceof CredentialStoreError) {
+                output.printError(err.message);
+                return { success: false, exitCode: 1 };
+            }
+            throw err;
+        }
+        output.printSuccess('Passphrase rotated. Update MOFLO_CREDENTIALS_PASSPHRASE if you set it in your environment.');
+        return { success: true };
+    },
+};
+export const spellCredentialsCommand = {
+    name: 'credentials',
+    aliases: ['creds'],
+    description: 'Manage the encrypted credential store used for unattended spell casts',
+    subcommands: [listCommand, setCommand, unsetCommand, clearCommand, passphraseCommand],
+    options: [],
+    examples: [
+        { command: 'moflo spell credentials list', description: 'Show stored credential names' },
+        { command: 'moflo spell credentials set GRAPH_TOKEN', description: 'Store a credential' },
+        { command: 'moflo spell credentials unset GRAPH_TOKEN', description: 'Remove a credential' },
+        { command: 'moflo spell credentials clear --force', description: 'Wipe all credentials' },
+    ],
+    action: async () => {
+        output.writeln();
+        output.writeln(output.bold('Spell Credentials'));
+        output.writeln();
+        output.writeln('Usage: moflo spell credentials <subcommand>');
+        output.writeln();
+        output.printList([
+            `${output.highlight('list')}        - List stored credential names`,
+            `${output.highlight('set')}         - Store a credential (hidden input)`,
+            `${output.highlight('unset')}       - Remove a single credential`,
+            `${output.highlight('clear')}       - Remove all stored credentials`,
+            `${output.highlight('passphrase')}  - Initialise or rotate the passphrase`,
+        ]);
+        return { success: true };
+    },
+};
+//# sourceMappingURL=spell-credentials.js.map

package/dist/src/cli/commands/spell.js

@@ -13,6 +13,7 @@ import { callMCPTool } from '../mcp-client.js';
 import { TOOL_SPELL_CAST, TOOL_SPELL_LIST, TOOL_SPELL_STATUS, TOOL_SPELL_CANCEL, TOOL_SPELL_TEMPLATE, } from '../mcp-tools/tool-names.js';
 import { formatStatus, handleMCPError } from '../services/cli-formatters.js';
 import { scheduleCommand } from './spell-schedule.js';
+import { spellCredentialsCommand } from './spell-credentials.js';
 import { loadSpellEngine } from '../services/engine-loader.js';
 // Re-export formatStatus as formatStageStatus for table column references
 const formatStageStatus = formatStatus;
@@ -587,7 +588,7 @@ export const spellCommand = {
     name: 'spell',
     aliases: ['workflow'],
     description: 'Spell casting and management',
-    subcommands: [castCommand, validateCommand, listCommand, statusCommand, stopCommand, templateCommand, scheduleCommand],
+    subcommands: [castCommand, validateCommand, listCommand, statusCommand, stopCommand, templateCommand, scheduleCommand, spellCredentialsCommand],
     options: [],
     examples: [
         { command: 'moflo spell cast -n development', description: 'Cast spell by name' },
@@ -609,8 +610,9 @@ export const spellCommand = {
             `${output.highlight('list')}      - List spells (grimoire + casts)`,
             `${output.highlight('status')}    - Show spell status`,
             `${output.highlight('stop')}      - Dispel a running spell`,
-            `${output.highlight('template')}  - Browse grimoire templates`,
-            `${output.highlight('schedule')}  - Manage scheduled spells`,
+            `${output.highlight('template')}    - Browse grimoire templates`,
+            `${output.highlight('schedule')}    - Manage scheduled spells`,
+            `${output.highlight('credentials')} - Manage stored secrets for unattended casts`,
         ]);
         output.writeln();
         output.writeln('Run "moflo spell <subcommand> --help" for more info');

package/dist/src/cli/services/moflo-paths.js

@@ -19,6 +19,7 @@
  * `cli/services/cherry-pick-learnings.ts` and is dynamically imported from
  * the compiled `dist/` by the launcher.
  */
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 export const MOFLO_DIR = '.moflo';
 /** Canonical memory DB filename (post-#727). Lives at `<root>/.moflo/moflo.db`. */
@@ -39,6 +40,10 @@ export const LEGACY_MEMORY_DB_BAK_SUFFIX = '.bak';
 export function mofloDir(projectRoot) {
     return join(projectRoot, MOFLO_DIR);
 }
+/** User-scope MoFlo state dir: `~/.moflo`. Holds credentials and other per-machine state. */
+export function mofloHomeDir() {
+    return join(homedir(), MOFLO_DIR);
+}
 export function legacyClaudeFlowDir(projectRoot) {
     return join(projectRoot, LEGACY_CLAUDE_FLOW_DIR);
 }

package/dist/src/cli/spells/commands/prompt-command.js

@@ -46,6 +46,10 @@ export const promptCommand = {
                 type: 'number',
                 description: 'Used when default resolves to empty/null — produces ISO timestamp N days ago',
             },
+            saveAs: {
+                type: 'string',
+                description: 'Persist the response under this name in the credential store; later casts read it back without prompting',
+            },
         },
         required: ['message'],
     },
@@ -65,11 +69,41 @@ export const promptCommand = {
         if (config.fallbackDaysAgo !== undefined && typeof config.fallbackDaysAgo !== 'number') {
             errors.push({ path: 'fallbackDaysAgo', message: 'fallbackDaysAgo must be a number' });
         }
+        if (config.saveAs !== undefined && typeof config.saveAs !== 'string') {
+            errors.push({ path: 'saveAs', message: 'saveAs must be a string' });
+        }
+        if (typeof config.saveAs === 'string' && config.saveAs.trim().length === 0) {
+            errors.push({ path: 'saveAs', message: 'saveAs cannot be empty' });
+        }
         return { valid: errors.length === 0, errors };
     },
     async execute(config, context) {
         const start = Date.now();
         const message = interpolateString(config.message, context);
+        const saveAs = config.saveAs?.trim();
+        if (saveAs) {
+            try {
+                const stored = await context.credentials.get(saveAs);
+                if (typeof stored === 'string' && stored.length > 0) {
+                    return {
+                        success: true,
+                        data: {
+                            message,
+                            options: config.options ?? null,
+                            outputVar: config.outputVar ?? 'response',
+                            response: stored,
+                            default: '',
+                            interactive: false,
+                            fromStore: true,
+                        },
+                        duration: Date.now() - start,
+                    };
+                }
+            }
+            catch {
+                // Store unavailable — fall through to normal prompt path.
+            }
+        }
         // Interpolate default — pure-ref interpolation may yield null; tolerate it.
         let interpolatedDefault = null;
         if (typeof config.default === 'string') {
@@ -96,6 +130,15 @@ export const promptCommand = {
                 lock.release();
             }
         }
+        // Best-effort persist — a failed save shouldn't fail a cast that already has a working answer.
+        if (saveAs && interactive && response) {
+            try {
+                await context.credentials.store(saveAs, response);
+            }
+            catch (err) {
+                console.warn(`[moflo:credentials] could not persist "${saveAs}": ${err.message}`);
+            }
+        }
         return {
             success: true,
             data: {
@@ -105,6 +148,7 @@ export const promptCommand = {
                 response,
                 default: effectiveDefault,
                 interactive,
+                fromStore: false,
             },
             duration: Date.now() - start,
         };
@@ -116,6 +160,7 @@ export const promptCommand = {
             { name: 'outputVar', type: 'string' },
             { name: 'default', type: 'string', description: 'Effective default after fallback chain' },
             { name: 'interactive', type: 'boolean', description: 'Whether the user was actually prompted' },
+            { name: 'fromStore', type: 'boolean', description: 'True when the response was returned from the credential store' },
         ];
     },
 };

package/dist/src/cli/spells/core/prerequisite-checker.js

@@ -151,17 +151,25 @@ export function formatPrerequisiteErrors(results) {
         return '';
     const lines = ['Missing prerequisites:'];
     for (const f of failed) {
-        lines.push(`  - ${f.name}: ${f.installHint}`);
-        if (f.url)
-            lines.push(`    ${f.url}`);
+        appendPrereqLine(lines, f.name, f.installHint, f.url);
     }
     return lines.join('\n');
 }
+function appendPrereqLine(lines, name, hint, url) {
+    const hintSuffix = hint ? `: ${hint}` : '';
+    lines.push(`  - ${name}${hintSuffix}`);
+    if (url)
+        lines.push(`    ${url}`);
+}
 /**
- * Evaluate all prereqs. On a TTY, prompts the user for unmet env-type prereqs
- * whose spec opted into `promptOnMissing`, writes answers into process.env,
- * then re-checks. Non-TTY calls and non-promptable unmet prereqs short-circuit
- * to a single formatted failure report.
+ * Evaluate all prereqs. Resolution chain for env-type prereqs:
+ *   1. process.env[key] already set → satisfied.
+ *   2. credentials.get(key) returns a value → write to process.env, satisfied.
+ *   3. TTY interactive → prompt → write to process.env AND credentials.store.
+ *   4. Non-TTY or no credentials → fail fast with `errorCode: 'MISSING_CREDENTIAL'`.
+ *
+ * Non-env prereqs (`command`, `file`) bypass the credential chain and surface
+ * through the standard "Missing prerequisites" path.
  */
 export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
     if (prerequisites.length === 0) {
@@ -170,22 +178,58 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
     const interactive = options.interactive
         ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
     const log = options.log ?? ((line) => console.log(line));
+    const credentials = options.credentials;
     const initial = await checkPrerequisites(prerequisites);
-    const unmet = prerequisites.filter((_, i) => !initial[i].satisfied);
-    if (unmet.length === 0) {
+    const unmetIndices = initial.flatMap((r, i) => r.satisfied ? [] : [i]);
+    if (unmetIndices.length === 0) {
         return { ok: true, resolvedNames: [] };
     }
-    const promptable = unmet.filter(p => interactive && p.promptOnMissing === true && typeof p.envKey === 'string');
+    // Pull env-type prereqs from the store in parallel — each resolved index
+    // lets us skip a re-check of the cheap env detector.
+    const resolvedFromStoreNames = [];
+    const storeResolved = new Set();
+    if (credentials) {
+        await Promise.all(unmetIndices.map(async (i) => {
+            const prereq = prerequisites[i];
+            if (!prereq.envKey)
+                return;
+            const stored = await credentials.get(prereq.envKey);
+            if (typeof stored === 'string' && stored.length > 0) {
+                process.env[prereq.envKey] = stored;
+                storeResolved.add(i);
+                resolvedFromStoreNames.push(prereq.name);
+            }
+        }));
+    }
+    const stillUnmetIdx = unmetIndices.filter(i => !storeResolved.has(i));
+    if (stillUnmetIdx.length === 0) {
+        return { ok: true, resolvedNames: resolvedFromStoreNames };
+    }
+    const stillUnmet = stillUnmetIdx.map(i => prerequisites[i]);
+    const promptable = stillUnmet.filter(p => interactive && p.promptOnMissing === true && typeof p.envKey === 'string');
     if (!interactive || promptable.length === 0) {
+        const promptableEnvKeys = stillUnmet
+            .filter(p => p.promptOnMissing === true && typeof p.envKey === 'string')
+            .map(p => p.envKey);
+        if (promptableEnvKeys.length > 0) {
+            return {
+                ok: false,
+                message: formatMissingCredentialMessage(promptableEnvKeys, stillUnmet),
+                resolvedNames: resolvedFromStoreNames,
+                errorCode: 'MISSING_CREDENTIAL',
+                missingCredentials: promptableEnvKeys,
+            };
+        }
         return {
             ok: false,
-            message: formatPrerequisiteErrors(initial),
-            resolvedNames: [],
+            message: formatPrerequisiteErrors(stillUnmetIdx.map(i => initial[i])),
+            resolvedNames: resolvedFromStoreNames,
         };
     }
-    printPreflightBanner(log, unmet.length);
+    printPreflightBanner(log, stillUnmet.length);
     const promptLine = options.promptLine ?? readLineFromStdin;
-    const resolvedNames = [];
+    const promptedNames = [];
+    const promptableSet = new Set(promptable);
     const lock = acquireTTYLock();
     try {
         for (const prereq of promptable) {
@@ -193,7 +237,7 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
                 return {
                     ok: false,
                     message: 'Prerequisite resolution aborted',
-                    resolvedNames,
+                    resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
                 };
             }
             if (prereq.description)
@@ -209,37 +253,56 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
                 return {
                     ok: false,
                     message: `Prerequisite "${prereq.name}" prompt failed: ${err.message}`,
-                    resolvedNames,
+                    resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
                 };
             }
             if (!answer || answer.length === 0) {
                 return {
                     ok: false,
                     message: `Prerequisite "${prereq.name}" was not provided`,
-                    resolvedNames,
+                    resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
                 };
             }
             if (prereq.envKey) {
                 process.env[prereq.envKey] = answer;
+                if (credentials) {
+                    try {
+                        await credentials.store(prereq.envKey, answer);
+                    }
+                    catch (err) {
+                        log(`  (could not persist credential "${prereq.envKey}": ${err.message})`);
+                    }
+                }
             }
-            resolvedNames.push(prereq.name);
+            promptedNames.push(prereq.name);
         }
     }
     finally {
         lock.release();
     }
-    // Re-check everything — any still unmet (e.g. command/file prereqs that
-    // couldn't be resolved via prompt) fail now with the up-to-date report.
-    const rerun = await checkPrerequisites(prerequisites);
-    const stillUnmet = rerun.filter(r => !r.satisfied);
-    if (stillUnmet.length > 0) {
+    // Anything in stillUnmet that wasn't promptable (typically command/file
+    // prereqs) is still broken — carry forward the initial detector result.
+    const unfixableIdx = stillUnmetIdx.filter(i => !promptableSet.has(prerequisites[i]));
+    if (unfixableIdx.length > 0) {
         return {
             ok: false,
-            message: formatPrerequisiteErrors(rerun),
-            resolvedNames,
+            message: formatPrerequisiteErrors(unfixableIdx.map(i => initial[i])),
+            resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
         };
     }
-    return { ok: true, resolvedNames };
+    return { ok: true, resolvedNames: [...resolvedFromStoreNames, ...promptedNames] };
+}
+function formatMissingCredentialMessage(envKeys, prereqs) {
+    const lines = ['Missing credentials (cannot prompt — non-interactive run):'];
+    for (const key of envKeys) {
+        const prereq = prereqs.find(p => p.envKey === key);
+        const label = `${prereq?.name ?? key} (${key})`;
+        appendPrereqLine(lines, label, prereq?.installHint, prereq?.url);
+    }
+    lines.push('');
+    lines.push('Prime these by casting the spell once interactively, or run:');
+    lines.push('  flo spell credentials set <name>');
+    return lines.join('\n');
 }
 function printPreflightBanner(log, unmetCount) {
     log('');

package/dist/src/cli/spells/core/runner.js

@@ -99,17 +99,18 @@ export class SpellCaster {
                 }
             }
         }
-        // Pre-flight prerequisite checks — walks YAML + step-command sources,
-        // prompts on a TTY for unmet env-type prereqs (issue #460).
+        // Pre-flight prerequisite checks (issue #460) — walks YAML + step-command
+        // sources, pulls from credential store, prompts on TTY, persists answers.
         if (!options.dryRun) {
             const prerequisites = collectPrerequisites(definition, this.registry);
             if (prerequisites.length > 0) {
                 const resolution = await resolveUnmetPrerequisites(prerequisites, {
                     abortSignal: options.signal,
+                    credentials: this.credentials,
                 });
                 if (!resolution.ok) {
                     return this.failureResult(spellId, startTime, [{
-                            code: 'PREREQUISITES_FAILED',
+                            code: resolution.errorCode ?? 'PREREQUISITES_FAILED',
                             message: resolution.message ?? 'Prerequisites failed',
                         }], definition.name);
                 }

package/dist/src/cli/spells/credentials/credential-store.js

@@ -20,6 +20,8 @@ const SALT_BYTES = 32;
 const KEY_BYTES = 32;
 const PBKDF2_ITERATIONS = 100_000;
 const PBKDF2_DIGEST = 'sha512';
+/** User-typeable floor for any passphrase that protects the store. */
+export const MIN_PASSPHRASE_LENGTH = 8;
 // ============================================================================
 // Encryption Helpers
 // ============================================================================
@@ -64,8 +66,8 @@ export class CredentialStore {
      * Derives the encryption key and loads existing data.
      */
     unlock(passphrase) {
-        if (passphrase.length < 8) {
-            throw new CredentialStoreError('Passphrase must be at least 8 characters', 'WEAK_PASSPHRASE');
+        if (passphrase.length < MIN_PASSPHRASE_LENGTH) {
+            throw new CredentialStoreError(`Passphrase must be at least ${MIN_PASSPHRASE_LENGTH} characters`, 'WEAK_PASSPHRASE');
         }
         this.data = this.readFile();
         const salt = Buffer.from(this.data.salt, 'hex');
@@ -132,6 +134,20 @@ export class CredentialStore {
         this.writeFile(this.data);
         return true;
     }
+    /**
+     * Remove every credential in a single write — preferred over a delete loop
+     * because each `delete()` rewrites the entire encrypted file.
+     * Returns the number of credentials removed.
+     */
+    async clear() {
+        this.ensureUnlocked();
+        const count = Object.keys(this.data.credentials).length;
+        if (count === 0)
+            return 0;
+        this.data.credentials = {};
+        this.writeFile(this.data);
+        return count;
+    }
     /**
      * List credential metadata (names + descriptions, never values).
      */
@@ -168,8 +184,8 @@ export class CredentialStore {
      * and derived key, re-encrypts everything, and writes atomically.
      */
     async rotate(oldPassphrase, newPassphrase) {
-        if (newPassphrase.length < 8) {
-            throw new CredentialStoreError('Passphrase must be at least 8 characters', 'WEAK_PASSPHRASE');
+        if (newPassphrase.length < MIN_PASSPHRASE_LENGTH) {
+            throw new CredentialStoreError(`Passphrase must be at least ${MIN_PASSPHRASE_LENGTH} characters`, 'WEAK_PASSPHRASE');
         }
         // Verify old passphrase by unlocking with it
         const fileData = this.readFile();

package/dist/src/cli/spells/credentials/default-store.js

@@ -0,0 +1,126 @@
+/**
+ * Default Credential Store
+ *
+ * Singleton `CredentialAccessor` wired into the runner factory, MCP bridge,
+ * and daemon executor so spells persist secrets between casts.
+ *
+ * Passphrase resolution: `MOFLO_CREDENTIALS_PASSPHRASE` env var, else an
+ * auto-generated `~/.moflo/credentials.key` (32 random bytes hex, mode
+ * 0o600) created on first need. The auto-key gives zero-config at-rest
+ * encryption — the threat model matches `~/.aws/credentials`: filesystem
+ * read by an attacker compromises the store either way.
+ *
+ * Failures degrade to `lockedNoopAccessor` (returns undefined / no-op
+ * persists) so the spell engine never crashes on a missing or unreadable
+ * credentials path.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CredentialStore, MIN_PASSPHRASE_LENGTH } from './credential-store.js';
+import { mofloHomeDir } from '../../services/moflo-paths.js';
+const KEY_BYTES = 32;
+/** 64 hex chars from `KEY_BYTES`; floor of 16 catches truncation/corruption. */
+const KEY_FILE_MIN_HEX_LENGTH = 16;
+export const DEFAULT_CREDENTIALS_FILE = join(mofloHomeDir(), 'credentials.json');
+export const DEFAULT_CREDENTIALS_KEY_FILE = join(mofloHomeDir(), 'credentials.key');
+let cached = null;
+/**
+ * Resolve the singleton default credential store. Returns an unlocked
+ * `CredentialStore` when a passphrase is available, otherwise a locked
+ * no-op accessor. Never throws.
+ */
+export function getDefaultCredentialStore(options = {}) {
+    if (cached)
+        return cached;
+    const filePath = resolveCredentialFilePath(options.filePath);
+    const passphrase = resolvePassphrase(options.passphrase, options.keyFilePath);
+    let accessor;
+    if (passphrase) {
+        try {
+            accessor = new CredentialStore({ filePath, passphrase });
+        }
+        catch (err) {
+            console.warn(`[moflo:credentials] store unavailable: ${err.message}`);
+            accessor = lockedNoopAccessor;
+        }
+    }
+    else {
+        accessor = lockedNoopAccessor;
+    }
+    cached = accessor;
+    return accessor;
+}
+/** Reset the cached singleton — used by tests and CLI subcommands. */
+export function resetDefaultCredentialStore() {
+    cached = null;
+}
+/** Resolve the credentials JSON path (override → env → default). */
+export function resolveCredentialFilePath(explicit) {
+    return explicit ?? process.env.MOFLO_CREDENTIALS_FILE ?? DEFAULT_CREDENTIALS_FILE;
+}
+/** Resolve the key file path (override → env → default). */
+export function resolveKeyFilePath(explicit) {
+    return explicit ?? process.env.MOFLO_CREDENTIALS_KEY_FILE ?? DEFAULT_CREDENTIALS_KEY_FILE;
+}
+/**
+ * Resolve a passphrase from explicit override, `MOFLO_CREDENTIALS_PASSPHRASE`,
+ * or the auto-generated key file. Returns `undefined` when no path yields a
+ * usable value (locked-store mode).
+ */
+export function resolvePassphrase(explicit, keyFilePathOverride) {
+    if (explicit)
+        return explicit;
+    const envPass = process.env.MOFLO_CREDENTIALS_PASSPHRASE;
+    if (envPass && envPass.length >= MIN_PASSPHRASE_LENGTH)
+        return envPass;
+    return resolveKeyFilePassphrase(keyFilePathOverride);
+}
+function resolveKeyFilePassphrase(override) {
+    const keyPath = resolveKeyFilePath(override);
+    try {
+        let content = null;
+        try {
+            content = readFileSync(keyPath, 'utf-8').trim();
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+        if (content !== null) {
+            if (content.length >= KEY_FILE_MIN_HEX_LENGTH)
+                return content;
+            // Refuse to regenerate over a corrupt key when credentials exist —
+            // a fresh key would silently invalidate every stored secret.
+            const credPath = join(dirname(keyPath), 'credentials.json');
+            try {
+                readFileSync(credPath);
+                console.warn(`[moflo:credentials] key file at ${keyPath} is corrupt; refusing to regenerate while ${credPath} exists`);
+                return undefined;
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT')
+                    throw err;
+            }
+        }
+        mkdirSync(dirname(keyPath), { recursive: true });
+        const generated = randomBytes(KEY_BYTES).toString('hex');
+        writeFileSync(keyPath, generated, { encoding: 'utf-8', mode: 0o600 });
+        // chmod after write in case the create mode was masked by umask.
+        try {
+            chmodSync(keyPath, 0o600);
+        }
+        catch { /* best-effort on Windows */ }
+        return generated;
+    }
+    catch (err) {
+        console.warn(`[moflo:credentials] could not read/create key file: ${err.message}`);
+        return undefined;
+    }
+}
+export const lockedNoopAccessor = {
+    async get() { return undefined; },
+    async has() { return false; },
+    async store() { },
+};
+//# sourceMappingURL=default-store.js.map

package/dist/src/cli/spells/credentials/index.js

@@ -0,0 +1,6 @@
+/**
+ * Credentials barrel — public surface of the credential subsystem.
+ */
+export { CredentialStore, CredentialStoreError, MIN_PASSPHRASE_LENGTH, } from './credential-store.js';
+export { getDefaultCredentialStore, resetDefaultCredentialStore, resolveCredentialFilePath, resolveKeyFilePath, resolvePassphrase, lockedNoopAccessor, DEFAULT_CREDENTIALS_FILE, DEFAULT_CREDENTIALS_KEY_FILE, } from './default-store.js';
+//# sourceMappingURL=index.js.map

package/dist/src/cli/spells/factory/runner-bridge.js

@@ -10,6 +10,7 @@
  */
 import { loadSandboxConfigFromProject } from '../core/platform-sandbox.js';
 import { createRunner, runSpellFromContent } from './runner-factory.js';
+import { getDefaultCredentialStore } from '../credentials/default-store.js';
 /**
  * Resolve sandbox config: prefer caller-supplied; fall back to auto-loading
  * from moflo.yaml at projectRoot. Returns undefined when neither is available
@@ -36,13 +37,14 @@ export async function bridgeRunSpell(content, sourceFile, args, options = {}) {
     activeSpells.set(spellId, controller);
     try {
         const sandboxConfig = await resolveSandbox(options.sandboxConfig, options.projectRoot);
+        const credentials = options.credentials ?? getDefaultCredentialStore();
         const result = await runSpellFromContent(content, sourceFile, {
             spellId,
             args,
             dryRun: options.dryRun,
             signal: controller.signal,
             memory: options.memory,
-            credentials: options.credentials,
+            credentials,
             ...(options.projectRoot ? { projectRoot: options.projectRoot } : {}),
             ...(sandboxConfig ? { sandboxConfig } : {}),
         });
@@ -61,7 +63,8 @@ export async function bridgeExecuteSpell(definition, args, options = {}) {
     activeSpells.set(spellId, controller);
     try {
         const sandboxConfig = await resolveSandbox(options.sandboxConfig, options.projectRoot);
-        const runner = createRunner({ memory: options.memory, credentials: options.credentials });
+        const credentials = options.credentials ?? getDefaultCredentialStore();
+        const runner = createRunner({ memory: options.memory, credentials });
         return await runner.run(definition, args, {
             spellId,
             signal: controller.signal,

package/dist/src/cli/spells/factory/runner-factory.js

@@ -14,6 +14,7 @@ import { validateSpellDefinition } from '../schema/validator.js';
 import { SpellConnectorRegistry } from '../registry/connector-registry.js';
 import { loadSandboxConfigFromProject } from '../core/platform-sandbox.js';
 import { errorDetail } from '../../shared/utils/error-detail.js';
+import { getDefaultCredentialStore } from '../credentials/default-store.js';
 // ============================================================================
 // Factory
 // ============================================================================
@@ -33,7 +34,7 @@ export function createRunner(options = {}) {
     if (options.stepDirs?.length) {
         registry.loadFromDirectories(options.stepDirs);
     }
-    const credentials = options.credentials ?? noopCredentials;
+    const credentials = options.credentials ?? getDefaultCredentialStore();
     const memory = options.memory ?? noopMemory;
     // Auto-register shipped connectors into the connector registry
     const connectorRegistry = options.connectorRegistry ?? new SpellConnectorRegistry();
@@ -92,9 +93,10 @@ export async function runSpellFromContent(content, sourceFile, options = {}) {
 // ============================================================================
 // Noop Accessors (for standalone usage without full CLI context)
 // ============================================================================
-const noopCredentials = {
+export const noopCredentials = {
     async get() { return undefined; },
     async has() { return false; },
+    async store() { },
 };
 export const noopMemory = {
     async read() { return null; },

package/dist/src/cli/spells/index.js

@@ -49,7 +49,7 @@ export { buildPausedState, persistPausedState, resumeSpell, cleanupStalePaused,
 // ============================================================================
 // Credential Store
 // ============================================================================
-export { CredentialStore, CredentialStoreError, } from './credentials/credential-store.js';
+export { CredentialStore, CredentialStoreError, getDefaultCredentialStore, resetDefaultCredentialStore, lockedNoopAccessor, } from './credentials/index.js';
 // ============================================================================
 // Spell Registry (abbreviation lookup + list/info)
 // ============================================================================

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.18';
+export const VERSION = '4.9.19';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.18",
+  "version": "4.9.19",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -81,7 +81,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.17",
+    "moflo": "^4.9.18",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"