moflo 4.8.56 → 4.8.58

package/.claude/skills/connector-builder/SKILL.md

@@ -414,6 +414,46 @@ export const <type>Command: StepCommand<<Type>StepConfig> = {
     ];
   },
 
+  // Optional: runtime preflight checks — run BEFORE any step executes.
+  // Use for validating runtime state (issue open, service reachable, etc).
+  // CRITICAL: the `reason` string IS the message the end user sees.
+  // Write it in plain English. State the problem AND the fix. No tool
+  // jargon, no exit codes, no internal identifiers.
+  //
+  // Default severity is 'fatal' (abort on failure). Set severity: 'warning'
+  // + resolutions when the user can safely choose how to proceed; in
+  // interactive runs they'll be prompted, in non-interactive runs warnings
+  // behave like fatals.
+  //
+  // preflight: [
+  //   {
+  //     name: '<service> reachable',
+  //     severity: 'fatal',
+  //     check: async (config, ctx) => {
+  //       const ok = await ping(config.endpoint);
+  //       if (ok) return { passed: true };
+  //       return {
+  //         passed: false,
+  //         reason: `Can't reach ${config.endpoint}. Check your network connection or the service URL in your spell config.`,
+  //       };
+  //     },
+  //   },
+  //   {
+  //     name: 'local cache fresh',
+  //     severity: 'warning',
+  //     resolutions: [
+  //       { label: 'Refresh the cache now', command: '<type>-cli cache refresh' },
+  //       { label: 'Continue with stale cache' },
+  //     ],
+  //     check: async (config) => {
+  //       const stale = await isCacheStale(config.endpoint);
+  //       return stale
+  //         ? { passed: false, reason: 'Your local cache is more than 24 hours old and may produce outdated results.' }
+  //         : { passed: true };
+  //     },
+  //   },
+  // ],
+
   // Optional: rollback on failure
   // async rollback(config, context) { /* undo side effects */ },
 };
