moflo 4.9.27 → 4.9.29

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

@@ -15,6 +15,9 @@ 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';
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { updateYamlArgDefaults } from '../spells/core/yaml-defaults-writer.js';
 // Re-export formatStatus as formatStageStatus for table column references
 const formatStageStatus = formatStatus;
 // Shared table column definitions
@@ -141,6 +144,12 @@ export const castCommand = {
             description: 'Single key=value spell argument (repeatable). Numeric/boolean strings are coerced.',
             type: 'array',
         },
+        {
+            name: 'reprompt-creds',
+            description: 'Force re-prompting for env-type prereqs (rotate or correct stored credentials)',
+            type: 'boolean',
+            default: false,
+        },
     ],
     examples: [
         { command: 'moflo spell cast -n development', description: 'Cast spell by name' },
@@ -148,6 +157,7 @@ export const castCommand = {
         { command: 'moflo spell cast -n sa --dry-run', description: 'Validate via abbreviation' },
         { command: "moflo spell cast -n oap --args '{\"maxEmails\":50}'", description: 'Pass spell arguments as JSON' },
         { command: 'moflo spell cast -n oap --arg headless=false --arg maxEmails=50', description: 'Pass arguments as key=value pairs' },
+        { command: 'moflo spell cast -n oap --reprompt-creds', description: 'Re-prompt for credentials (rotate stored secrets)' },
     ],
     action: async (ctx) => {
         const name = ctx.flags.name || ctx.args[0];
@@ -217,6 +227,7 @@ export const castCommand = {
                 file: file || undefined,
                 args,
                 dryRun,
+                forceCredentialReprompt: ctx.flags.repromptCreds,
             });
             if (result.error) {
                 spinner.fail(`Spell failed: ${result.error}`);
@@ -245,6 +256,22 @@ export const castCommand = {
                 output.printTable({ columns: STEP_COLUMNS, data: result.steps });
             }
             printSpellErrors(result.errors);
+            // #1003 — offer to persist --arg values back into the spell YAML.
+            // CLI-interactive only; MCP/headless callers skip by design.
+            if (result.success
+                && !dryRun
+                && ctx.interactive
+                && Object.keys(args).length > 0
+                && result.sourceFile) {
+                if (result.tier === 'shipped') {
+                    const hint = name || basename(result.sourceFile).replace(/\.[^.]+$/, '');
+                    output.writeln();
+                    output.printInfo(`Shipped spell — copy to spells/dev/${hint}.yaml first to persist defaults.`);
+                }
+                else {
+                    await offerArgWriteback(result.sourceFile, args);
+                }
+            }
             return { success: result.success, data: result };
         }
         catch (error) {
@@ -256,6 +283,39 @@ export const castCommand = {
         }
     },
 };
+async function offerArgWriteback(sourceFile, userArgs) {
+    const keys = Object.keys(userArgs);
+    output.writeln();
+    const noun = keys.length === 1 ? 'argument' : 'arguments';
+    const accepted = await confirm({
+        message: `Save ${keys.length} ${noun} (${keys.join(', ')}) as the spell's defaults?`,
+        default: false,
+    });
+    if (!accepted)
+        return;
+    let original;
+    try {
+        original = await readFile(sourceFile, 'utf-8');
+    }
+    catch (err) {
+        output.printError(`Could not read spell YAML: ${err.message}`);
+        return;
+    }
+    const result = updateYamlArgDefaults(original, userArgs);
+    if (result.updated.length > 0) {
+        try {
+            await writeFile(sourceFile, result.content, 'utf-8');
+            output.printSuccess(`Saved ${result.updated.length} default${result.updated.length === 1 ? '' : 's'}: ${result.updated.join(', ')}`);
+        }
+        catch (err) {
+            output.printError(`Could not write spell YAML: ${err.message}`);
+            return;
+        }
+    }
+    if (result.skipped.length > 0) {
+        output.printWarning(`Skipped ${result.skipped.length} (not declared in arguments:): ${result.skipped.join(', ')}`);
+    }
+}
 // Validate subcommand
 const validateCommand = {
     name: 'validate',

package/dist/src/cli/mcp-tools/spell-tools.js

@@ -11,6 +11,7 @@ import { loadSpellEngine, getCachedEngine, } from '../services/engine-loader.js'
 import { findProjectRoot } from '../services/project-root.js';
 import { buildGrimoire } from '../services/grimoire-builder.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
+import { inferSpellTier } from '../spells/core/spell-tier.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -53,14 +54,18 @@ function trackResult(tracked, result) {
     tracked.completedAt = new Date().toISOString();
 }
 /** Execute a definition via the engine with tracking and error handling. */