@@ -421,6 +461,18 @@ export const <type>Command: StepCommand<<Type>StepConfig> = {
 
 Alternatively, use the `createStepCommand()` factory from `src/modules/spells/src/commands/create-step-command.ts` for compile-time type safety.
 
+#### Preflight `reason` strings — write for humans
+
+When your step declares `preflight` checks, the `reason` string returned on failure is shown verbatim to end users as the error message. Treat it as user-facing copy:
+
+- Plain English, no command names, exit codes, or internal identifiers.
+- State BOTH the problem and the fix.
+- Assume a non-technical reader.
+
+Good: `"You're not signed in to GitHub. Run: gh auth login"`
+Bad: `"gh auth status exited with code 1"` — leaks implementation detail
+Bad: `"auth check failed"` — tells the user nothing actionable
+
 ### Step 3: Generate Step Command Test
 
 Create at `tests/packages/spells/commands/<type>-command.test.ts`:

package/.claude/skills/spell-builder/SKILL.md

@@ -136,6 +136,65 @@ Permissions for step "analyze-logs":
 - `{credentials.NAME}` — references a credential (resolved at runtime)
 - `{stepId.outputKey}` — references output from a previous step
 
+#### REQUIRED: Preflight checks with human-readable hints
+
+When a step depends on runtime state the user controls (clean git tree, logged-in CLI, reachable host, etc.), declare a `preflight:` block so the spell fails fast with a helpful message BEFORE any side effects occur.
+
+**Every preflight MUST include a `hint:` field.** The hint is what the end user will see when the check fails. Without it they get raw shell output (`command "git diff --quiet" exited with 1, expected 0`), which looks like a bug in the spell engine.
+
+Good hints:
+- Speak in plain English (no command names, exit codes, or tool jargon).
+- State the problem AND the fix in one or two sentences.
+- Assume a non-technical reader.
+
+```yaml
+steps:
+  - id: create-branch
+    type: bash
+    preflight:
+      - name: "working tree clean (tracked changes)"
+        command: "git diff --quiet"
+        hint: "You have uncommitted changes to tracked files. Commit them or stash them (git stash) before running this spell."
+      - name: "gh cli authenticated"
+        command: "gh auth status"
+        hint: "The GitHub CLI isn't signed in. Run: gh auth login"
+    config:
+      command: "git checkout -b feature/new"
+```
+
+Bad hint (don't do this):
+```yaml
+hint: "git diff --quiet failed with exit code 1"   # leaks command name + exit code
+hint: "Precondition violated"                       # tells user nothing actionable
+```
+
+Preflights with no `hint` still work but produce unfriendly default output — flag this to the user as a quality issue before saving the spell.
+
+##### Fatal vs warning severity
+
+By default every preflight is `severity: fatal` — if it fails, the spell aborts. Some preflights are better expressed as `severity: warning`: the user gets to choose how to handle the problem, and the spell continues if they pick a resolution.
+
+Use `warning` ONLY when:
+- The underlying problem has a safe, one-step fix the user might reasonably want to apply.
+- Proceeding is viable either way — the step itself is robust to the condition.
+
+Warning preflights MUST declare `resolutions:` — a list of options the user can pick from. Each resolution has a `label` and an optional `command` to run before continuing. If `command` is omitted, picking the resolution just proceeds (useful for "I'll handle it myself").
+
+```yaml
+preflight:
+  - name: "working tree clean (tracked changes)"
+    command: "git diff --quiet"
+    severity: "warning"
+    hint: "You have uncommitted changes. If you want them carried onto the new branch, pick 'Stash and carry over'."
+    resolutions:
+      - label: "Stash changes and carry them onto the new branch"
+        command: "git stash push --include-untracked --message 'pre-spell autostash'"
+      - label: "Commit changes to the current branch first, then continue"
+        command: "git commit -am 'wip: pre-spell snapshot'"
+```
+
+In non-interactive contexts (CI, daemons, scheduled spells) warnings automatically behave like fatals, because there is no one to prompt. Don't use `warning` as a way to silently ignore a problem — if ignoring it is always safe, the check shouldn't be there.
+
 ### Step 4: Generate the Spell YAML
 
 Assemble the definition into YAML format following this structure:
@@ -407,6 +466,13 @@ arguments:
 steps:
   - id: scan-deps
     type: bash
+    preflight:
+      - name: "npm available"
+        command: "npm --version"
+        hint: "npm isn't installed or isn't on your PATH. Install Node.js from https://nodejs.org and try again."
+      - name: "target directory exists"
+        command: "test -d \"{args.target}\""
+        hint: "The directory you passed as --target doesn't exist. Check the path and try again."
     config:
       command: "npm audit --json"
       cwd: "{args.target}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.56",
+  "version": "4.8.58",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",
@@ -111,7 +111,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.19.37",
     "eslint": "^8.0.0",
-    "moflo": "^4.8.56-rc.20",
+    "moflo": "^4.8.57",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/src/modules/cli/dist/src/commands/epic.js

@@ -16,7 +16,8 @@ import { execSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isEpicIssue, fetchEpicIssue, extractStories, enrichStoryNames, resolveExecutionOrder, } from '../epic/index.js';
-import { runEpicSpell } from '../epic/runner-adapter.js';
+import { runEpicSpell, } from '../epic/runner-adapter.js';
+import { select } from '../prompt.js';
 // ============================================================================
 // Spell Template Loader
 // ============================================================================
@@ -183,6 +184,7 @@ async function runEpic(source, strategy, dryRun) {
                     console.log(`[epic]   └─ ${stepResult.error}`);
                 }
             },
+            onPreflightWarnings: isInteractive() ? resolvePreflightWarningsInteractively : undefined,
         });
         if (result.success) {
             console.log(`\n[epic] Epic #${issueNumber} completed successfully`);
@@ -195,8 +197,16 @@ async function runEpic(source, strategy, dryRun) {
             return { success: true, message: 'Epic completed', data: result };
         }
         else {
+            const firstErr = result.errors[0];
+            const errCode = firstErr?.code;
+            // Preflight failures are user environment problems, not epic bugs.
+            // Show only the friendly prerequisite message, nothing else.
+            if (errCode === 'PREFLIGHT_FAILED' && typeof firstErr?.message === 'string') {
+                console.log(`\n${firstErr.message}`);
+                console.log('\nThe epic was not started. Fix the item(s) above and try again.');
+                return { success: false, message: firstErr.message, data: result };
+            }
             console.log(`\n[epic] Epic #${issueNumber} failed`);
-            // Print step-level results for visibility
             if (result.steps && result.steps.length > 0) {
                 for (const step of result.steps) {
                     const icon = step.status === 'succeeded' ? '✓' : step.status === 'skipped' ? '○' : '✗';
@@ -207,7 +217,6 @@ async function runEpic(source, strategy, dryRun) {
                     }
                 }
             }
-            // Print spell-level errors with full detail
             for (const err of result.errors) {
                 const prefix = err.stepId
                     ? `  [${err.stepId}]`
@@ -220,8 +229,6 @@ async function runEpic(source, strategy, dryRun) {
                     }
                 }
             }
-            // Build actionable error message from first failure
-            const firstErr = result.errors[0];
             const rawMsg = firstErr?.message ?? 'Unknown error';
             const summary = buildFailureSummary(rawMsg, {
                 stepId: firstErr?.stepId,
@@ -301,6 +308,38 @@ async function resetEpic(epicNumber) {
     return { success: true };
 }
 // ============================================================================
+// Preflight warning interactive resolver
+// ============================================================================
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY) && process.env.CI !== 'true';
+}
+async function resolvePreflightWarningsInteractively(warnings) {
+    console.log('\nBefore this spell starts, some things need your attention:\n');
+    const decisions = [];
+    for (let i = 0; i < warnings.length; i++) {
+        const w = warnings[i];
+        const choices = [
+            ...w.resolutions.map((r, idx) => ({
+                label: r.label,
+                value: { action: 'resolve', resolutionIndex: idx },
+            })),
+            { label: "Continue anyway (I'll handle it)", value: { action: 'continue' } },
+            { label: 'Abort the spell', value: { action: 'abort' } },
+        ];
+        const decision = await select({
+            message: `${i + 1}. ${w.reason}`,
+            options: choices,
+        });
+        decisions.push(decision);
+        if (decision.action === 'abort') {
+            while (decisions.length < warnings.length)
+                decisions.push({ action: 'abort' });
+            break;
+        }
+    }
+    return decisions;
+}
+// ============================================================================
 // Error remediation hints
 // ============================================================================
 const REMEDIATION_PATTERNS = [

package/src/modules/cli/dist/src/epic/runner-adapter.js

@@ -8,7 +8,7 @@
  * Story #229: Uses shared engine loader instead of inline dynamic import.
  */
 import * as readline from 'node:readline';
-import { loadSpellEngine } from '../services/engine-loader.js';
+import { loadSpellEngine, } from '../services/engine-loader.js';
 import { createDashboardMemoryAccessor } from '../services/daemon-dashboard.js';
 /** Cached memory accessor — created once per process. */
 let memoryAccessor = null;

package/src/modules/cli/dist/src/epic/spells/auto-merge.yaml

@@ -62,14 +62,31 @@ steps:
           - name: "no unmerged files"
             command: "git diff --name-only --diff-filter=U"
             expectExitCode: 0
+            hint: "You have unresolved merge conflicts. Resolve them and commit before running this spell."
           - name: "working tree clean (tracked changes)"
             command: "git diff --quiet"
+            severity: "warning"
+            hint: "You have uncommitted changes to tracked files. If you want them carried onto the epic branch, pick 'Stash and carry over'."
+            resolutions:
+              - label: "Stash changes and carry them onto the epic branch"
+                command: "git stash push --include-untracked --message 'moflo-epic-autostash'"
+              - label: "Commit changes to the current branch first, then continue"
+                command: "git commit -am 'wip: pre-epic snapshot'"
           - name: "working tree clean (staged changes)"
             command: "git diff --cached --quiet"
+            severity: "warning"
+            hint: "You have staged changes that aren't committed. If you want them carried onto the epic branch, pick 'Stash and carry over'."
+            resolutions:
+              - label: "Stash staged changes and carry them onto the epic branch"
+                command: "git stash push --include-untracked --message 'moflo-epic-autostash'"
+              - label: "Commit staged changes to the current branch first, then continue"
+                command: "git commit -m 'wip: pre-epic snapshot'"
           - name: "gh cli authenticated"
             command: "gh auth status"
+            hint: "The GitHub CLI isn't signed in. Run: gh auth login"
           - name: "origin remote configured"
             command: "git remote get-url origin"
+            hint: "This repo has no 'origin' remote. Set one with: git remote add origin <url>"
         config:
           command: "git stash --include-untracked -q 2>/dev/null; git checkout {args.base_branch} && git pull origin {args.base_branch}; git stash pop -q 2>/dev/null || true"
           failOnError: true

package/src/modules/cli/dist/src/epic/spells/single-branch.yaml

@@ -59,12 +59,28 @@ steps:
       - name: "no unmerged files"
         command: "git diff --name-only --diff-filter=U"
         expectExitCode: 0
+        hint: "You have unresolved merge conflicts. Resolve them and commit before running this spell."
       - name: "working tree clean (tracked changes)"
         command: "git diff --quiet"
+        severity: "warning"
+        hint: "You have uncommitted changes to tracked files. If you want them carried onto the epic branch, pick 'Stash and carry over'."
+        resolutions:
+          - label: "Stash changes and carry them onto the epic branch"
+            command: "git stash push --include-untracked --message 'moflo-epic-autostash'"
+          - label: "Commit changes to the current branch first, then continue"
+            command: "git commit -am 'wip: pre-epic snapshot'"
       - name: "working tree clean (staged changes)"
         command: "git diff --cached --quiet"
+        severity: "warning"
+        hint: "You have staged changes that aren't committed. If you want them carried onto the epic branch, pick 'Stash and carry over'."
+        resolutions:
+          - label: "Stash staged changes and carry them onto the epic branch"
+            command: "git stash push --include-untracked --message 'moflo-epic-autostash'"
+          - label: "Commit staged changes to the current branch first, then continue"
+            command: "git commit -m 'wip: pre-epic snapshot'"
       - name: "gh cli authenticated"
         command: "gh auth status"
+        hint: "The GitHub CLI isn't signed in. Run: gh auth login"
     config:
       command: "git stash --include-untracked -q 2>/dev/null; git checkout {args.base_branch} && git pull origin {args.base_branch} && (git show-ref --verify --quiet refs/heads/epic/{args.epic_number}-{args.epic_slug} && git checkout epic/{args.epic_number}-{args.epic_slug} || git checkout -b epic/{args.epic_number}-{args.epic_slug}); git stash pop -q 2>/dev/null || true"
       timeout: 120000

package/src/modules/cli/dist/src/init/moflo-init.js

@@ -729,20 +729,29 @@ function isStale(srcPath, destPath) {
 // ============================================================================
 function updateGitignore(root) {
     const gitignorePath = path.join(root, '.gitignore');
-    const entries = ['.claude-epic/', '.swarm/', '.moflo/'];
+    const entries = [
+        '.claude-epic/',
+        '.claude-flow/',
+        '.swarm/',
+        '.moflo/',
+        '.claude/settings.local.json',
+        '.claude/scheduled_tasks.lock',
+        '**/workflow-state.json',
+    ];
     if (!fs.existsSync(gitignorePath)) {
-        // Create .gitignore with common defaults + MoFlo entries
         const defaultEntries = ['node_modules/', 'dist/', '.env', '.env.*', ''];
         const content = '# Dependencies\n' + defaultEntries.join('\n') + '\n# MoFlo state\n' + entries.join('\n') + '\n';
         fs.writeFileSync(gitignorePath, content, 'utf-8');
         return { name: '.gitignore', status: 'created', detail: 'Created with node_modules, .env, and MoFlo entries' };
     }
     const existing = fs.readFileSync(gitignorePath, 'utf-8');
-    const toAdd = entries.filter(e => !existing.includes(e));
+    const existingLines = new Set(existing.split(/\r?\n/).map(l => l.trim()).filter(l => l && !l.startsWith('#')));
+    const toAdd = entries.filter(e => !existingLines.has(e));
     if (toAdd.length === 0) {
         return { name: '.gitignore', status: 'skipped', detail: 'Entries already present' };
     }
-    fs.appendFileSync(gitignorePath, '\n# MoFlo state (gitignored)\n' + toAdd.join('\n') + '\n');
+    const sep = existing.endsWith('\n') ? '' : '\n';
+    fs.appendFileSync(gitignorePath, sep + '\n# MoFlo state (gitignored)\n' + toAdd.join('\n') + '\n');
     return { name: '.gitignore', status: 'updated', detail: `Added: ${toAdd.join(', ')}` };
 }
 // ============================================================================

package/src/modules/cli/dist/src/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.8.56';
+export const VERSION = '4.8.58';
 //# sourceMappingURL=version.js.map

package/src/modules/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moflo/cli",
-  "version": "4.8.56",
+  "version": "4.8.58",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/src/modules/spells/dist/commands/bash-command.js

@@ -146,10 +146,14 @@ export const bashCommand = {
                 const projectRoot = context.variables.projectRoot || process.cwd();
                 const caps = context.effectiveCaps ?? [];
                 if (tool === 'sandbox-exec') {
-                    sandboxWrap = wrapWithSandboxExec(command, caps, projectRoot);
+                    sandboxWrap = wrapWithSandboxExec(command, caps, projectRoot, {
+                        permissionLevel: context.permissionLevel,
+                    });
                 }
                 else if (tool === 'bwrap') {
-                    sandboxWrap = wrapWithBwrap(command, caps, projectRoot);
+                    sandboxWrap = wrapWithBwrap(command, caps, projectRoot, {
+                        permissionLevel: context.permissionLevel,
+                    });
                 }
             }
             catch (err) {

package/src/modules/spells/dist/core/bwrap-sandbox.js

@@ -9,7 +9,44 @@
  *
  * @see https://github.com/eric-cielo/moflo/issues/411
  */
+import { homedir } from 'node:os';
+import { posix } from 'node:path';
 import { resolveScopePath } from './sandbox-utils.js';
+/**
+ * Home-directory paths that common CLI tools need writable to persist state.
+ * These are bound via `--bind-try` so missing entries are silently skipped.
+ *
+ * Rationale: `elevated`/`autonomous` steps routinely spawn tools like `claude`,
+ * `gh`, `git`, and `npm` that write config/credentials/cache under $HOME. A
+ * pure `--ro-bind / /` makes those tools fail with EROFS. We narrow the bind
+ * set to well-known config paths so the sandbox still protects system dirs
+ * (/etc, /usr, /var) and the rest of $HOME.
+ */
+const TOOL_HOME_PATHS = [
+    // Claude Code
+    '.claude',
+    '.claude.json',
+    // GitHub CLI
+    '.config/gh',
+    // git
+    '.gitconfig',
+    '.git-credentials',
+    // npm
+    '.npmrc',
+    '.npm',
+    // Shared XDG locations
+    '.config',
+    '.cache',
+    '.local/share',
+    '.local/state',
+];
+/**
+ * Permission levels that spawn arbitrary CLI tools and therefore need tool
+ * home paths bound writable.
+ */
+function needsToolHomeAccess(level) {
+    return level === 'elevated' || level === 'autonomous';
+}
 /**
  * Build bwrap CLI arguments from step capabilities.
  *
@@ -20,8 +57,12 @@ import { resolveScopePath } from './sandbox-utils.js';
  *   - fs:write scoped  -> --bind (read-write) for each scope path
  *   - fs:write unscoped -> --bind (read-write) for projectRoot
  *   - net              -> omit --unshare-net
+ *
+ * When `options.permissionLevel` is `elevated` or `autonomous`, also bind a
+ * narrow allowlist of CLI-tool home paths writable via `--bind-try` so that
+ * spawned subcommands (claude, gh, git, npm) can persist their state.
  */
-export function buildBwrapArgs(command, capabilities, projectRoot) {
+export function buildBwrapArgs(command, capabilities, projectRoot, options = {}) {
     const args = [];
     // ── Root filesystem (read-only by default) ──────────────────────────
     args.push('--ro-bind', '/', '/');
@@ -32,16 +73,35 @@ export function buildBwrapArgs(command, capabilities, projectRoot) {
     args.push('--tmpfs', '/tmp');
     // ── fs:write — grant read-write bind mounts ─────────────────────────
     const fsWrite = capabilities.find(c => c.type === 'fs:write');
+    const writableScopes = new Set();
     if (fsWrite) {
         if (fsWrite.scope && fsWrite.scope.length > 0) {
             for (const scopePath of fsWrite.scope) {
                 const resolved = resolveScopePath(scopePath, projectRoot);
                 args.push('--bind', resolved, resolved);
+                writableScopes.add(resolved);
             }
         }
         else {
             // Unscoped fs:write -> writable project root
             args.push('--bind', projectRoot, projectRoot);
+            writableScopes.add(projectRoot);
+        }
+    }
+    // ── Tool home paths (elevated/autonomous only) ──────────────────────
+    // Bind well-known CLI-tool config/cache paths writable so spawned
+    // subcommands (claude, gh, git, npm) can persist their state. Uses
+    // --bind-try so missing paths are ignored instead of erroring.
+    if (needsToolHomeAccess(options.permissionLevel)) {
+        const home = options.homeDir ?? homedir();
+        if (home) {
+            for (const rel of TOOL_HOME_PATHS) {
+                const resolved = posix.join(home, rel);
+                if (writableScopes.has(resolved))
+                    continue;
+                args.push('--bind-try', resolved, resolved);
+                writableScopes.add(resolved);
+            }
         }
     }
     // ── fs:read scoped — explicit read-only bind mounts ─────────────────
@@ -50,9 +110,8 @@ export function buildBwrapArgs(command, capabilities, projectRoot) {
     if (fsRead && fsRead.scope && fsRead.scope.length > 0) {
         for (const scopePath of fsRead.scope) {
             const resolved = resolveScopePath(scopePath, projectRoot);
-            // Only add if not already covered by an fs:write --bind for same path
-            const alreadyWritable = fsWrite?.scope?.some(wp => resolveScopePath(wp, projectRoot) === resolved);
-            if (!alreadyWritable) {
+            // Only add if not already covered by a writable bind for same path
+            if (!writableScopes.has(resolved)) {
                 args.push('--ro-bind', resolved, resolved);
             }
         }
@@ -77,8 +136,8 @@ export function buildBwrapArgs(command, capabilities, projectRoot) {
  * Unlike sandbox-exec, bwrap uses CLI args only — no temp files are created,
  * so `cleanup()` is a no-op.
  */
-export function wrapWithBwrap(command, capabilities, projectRoot) {
-    const args = buildBwrapArgs(command, capabilities, projectRoot);
+export function wrapWithBwrap(command, capabilities, projectRoot, options = {}) {
+    const args = buildBwrapArgs(command, capabilities, projectRoot, options);
     return {
         bin: 'bwrap',
         args,

package/src/modules/spells/dist/core/preflight-checker.js

@@ -61,6 +61,8 @@ function bindCommandPreflight(step, stepIndex, check, context) {
         stepId: step.id,
         stepIndex,
         name: check.name,
+        severity: check.severity ?? 'fatal',
+        resolutions: check.resolutions,
         run: () => {
             const ctx = {
                 args: context.args,
@@ -77,6 +79,8 @@ function bindYamlPreflight(step, stepIndex, spec, context) {
         stepId: step.id,
         stepIndex,
         name: spec.name,
+        severity: spec.severity ?? 'fatal',
+        resolutions: spec.resolutions,
         run: async () => {
             const command = interpolateSafe(spec.command, context.args);
             const expected = spec.expectExitCode ?? 0;
@@ -84,6 +88,9 @@ function bindYamlPreflight(step, stepIndex, spec, context) {
             const actualExitCode = await runShellExitCode(command, timeoutMs);
             if (actualExitCode === expected)
                 return { passed: true };
+            if (spec.hint) {
+                return { passed: false, reason: spec.hint };
+            }
             return {
                 passed: false,
                 reason: `command "${command}" exited with ${actualExitCode}, expected ${expected}`,
@@ -104,6 +111,8 @@ export async function checkPreflights(preflights) {
                 name: pf.name,
                 passed: result.passed,
                 reason: result.reason,
+                severity: pf.severity,
+                resolutions: pf.resolutions,
             };
         }
         catch (err) {
@@ -112,21 +121,52 @@ export async function checkPreflights(preflights) {
                 name: pf.name,
                 passed: false,
                 reason: err.message,
+                severity: pf.severity,
+                resolutions: pf.resolutions,
             };
         }
     }));
 }
+/**
+ * Run a resolution shell command chosen by the user.
+ * Returns true iff the command exits 0 (or no command was provided).
+ */
+export async function runResolutionCommand(resolution, args) {
+    if (!resolution.command)
+        return { ok: true, exitCode: 0 };
+    const cmd = interpolateSafe(resolution.command, args);
+    const exitCode = await runShellExitCode(cmd, resolution.timeoutMs ?? 30_000);
+    return { ok: exitCode === 0, exitCode };
+}
 /** Format failed preflights into a user-friendly error message. */
 export function formatPreflightErrors(results) {
     const failed = results.filter(r => !r.passed);
     if (failed.length === 0)
         return '';
-    const lines = ['Preflight checks failed:'];
+    const header = failed.length === 1
+        ? 'A prerequisite for this spell was not met:'
+        : `${failed.length} prerequisites for this spell were not met:`;
+    const lines = [header];
     for (const f of failed) {
-        lines.push(`  - [${f.stepId}] ${f.name}${f.reason ? `: ${f.reason}` : ''}`);
+        const message = f.reason && f.reason.trim().length > 0 ? f.reason : f.name;
+        lines.push(`  - ${message}`);
     }
     return lines.join('\n');
 }
+/** Partition preflight results by severity. */
+export function partitionPreflightResults(results) {
+    const fatals = [];
+    const warnings = [];
+    for (const r of results) {
+        if (r.passed)
+            continue;
+        if (r.severity === 'warning')
+            warnings.push(r);
+        else
+            fatals.push(r);
+    }
+    return { fatals, warnings };
+}
 // ============================================================================
 // Internals
 // ============================================================================

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

@@ -9,7 +9,7 @@ import { rollbackSteps } from './rollback-orchestrator.js';
 import { buildCredentialPatterns, addCredentialPattern, collectCredentialNames } from './credential-masker.js';
 import { executeSingleStep } from './step-executor.js';
 import { collectPrerequisites, checkPrerequisites, formatPrerequisiteErrors } from './prerequisite-checker.js';
-import { collectPreflights, checkPreflights, formatPreflightErrors } from './preflight-checker.js';
+import { collectPreflights, checkPreflights, formatPreflightErrors, partitionPreflightResults, runResolutionCommand, } from './preflight-checker.js';
 import { DENY_ALL_GATEWAY } from './capability-gateway.js';
 import { resolveEffectiveSandbox, formatSandboxLog, DEFAULT_SANDBOX_CONFIG, } from './platform-sandbox.js';
 import { checkAcceptance, recordAcceptance } from './permission-acceptance.js';
@@ -110,19 +110,9 @@ export class SpellCaster {
                 }
             }
             // Preflight runtime-state checks — fail fast before any step runs.
-            const preflights = collectPreflights(definition, this.registry, {
-                args: resolvedArgs,
-                credentials: this.credentials,
-            });
-            if (preflights.length > 0) {
-                const preflightResults = await checkPreflights(preflights);
-                if (preflightResults.some(r => !r.passed)) {
-                    console.log(`[spell] ${formatPreflightErrors(preflightResults)}`);
-                    return this.failureResult(spellId, startTime, [{
-                            code: 'PREFLIGHT_FAILED',
-                            message: formatPreflightErrors(preflightResults),
-                        }], definition.name);
-                }
+            const preflightFailure = await this.runPreflights(definition, resolvedArgs, options);
+            if (preflightFailure) {
+                return this.failureResult(spellId, startTime, [{ code: 'PREFLIGHT_FAILED', message: preflightFailure }], definition.name);
             }
         }
         if (options.dryRun) {
@@ -320,6 +310,54 @@ export class SpellCaster {
     // --------------------------------------------------------------------------
     // Private — Helpers
     // --------------------------------------------------------------------------
+    /**
+     * Run every preflight declared by the spell.
+     * Returns a user-facing failure message, or null if the spell may proceed.
+     */
+    async runPreflights(definition, resolvedArgs, options) {
+        const preflights = collectPreflights(definition, this.registry, {
+            args: resolvedArgs,
+            credentials: this.credentials,
+        });
+        if (preflights.length === 0)
+            return null;
+        const results = await checkPreflights(preflights);
+        const { fatals, warnings } = partitionPreflightResults(results);
+        if (fatals.length > 0)
+            return formatPreflightErrors(fatals);
+        if (warnings.length === 0)
+            return null;
+        if (!options.onPreflightWarnings)
+            return formatPreflightErrors(warnings);
+        const payload = warnings.map(w => ({
+            stepId: w.stepId,
+            name: w.name,
+            reason: w.reason ?? w.name,
+            resolutions: w.resolutions ?? [],
+        }));
+        const decisions = await options.onPreflightWarnings(payload);
+        if (decisions.length !== warnings.length) {
+            return `Preflight warning handler returned ${decisions.length} decisions for ${warnings.length} warnings`;
+        }
+        for (let i = 0; i < decisions.length; i++) {
+            const decision = decisions[i];
+            const warn = warnings[i];
+            if (decision.action === 'abort') {
+                return formatPreflightErrors([warn]);
+            }
+            if (decision.action === 'resolve') {
+                const chosen = (warn.resolutions ?? [])[decision.resolutionIndex];
+                if (!chosen) {
+                    return `Invalid resolution index ${decision.resolutionIndex} for "${warn.name}"`;
+                }
+                const { ok, exitCode } = await runResolutionCommand(chosen, resolvedArgs);
+                if (!ok) {
+                    return `Resolution "${chosen.label}" failed (exit code ${exitCode}). Fix the underlying issue and try again.`;
+                }
+            }
+        }
+        return null;
+    }
     runStep(step, state, index) {
         const ctxBuilder = (v, a, sid, si, sig) => this.buildContext(v, a, sid, si, sig, state.effectiveSandbox);
         return executeSingleStep(step, state, index, this.registry, ctxBuilder);

package/src/modules/spells/dist/core/sandbox-profile.js

@@ -7,10 +7,42 @@
  * @see https://github.com/eric-cielo/moflo/issues/410
  */
 import { writeFileSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
+import { join, posix } from 'node:path';
+import { tmpdir, homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { resolveScopePath } from './sandbox-utils.js';
+/**
+ * Home-directory paths that common CLI tools need writable to persist state.
+ * Rationale matches the Linux bwrap wrapper: `elevated`/`autonomous` steps
+ * spawn tools (claude, gh, git, npm) that write under $HOME; a pure
+ * deny-default profile makes those tools fail. System dirs (/etc, /usr,
+ * /private/var/root, etc.) remain denied.
+ */
+const TOOL_HOME_PATHS = [
+    // Claude Code (dotfile + Application Support on macOS)
+    '.claude',
+    '.claude.json',
+    'Library/Application Support/Claude',
+    'Library/Application Support/claude-cli-nodejs',
+    'Library/Caches/Claude',
+    'Library/Preferences',
+    // GitHub CLI
+    '.config/gh',
+    // git
+    '.gitconfig',
+    '.git-credentials',
+    // npm
+    '.npmrc',
+    '.npm',
+    // Shared XDG locations
+    '.config',
+    '.cache',
+    '.local/share',
+    '.local/state',
+];
+function needsToolHomeAccess(level) {
+    return level === 'elevated' || level === 'autonomous';
+}
 // ============================================================================
 // Profile Generation
 // ============================================================================
@@ -28,7 +60,7 @@ import { resolveScopePath } from './sandbox-utils.js';
  *   - net capability → allow network*
  *   - No net capability → network denied (default deny covers it)
  */
-export function generateSandboxProfile(capabilities, projectRoot) {
+export function generateSandboxProfile(capabilities, projectRoot, options = {}) {
     const lines = [
         '(version 1)',
         '(deny default)',
@@ -85,6 +117,23 @@ export function generateSandboxProfile(capabilities, projectRoot) {
             lines.push(`(allow file-write* (subpath "${escapeSbPath(projectRoot)}"))`);
         }
     }
+    // ── Tool home paths (elevated/autonomous only) ──────────────────────
+    // Allow writes to well-known CLI-tool home paths so spawned subcommands
+    // (claude, gh, git, npm) can persist config/credentials/cache. Uses
+    // `(subpath ...)` so non-existent paths are simply unmatched — no error.
+    if (needsToolHomeAccess(options.permissionLevel)) {
+        const home = options.homeDir ?? homedir();
+        if (home) {
+            lines.push('');
+            lines.push('; Tool home paths (elevated)');
+            for (const rel of TOOL_HOME_PATHS) {
+                // sandbox-exec is macOS-only → always POSIX paths
+                const resolved = posix.join(home, rel);
+                lines.push(`(allow file-read* (subpath "${escapeSbPath(resolved)}"))`);
+                lines.push(`(allow file-write* (subpath "${escapeSbPath(resolved)}"))`);
+            }
+        }
+    }
     // ── net ──────────────────────────────────────────────────────────────
     const hasNet = capabilities.some(c => c.type === 'net');
     if (hasNet) {
@@ -104,8 +153,8 @@ export function generateSandboxProfile(capabilities, projectRoot) {
  * Writes a temporary `.sb` profile and returns the sandbox-exec invocation.
  * The caller MUST call `cleanup()` after the process exits.
  */
-export function wrapWithSandboxExec(command, capabilities, projectRoot) {
-    const profile = generateSandboxProfile(capabilities, projectRoot);
+export function wrapWithSandboxExec(command, capabilities, projectRoot, options = {}) {
+    const profile = generateSandboxProfile(capabilities, projectRoot, options);
     const profilePath = join(tmpdir(), `moflo-sandbox-${randomBytes(8).toString('hex')}.sb`);
     writeFileSync(profilePath, profile, 'utf8');
     return {

package/src/modules/spells/dist/schema/validator.js

@@ -179,6 +179,35 @@ function validateSteps(steps, errors, stepIds, outputVars, options, prefix = 'st
                     if (pf.timeoutMs !== undefined && (typeof pf.timeoutMs !== 'number' || pf.timeoutMs <= 0)) {
                         errors.push({ path: `${pfPath}.timeoutMs`, message: 'timeoutMs must be a positive number' });
                     }
+                    if (pf.hint !== undefined && typeof pf.hint !== 'string') {
+                        errors.push({ path: `${pfPath}.hint`, message: 'hint must be a string' });
+                    }
+                    if (pf.severity !== undefined && pf.severity !== 'fatal' && pf.severity !== 'warning') {
+                        errors.push({ path: `${pfPath}.severity`, message: 'severity must be "fatal" or "warning"' });
+                    }
+                    if (pf.resolutions !== undefined) {
+                        if (!Array.isArray(pf.resolutions)) {
+                            errors.push({ path: `${pfPath}.resolutions`, message: 'resolutions must be an array' });
+                        }
+                        else {
+                            pf.resolutions.forEach((r, ri) => {
+                                const rPath = `${pfPath}.resolutions[${ri}]`;
+                                if (!r || typeof r !== 'object') {
+                                    errors.push({ path: rPath, message: 'resolution must be an object' });
+                                    return;
+                                }
+                                if (typeof r.label !== 'string' || r.label.length === 0) {
+                                    errors.push({ path: `${rPath}.label`, message: 'resolution.label is required' });
+                                }
+                                if (r.command !== undefined && typeof r.command !== 'string') {
+                                    errors.push({ path: `${rPath}.command`, message: 'resolution.command must be a string' });
+                                }
+                                if (r.timeoutMs !== undefined && (typeof r.timeoutMs !== 'number' || r.timeoutMs <= 0)) {
+                                    errors.push({ path: `${rPath}.timeoutMs`, message: 'resolution.timeoutMs must be a positive number' });
+                                }
+                            });
+                        }
+                    }
                 });
             }
         }