-async function executeAndTrack(engine, definition, args) {
+async function executeAndTrack(engine, definition, args, options = {}) {
     const spellId = `sp-${Date.now()}`;
     const tracked = trackStart(spellId, definition.name, definition.description);
     try {
         const sandboxConfig = await engine.loadSandboxConfigFromProject(findProjectRoot());
-        const result = await engine.bridgeExecuteSpell(definition, args, { spellId, sandboxConfig });
+        const result = await engine.bridgeExecuteSpell(definition, args, {
+            spellId,
+            sandboxConfig,
+            forceCredentialReprompt: options.forceCredentialReprompt,
+        });
         trackResult(tracked, result);
-        return serializeResult(result);
+        return withSpellSource(serializeResult(result), options.sourceFile, options.tier);
     }
     catch (err) {
         tracked.status = SPELL_STATUS.FAILED;
@@ -68,6 +73,14 @@ async function executeAndTrack(engine, definition, args) {
         return { spellId, error: errorDetail(err) };
     }
 }
+/** Attach sourceFile + tier metadata to a serialized cast response. (#1003) */
+function withSpellSource(base, sourceFile, tier) {
+    if (sourceFile)
+        base.sourceFile = sourceFile;
+    if (tier)
+        base.tier = tier;
+    return base;
+}
 // ============================================================================
 // Registry singleton (created once per session, refreshable on demand)
 // ============================================================================
@@ -149,11 +162,16 @@ export const spellTools = [
                 content: { type: 'string', description: 'Inline YAML/JSON spell incantation' },
                 args: { type: 'object', description: 'Reagents (arguments) to pass to the spell' },
                 dryRun: { type: 'boolean', description: 'Preview the spell without casting' },
+                forceCredentialReprompt: {
+                    type: 'boolean',
+                    description: 'Force re-prompting for env-type prereqs even when the credential store has a stored value (used to rotate or correct stored secrets)',
+                },
             },
         },
         handler: async (input) => {
             const args = input.args ?? {};
             const dryRun = input.dryRun;
+            const forceCredentialReprompt = input.forceCredentialReprompt;
             if (input.name) {
                 // Resolve via registry and execute the parsed definition directly
                 const registry = await getRegistry();
@@ -162,7 +180,11 @@ export const spellTools = [
                     return { error: `Spell not found in grimoire: ${input.name}` };
                 }
                 const engine = await loadSpellEngine();
-                return executeAndTrack(engine, loaded.definition, args);
+                return executeAndTrack(engine, loaded.definition, args, {
+                    forceCredentialReprompt,
+                    sourceFile: loaded.sourceFile,
+                    tier: loaded.tier,
+                });
             }
             // Determine raw content source
             let content;
@@ -189,10 +211,12 @@ export const spellTools = [
             // Run from raw content via bridge
             const engine = await loadSpellEngine();
             const sandboxConfig = await engine.loadSandboxConfigFromProject(findProjectRoot());
-            const result = await engine.bridgeRunSpell(content, sourceFile, args, { dryRun, sandboxConfig });
+            const result = await engine.bridgeRunSpell(content, sourceFile, args, {
+                dryRun, sandboxConfig, forceCredentialReprompt,
+            });
             const tracked = trackStart(result.spellId, spellName);
             trackResult(tracked, result);
-            return serializeResult(result);
+            return withSpellSource(serializeResult(result), sourceFile, sourceFile ? inferSpellTier(sourceFile) : undefined);
         },
     },
     // --------------------------------------------------------------------------

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

@@ -165,7 +165,9 @@ function appendPrereqLine(lines, name, hint, url) {
  * 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.
+ *   3. TTY interactive → prompt → write to process.env. After ALL prompts,
+ *      one Y/n offer asks whether to persist the collected answers to the
+ *      credential store as a batch (default Y). Story #1002.
  *   4. Non-TTY or no credentials → fail fast with `errorCode: 'MISSING_CREDENTIAL'`.
  *
  * Non-env prereqs (`command`, `file`) bypass the credential chain and surface
@@ -186,9 +188,11 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
     }
     // Pull env-type prereqs from the store in parallel — each resolved index
     // lets us skip a re-check of the cheap env detector.
+    // `forceCredentialReprompt` bypasses this step so users can rotate or
+    // correct stored credentials by re-running through the prompt path.
     const resolvedFromStoreNames = [];
     const storeResolved = new Set();
-    if (credentials) {
+    if (credentials && !options.forceCredentialReprompt) {
         await Promise.all(unmetIndices.map(async (i) => {
             const prereq = prerequisites[i];
             if (!prereq.envKey)
@@ -230,7 +234,9 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
     const promptLine = options.promptLine ?? readLineFromStdin;
     const promptedNames = [];
     const promptableSet = new Set(promptable);
+    const pendingSaves = [];
     const lock = acquireTTYLock();
+    let shouldSave = false;
     try {
         for (const prereq of promptable) {
             if (options.abortSignal?.aborted) {
@@ -265,21 +271,32 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
             }
             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})`);
-                    }
-                }
+                if (credentials)
+                    pendingSaves.push({ envKey: prereq.envKey, value: answer });
             }
             promptedNames.push(prereq.name);
         }
+        // One batched save offer covers every collected answer — issuing N
+        // confirmations would be repetitive when most users want all-or-nothing.
+        if (credentials && pendingSaves.length > 0) {
+            shouldSave = await promptSaveCredentialsConfirmation(promptLine, pendingSaves.length, options.abortSignal);
+        }
     }
     finally {
         lock.release();
     }
+    // Persist outside the TTY lock so slow disk/keychain writes don't block
+    // concurrent stdin readers waiting on the same lock.
+    if (credentials && shouldSave) {
+        for (const { envKey, value } of pendingSaves) {
+            try {
+                await credentials.store(envKey, value);
+            }
+            catch (err) {
+                log(`  (could not persist credential "${envKey}": ${err.message})`);
+            }
+        }
+    }
     // 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]));
@@ -304,6 +321,25 @@ function formatMissingCredentialMessage(envKeys, prereqs) {
     lines.push('  flo spell credentials set <name>');
     return lines.join('\n');
 }
+/**
+ * Ask once whether to persist every collected prereq answer to the
+ * credential store. Empty input or `y/yes` → true (default Y); `n/no` →
+ * false. A failed prompt (e.g. abort) silently declines so the cast
+ * still proceeds with the in-memory env values.
+ */
+async function promptSaveCredentialsConfirmation(promptLine, count, abortSignal) {
+    const noun = count === 1 ? 'credential' : 'credentials';
+    const prompt = `  Save ${count} ${noun} to the encrypted credential store for future runs? [Y/n] `;
+    let answer;
+    try {
+        answer = await promptLine(prompt, abortSignal);
+    }
+    catch {
+        return false;
+    }
+    const trimmed = answer.trim().toLowerCase();
+    return trimmed === '' || trimmed === 'y' || trimmed === 'yes';
+}
 function printPreflightBanner(log, unmetCount) {
     log('');
     log('\x1b[1;36m━━━ Preflight: missing prerequisites ━━━\x1b[0m');

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

@@ -107,6 +107,7 @@ export class SpellCaster {
                 const resolution = await resolveUnmetPrerequisites(prerequisites, {
                     abortSignal: options.signal,
                     credentials: this.credentials,
+                    forceCredentialReprompt: options.forceCredentialReprompt,
                 });
                 if (!resolution.ok) {
                     return this.failureResult(spellId, startTime, [{

package/dist/src/cli/spells/core/spell-tier.js

@@ -0,0 +1,23 @@
+/**
+ * Classify a spell's source path as 'shipped' (ships with moflo, read-only
+ * from the consumer's perspective) or 'user' (project-local, writable).
+ *
+ * Story #1003 — used by the post-cast arg-writeback offer to skip the save
+ * prompt for shipped YAMLs (mutating them inside `node_modules/moflo/...`
+ * would be wiped on the next `npm install` and confuses provenance).
+ */
+const SHIPPED_MARKERS = [
+    // Installed package — both bare 'moflo' and the legacy '@moflo/*' workspace.
+    /\/node_modules\/moflo\//,
+    /\/node_modules\/@moflo\//,
+    // Source-tree shipped definitions (relevant when moflo dogfoods itself).
+    /\/src\/cli\/spells\/definitions\//,
+    /\/dist\/[^/]*\/?cli\/spells\/definitions\//,
+];
+export function inferSpellTier(sourceFile) {
+    if (!sourceFile)
+        return 'user';
+    const norm = sourceFile.replace(/\\/g, '/');
+    return SHIPPED_MARKERS.some((re) => re.test(norm)) ? 'shipped' : 'user';
+}
+//# sourceMappingURL=spell-tier.js.map

package/dist/src/cli/spells/core/yaml-defaults-writer.js

@@ -0,0 +1,169 @@
+// YAML line-editor: rewrite `arguments.<key>.default` without a full
+// round-trip through js-yaml (which would drop comments). Anchors and
+// block-scalar defaults are listed in `skipped` so callers can surface them.
+import * as yaml from 'js-yaml';
+const ARGUMENTS_HEADER_RE = /^arguments\s*:\s*(?:#.*)?$/;
+const KEY_LINE_RE = /^(\s*)([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/;
+const DEFAULT_LINE_RE = /^(\s*default\s*:\s*)(?:[^#\n]*?)(\s*#.*)?$/;
+const BLOCK_SCALAR_DEFAULT_RE = /^\s*default\s*:\s*[|>][+-]?\d*\s*(?:#.*)?$/;
+export function updateYamlArgDefaults(yamlContent, updates) {
+    const updateKeys = Object.keys(updates);
+    if (updateKeys.length === 0) {
+        return { content: yamlContent, updated: [], skipped: [] };
+    }
+    const usesCRLF = /\r\n/.test(yamlContent);
+    const normalized = usesCRLF ? yamlContent.replace(/\r\n/g, '\n') : yamlContent;
+    const lines = normalized.split('\n');
+    const argumentsLineIdx = findArgumentsHeader(lines);
+    if (argumentsLineIdx === -1) {
+        return { content: yamlContent, updated: [], skipped: updateKeys };
+    }
+    const argKeyIndent = findArgKeyIndent(lines, argumentsLineIdx);
+    if (argKeyIndent === -1) {
+        return { content: yamlContent, updated: [], skipped: updateKeys };
+    }
+    const remaining = new Set(updateKeys);
+    const updated = [];
+    const skippedExtra = [];
+    let i = argumentsLineIdx + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        const stripped = line.trim();
+        if (!stripped || stripped.startsWith('#')) {
+            i++;
+            continue;
+        }
+        const indent = leadingSpaces(line);
+        if (indent === 0)
+            break;
+        if (indent !== argKeyIndent) {
+            i++;
+            continue;
+        }
+        const m = KEY_LINE_RE.exec(line);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const argName = m[2];
+        if (!remaining.has(argName)) {
+            i = skipBlock(lines, i + 1, argKeyIndent);
+            continue;
+        }
+        const blockStart = i + 1;
+        const blockEnd = skipBlock(lines, blockStart, argKeyIndent);
+        const propIndent = findPropIndent(lines, blockStart, blockEnd, argKeyIndent);
+        const defaultLineIdx = findDefaultLine(lines, blockStart, blockEnd, propIndent);
+        const newValueStr = formatYamlValue(updates[argName]);
+        // Refuse to touch block-scalar defaults — replacing the header line with
+        // an inline scalar would orphan the continuation lines as sibling keys.
+        if (defaultLineIdx !== -1 && BLOCK_SCALAR_DEFAULT_RE.test(lines[defaultLineIdx])) {
+            skippedExtra.push(argName);
+            remaining.delete(argName);
+            i = skipBlock(lines, i + 1, argKeyIndent);
+            continue;
+        }
+        // Refuse multi-line dumped values for the same orphan-line reason.
+        if (newValueStr.includes('\n')) {
+            skippedExtra.push(argName);
+            remaining.delete(argName);
+            i = skipBlock(lines, i + 1, argKeyIndent);
+            continue;
+        }
+        if (defaultLineIdx !== -1) {
+            lines[defaultLineIdx] = replaceDefaultValue(lines[defaultLineIdx], newValueStr);
+        }
+        else {
+            const insertIndent = ' '.repeat(propIndent);
+            lines.splice(blockStart, 0, `${insertIndent}default: ${newValueStr}`);
+        }
+        updated.push(argName);
+        remaining.delete(argName);
+        i = skipBlock(lines, i + 1, argKeyIndent);
+    }
+    const joined = lines.join('\n');
+    const content = usesCRLF ? joined.replace(/\n/g, '\r\n') : joined;
+    return {
+        content,
+        updated,
+        skipped: [...remaining, ...skippedExtra],
+    };
+}
+function findArgumentsHeader(lines) {
+    for (let i = 0; i < lines.length; i++) {
+        if (leadingSpaces(lines[i]) === 0 && ARGUMENTS_HEADER_RE.test(lines[i].trim())) {
+            return i;
+        }
+    }
+    return -1;
+}
+function findArgKeyIndent(lines, headerIdx) {
+    for (let i = headerIdx + 1; i < lines.length; i++) {
+        const stripped = lines[i].trim();
+        if (!stripped || stripped.startsWith('#'))
+            continue;
+        const indent = leadingSpaces(lines[i]);
+        if (indent === 0)
+            return -1;
+        return indent;
+    }
+    return -1;
+}
+function findPropIndent(lines, blockStart, blockEnd, argKeyIndent) {
+    for (let j = blockStart; j < blockEnd; j++) {
+        const stripped = lines[j].trim();
+        if (!stripped || stripped.startsWith('#'))
+            continue;
+        return leadingSpaces(lines[j]);
+    }
+    return argKeyIndent + 2;
+}
+function findDefaultLine(lines, blockStart, blockEnd, propIndent) {
+    for (let j = blockStart; j < blockEnd; j++) {
+        const stripped = lines[j].trim();
+        if (!stripped || stripped.startsWith('#'))
+            continue;
+        if (leadingSpaces(lines[j]) !== propIndent)
+            continue;
+        if (/^default\s*:/.test(stripped))
+            return j;
+    }
+    return -1;
+}
+function skipBlock(lines, start, parentIndent) {
+    for (let i = start; i < lines.length; i++) {
+        const stripped = lines[i].trim();
+        if (!stripped || stripped.startsWith('#'))
+            continue;
+        if (leadingSpaces(lines[i]) <= parentIndent)
+            return i;
+    }
+    return lines.length;
+}
+function leadingSpaces(line) {
+    let n = 0;
+    while (n < line.length && line[n] === ' ')
+        n++;
+    return n;
+}
+function replaceDefaultValue(line, newValue) {
+    const m = DEFAULT_LINE_RE.exec(line);
+    if (!m)
+        return line;
+    const prefix = m[1];
+    const trailingComment = m[2] ?? '';
+    return `${prefix}${newValue}${trailingComment}`;
+}
+export function formatYamlValue(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return String(value);
+    const dumped = yaml.dump(value, {
+        flowLevel: 0,
+        lineWidth: -1,
+        noRefs: true,
+    }).replace(/\r?\n$/, '');
+    return dumped;
+}
+//# sourceMappingURL=yaml-defaults-writer.js.map

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

@@ -45,6 +45,7 @@ export async function bridgeRunSpell(content, sourceFile, args, options = {}) {
             signal: controller.signal,
             memory: options.memory,
             credentials,
+            forceCredentialReprompt: options.forceCredentialReprompt,
             ...(options.projectRoot ? { projectRoot: options.projectRoot } : {}),
             ...(sandboxConfig ? { sandboxConfig } : {}),
         });
@@ -68,6 +69,7 @@ export async function bridgeExecuteSpell(definition, args, options = {}) {
         return await runner.run(definition, args, {
             spellId,
             signal: controller.signal,
+            forceCredentialReprompt: options.forceCredentialReprompt,
             ...(options.projectRoot ? { projectRoot: options.projectRoot } : {}),
             ...(sandboxConfig ? { sandboxConfig } : {}),
         });

package/dist/src/cli/swarm/message-bus/write-through-adapter.js

@@ -101,16 +101,17 @@ export class WriteThroughAdapter {
             // Best-effort cleanup
         }
     }
-    /**
-     * Wait for every fire-and-forget write currently in flight to settle.
-     * No-op when no writes are queued. Bounded by `Promise.allSettled` so a
-     * single hung write can't block forever (each individual write has its
-     * own daemon-write-client timeout).
-     */
+    // #1003 — yield to the microtask queue and re-check until pendingWrites
+    // settles. The single-snapshot pattern lost a race on fast hosts (Ubuntu CI)
+    // where a caller's awaited bus.sendUnified resolved before its `.then()`
+    // chain registered the write-through promise.
     async drainPendingWrites() {
-        if (this.pendingWrites.size === 0)
-            return;
-        await Promise.allSettled([...this.pendingWrites]);
+        for (let i = 0; i < 5; i++) {
+            await Promise.resolve();
+            if (this.pendingWrites.size === 0)
+                return;
+            await Promise.allSettled([...this.pendingWrites]);
+        }
     }
     onUnifiedMessage(event) {
         if (!event.namespace || !this.enabledNamespaces.has(event.namespace)) {

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.27';
+export const VERSION = '4.9.29';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.27",
+  "version": "4.9.29",
   "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",
@@ -84,7 +84,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.26",
+    "moflo": "^4.9.28",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/src/cli/spells/definitions/epic-auto-merge.yaml

@@ -87,8 +87,12 @@ steps:
         # elevated — bwrap network access for git pull (see single-branch create-branch).
         permissionLevel: elevated
         preflight:
+          # `git diff --name-only --diff-filter=U` always exits 0 — it just
+          # lists paths. Use `--quiet`, which exits 1 when any unmerged path
+          # exists, so this preflight actually catches a half-merged index
+          # (e.g. left by an earlier failed run).
           - name: "no unmerged files"
-            command: "git diff --name-only --diff-filter=U"
+            command: "git diff --quiet --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)"
@@ -97,7 +101,7 @@ steps:
             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'"
+                command: "git stash push --include-untracked --message 'moflo-epic-{args.epic_number}-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)"
@@ -106,7 +110,7 @@ steps:
             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'"
+                command: "git stash push --include-untracked --message 'moflo-epic-{args.epic_number}-autostash'"
               - label: "Commit staged changes to the current branch first, then continue"
                 command: "git commit -m 'wip: pre-epic snapshot'"
           - name: "gh cli authenticated"
@@ -116,9 +120,28 @@ steps:
             command: "git remote get-url origin"
             hint: "This repo has no 'origin' remote. Set one with: git remote add origin <url>"
         config:
-          # set -e: fail fast if checkout/pull fails; otherwise the trailing
-          # `stash pop ... || true` would mask the real failure.
-          command: "set -e; git stash --include-untracked -q 2>/dev/null || true; git checkout {args.base_branch}; git pull origin {args.base_branch}; git stash pop -q 2>/dev/null || true"
+          # set -e: fail fast if checkout/pull fails.
+          #
+          # We deliberately do NOT auto-stash here. Preflight enforces a clean
+          # tree (or runs the user-chosen stash-and-carry resolution), so the
+          # only stash we should ever pop is the preflight's
+          # `moflo-epic-autostash` marker. Popping the unconditionally-top
+          # stash (the previous design) was the source of #287's stash-pop
+          # conflict that left the index half-merged.
+          command: |
+            set -e
+            git checkout {args.base_branch}
+            git pull origin {args.base_branch}
+            # Scoped by epic_number to prevent a stale autostash from an
+            # unrelated abandoned run getting popped here.
+            EXPECTED_STASH_TAG="moflo-epic-{args.epic_number}-autostash"
+            TOP_MSG=$(git stash list --format='%s' -1)
+            if [[ "$TOP_MSG" == *"$EXPECTED_STASH_TAG"* ]]; then
+              if ! git stash pop -q; then
+                echo "[epic] carrying-over stash conflicted on {args.base_branch} — resolve unmerged paths and re-run the spell" >&2
+                exit 1
+              fi
+            fi
           failOnError: true
 
       # 2: Spawn Claude agent to implement the story (creates branch + PR)
@@ -155,7 +178,20 @@ steps:
         permissionLevel: elevated
         config:
           # set -e: fail fast if checkout/pull fails (see checkout-base).
-          command: "set -e; git stash --include-untracked -q 2>/dev/null || true; git checkout {args.base_branch}; git pull origin {args.base_branch}; git stash pop -q 2>/dev/null || true"
+          # No in-step stash; pop only the preflight's autostash marker
+          # (scoped by epic_number — see checkout-base).
+          command: |
+            set -e
+            git checkout {args.base_branch}
+            git pull origin {args.base_branch}
+            EXPECTED_STASH_TAG="moflo-epic-{args.epic_number}-autostash"
+            TOP_MSG=$(git stash list --format='%s' -1)
+            if [[ "$TOP_MSG" == *"$EXPECTED_STASH_TAG"* ]]; then
+              if ! git stash pop -q; then
+                echo "[epic] carrying-over stash conflicted on {args.base_branch} — resolve unmerged paths and re-run the spell" >&2
+                exit 1
+              fi
+            fi
           failOnError: true
 
       # 6: Comment on epic with progress

package/src/cli/spells/definitions/epic-single-branch.yaml

@@ -87,8 +87,12 @@ steps:
     # has working network.
     permissionLevel: elevated
     preflight:
+      # `git diff --name-only --diff-filter=U` always exits 0 — it just lists
+      # paths. Use `--quiet`, which exits 1 when any unmerged path exists, so
+      # the preflight actually catches a half-merged index left by an earlier
+      # failed run (e.g. a stash-pop conflict).
       - name: "no unmerged files"
-        command: "git diff --name-only --diff-filter=U"
+        command: "git diff --quiet --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)"
@@ -97,7 +101,7 @@ steps:
         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'"
+            command: "git stash push --include-untracked --message 'moflo-epic-{args.epic_number}-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)"
@@ -106,18 +110,45 @@ steps:
         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'"
+            command: "git stash push --include-untracked --message 'moflo-epic-{args.epic_number}-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:
-      # set -e: any failing step aborts the whole command. Without it, the
-      # trailing `git stash pop ... || true` would swallow real failures
-      # (e.g., checkout/pull/branch-create errors) and report success,
-      # leaving later steps to crash when the epic branch isn't there.
-      command: "set -e; git stash --include-untracked -q 2>/dev/null || true; git checkout {args.base_branch}; git pull origin {args.base_branch}; BRANCH=\"epic/{args.epic_number}-{args.epic_slug}\"; if git show-ref --verify --quiet \"refs/heads/$BRANCH\"; then git checkout \"$BRANCH\"; else git checkout -b \"$BRANCH\"; fi; git stash pop -q 2>/dev/null || true"
+      # set -e: any failing step aborts the whole command.
+      #
+      # We deliberately do NOT auto-stash here. Preflight has already enforced
+      # a clean tree (or run the user-chosen stash-and-carry resolution), so
+      # the only stash we should ever pop is the preflight's `moflo-epic-autostash`
+      # marker. Popping the unconditionally-top stash (the previous design)
+      # was the source of #287's stash-pop conflict that left the index
+      # half-merged — `git stash pop ... || true` masked the conflict
+      # failure and the next step's `git checkout` then died with
+      # "you need to resolve your current index first".
+      command: |
+        set -e
+        git checkout {args.base_branch}
+        git pull origin {args.base_branch}
+        BRANCH="epic/{args.epic_number}-{args.epic_slug}"
+        if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
+          git checkout "$BRANCH"
+        else
+          git checkout -b "$BRANCH"
+        fi
+        # Scope the marker by epic_number so a stale autostash from an
+        # abandoned previous run of a DIFFERENT epic doesn't get popped onto
+        # this branch unintentionally. Same-epic re-runs still carry over,
+        # which is the intended recovery path.
+        EXPECTED_STASH_TAG="moflo-epic-{args.epic_number}-autostash"
+        TOP_MSG=$(git stash list --format='%s' -1)
+        if [[ "$TOP_MSG" == *"$EXPECTED_STASH_TAG"* ]]; then
+          if ! git stash pop -q; then
+            echo "[epic] carrying-over stash conflicted on $BRANCH — resolve unmerged paths and re-run the spell" >&2
+            exit 1
+          fi
+        fi
       timeout: 120000
       failOnError: true