moflo 4.8.86 → 4.8.87-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.86",
+  "version": "4.8.87-rc.1",
   "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",
@@ -117,7 +117,7 @@
     "@types/node": "^24.12.2",
     "@xenova/transformers": "^2.17.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.8.85",
+    "moflo": "^4.8.86",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

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

@@ -32,6 +32,32 @@ arguments:
 
 mofloLevel: hooks
 
+# Command-presence checks — fail fast with an actionable message if any
+# of these aren't on PATH. Runtime-state checks (auth, dirty tree, remote)
+# still live on the individual steps that need them via `preflight:`.
+prerequisites:
+  - name: gh-cli
+    description: GitHub CLI is required to read issues and manage PRs
+    docsUrl: https://cli.github.com
+    detect:
+      type: command
+      command: gh
+    promptOnMissing: false
+  - name: git
+    description: Git is required for branch management
+    docsUrl: https://git-scm.com/downloads
+    detect:
+      type: command
+      command: git
+    promptOnMissing: false
+  - name: claude-cli
+    description: Claude Code CLI is required to run the story implementer subagent
+    docsUrl: https://docs.anthropic.com/en/docs/claude-code
+    detect:
+      type: command
+      command: claude
+    promptOnMissing: false
+
 steps:
   # Step 1: Initialize epic state in memory (enables resume)
   - id: init-state

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

@@ -37,6 +37,32 @@ arguments:
 
 mofloLevel: hooks
 
+# Command-presence checks — fail fast with an actionable message if any
+# of these aren't on PATH. Runtime-state checks (auth, dirty tree, remote)
+# still live on the individual steps that need them via `preflight:`.
+prerequisites:
+  - name: gh-cli
+    description: GitHub CLI is required to read issues and manage PRs
+    docsUrl: https://cli.github.com
+    detect:
+      type: command
+      command: gh
+    promptOnMissing: false
+  - name: git
+    description: Git is required for branch management
+    docsUrl: https://git-scm.com/downloads
+    detect:
+      type: command
+      command: git
+    promptOnMissing: false
+  - name: claude-cli
+    description: Claude Code CLI is required to run the story implementer subagent
+    docsUrl: https://docs.anthropic.com/en/docs/claude-code
+    detect:
+      type: command
+      command: claude
+    promptOnMissing: false
+
 steps:
   # Step 1: Initialize epic state in memory (enables resume)
   - id: init-state

package/src/modules/cli/dist/src/services/headless-worker-executor.js

@@ -340,6 +340,23 @@ export function getWorkerConfig(type) {
 // ============================================
 // HeadlessWorkerExecutor Class
 // ============================================
+// Module-level registry + single process 'exit' listener.
+// Attaching the listener per instance leaked handlers (MaxListenersExceededWarning
+// after ~11 daemons), so we install one global listener that walks a live registry.
+// Instances remove themselves on dispose() for long-running hosts / test suites.
+const liveExecutors = new Set();
+let exitListenerInstalled = false;
+function ensureExitListener() {
+    if (exitListenerInstalled)
+        return;
+    exitListenerInstalled = true;
+    // 'exit' (not 'beforeExit') fires on explicit process.exit(); handler must be sync.
+    process.on('exit', () => {
+        for (const executor of liveExecutors) {
+            executor._killPoolOnExit();
+        }
+    });
+}
 /**
  * HeadlessWorkerExecutor - Executes workers using Claude Code in headless mode
  *
@@ -374,20 +391,29 @@ export class HeadlessWorkerExecutor extends EventEmitter {
         };
         // Ensure log directory exists
         this.ensureLogDir();
-        // Kill child processes on parent exit to prevent orphaned node processes.
-        // Uses 'exit' (not 'beforeExit') so it fires even on explicit process.exit().
-        // The handler must be synchronous — no async work allowed in 'exit' handlers.
-        process.on('exit', () => {
-            for (const [, entry] of this.processPool) {
-                try {
-                    clearTimeout(entry.timeout);
-                    entry.process.kill('SIGTERM');
-                }
-                catch {
-                    // Process already gone — ignore
-                }
+        // Register for process-exit cleanup via the shared listener.
+        ensureExitListener();
+        liveExecutors.add(this);
+    }
+    /**
+     * Remove this executor from the exit-cleanup registry. Call when the host
+     * (daemon / test) is done with the instance — otherwise the registry
+     * retains a strong ref via the pool/cache Maps.
+     */
+    dispose() {
+        liveExecutors.delete(this);
+    }
+    /** @internal — invoked by the shared process-exit listener. Must stay sync. */
+    _killPoolOnExit() {
+        for (const [, entry] of this.processPool) {
+            try {
+                clearTimeout(entry.timeout);
+                entry.process.kill('SIGTERM');
             }
-        });
+            catch {
+                // Process already gone — ignore
+            }
+        }
     }
     // ============================================
     // Public API

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.86';
+export const VERSION = '4.8.87-rc.1';
 //# sourceMappingURL=version.js.map

package/src/modules/cli/package.json

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

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

@@ -10,9 +10,9 @@
  *   2. ISO timestamp `fallbackDaysAgo` days in the past, if provided
  *   3. empty string
  */
-import * as readline from 'node:readline';
 import { interpolateString } from '../core/interpolation.js';
 import { acquireTTYLock } from '../core/tty-lock.js';
+import { readLineFromStdin } from '../core/stdin-reader.js';
 /**
  * Resolve the effective default, walking the fallback chain.
  * Exported for testing.
@@ -31,30 +31,6 @@ export function resolveDefault(raw, fallbackDaysAgo, now = Date.now()) {
     }
     return '';
 }
-/**
- * Read one line from stdin. Resolves with the trimmed line (empty string
- * if the user just hit enter). Honors the provided abort signal.
- */
-async function readLineFromStdin(prompt, abortSignal) {
-    return new Promise((resolve, reject) => {
-        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-        const onAbort = () => { rl.close(); reject(new Error('Prompt aborted')); };
-        if (abortSignal) {
-            if (abortSignal.aborted) {
-                rl.close();
-                reject(new Error('Prompt aborted'));
-                return;
-            }
-            abortSignal.addEventListener('abort', onAbort, { once: true });
-        }
-        rl.question(prompt, (answer) => {
-            if (abortSignal)
-                abortSignal.removeEventListener('abort', onAbort);
-            rl.close();
-            resolve(answer.trim());
-        });
-    });
-}
 export const promptCommand = {
     type: 'prompt',
     description: 'Ask the user a question and capture the response',

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

@@ -27,8 +27,10 @@ export const VAR_REF_PATTERN = /(?<!\$)\{([A-Za-z_][A-Za-z0-9_.-]*)\}/g;
 /**
  * Resolution precedence:
  * 1. {args.key} — explicit args prefix (depth-2 only)
- * 2. {stepId.outputKey} — walk context.variables
- * 3. {key} — single-segment fallback to context.args
+ * 2. {env.KEY} — environment variable (depth-2 only); typically populated
+ *    by a spell-level `prerequisites:` entry with `promptOnMissing: true`
+ * 3. {stepId.outputKey} — walk context.variables
+ * 4. {key} — single-segment fallback to context.args
  */
 function resolveVariable(path, context) {
     const segments = path.split('.');
@@ -38,6 +40,12 @@ function resolveVariable(path, context) {
         if (val !== undefined)
             return val;
     }
+    // Environment variable prefix: {env.KEY}
+    if (segments[0] === 'env' && segments.length === 2) {
+        const val = process.env[segments[1]];
+        if (val !== undefined && val.length > 0)
+            return val;
+    }
     // Walk context.variables (step outputs): {stepId.outputKey}
     let value = context.variables;
     for (const segment of segments) {

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

@@ -1,13 +1,23 @@
 /**
  * Prerequisite Checker
  *
- * Collects and deduplicates prerequisites from all spell steps,
- * runs each check once, and returns structured results.
+ * Collects prerequisites from three sources (declarative YAML at spell and
+ * step level + imperative step-command-owned), dedupes by name, runs each
+ * detector once, and — when stdin is a TTY — prompts for unmet env-type
+ * prereqs and writes the answer into process.env so downstream steps
+ * (including nested loop bodies) inherit it.
  *
- * Story #193: Spell engine prerequisites system.
+ * Non-TTY failure path reports every unmet prereq with its docs URL so the
+ * caller sees the full picture rather than failing mid-cast.
+ *
+ * Story #193: initial step-command-owned prereqs.
+ * Issue #460: YAML-declared + interactive preflight walker.
  */
 import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
 import { promisify } from 'node:util';
+import { acquireTTYLock } from './tty-lock.js';
+import { readLineFromStdin } from './stdin-reader.js';
 const execFileAsync = promisify(execFile);
 /** Check whether a CLI command is available on the system PATH. */
 export async function commandExists(cmd) {
@@ -21,23 +31,92 @@ export async function commandExists(cmd) {
     }
 }
 /**
- * Collect unique prerequisites from all steps in a spell definition.
- * Deduplicates by prerequisite name (first occurrence wins).
+ * Compile a declarative YAML `PrerequisiteSpec` into the imperative
+ * `Prerequisite` shape — synthesizes a `check()` that dispatches on the
+ * detector type and populates the prompt-resolution metadata.
+ */
+export function compilePrerequisiteSpec(spec) {
+    const detect = spec.detect;
+    const check = async () => {
+        switch (detect.type) {
+            case 'env': {
+                const val = process.env[detect.key];
+                return typeof val === 'string' && val.length > 0;
+            }
+            case 'command':
+                return commandExists(detect.command);
+            case 'file':
+                try {
+                    await access(detect.path);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+        }
+    };
+    const installHint = spec.description ?? defaultHintForDetect(spec);
+    const envKey = detect.type === 'env' ? detect.key : undefined;
+    const promptOnMissing = spec.promptOnMissing ?? true;
+    return {
+        name: spec.name,
+        check,
+        installHint,
+        url: spec.docsUrl,
+        description: spec.description,
+        promptOnMissing,
+        envKey,
+    };
+}
+function defaultHintForDetect(spec) {
+    switch (spec.detect.type) {
+        case 'env': return `Set the ${spec.detect.key} environment variable`;
+        case 'command': return `Install "${spec.detect.command}" and add it to your PATH`;
+        case 'file': return `Ensure the file exists: ${spec.detect.path}`;
+    }
+}
+/**
+ * Collect unique prerequisites from a spell. Sources, in order:
+ *   1. spell-level YAML (`definition.prerequisites`)
+ *   2. step-level YAML (including nested loop/condition/parallel bodies)
+ *   3. step-command built-ins (imperative, from the registry)
+ *
+ * Deduplicates by name — first occurrence wins.
  */
 export function collectPrerequisites(definition, registry) {
     const seen = new Map();
-    for (const step of definition.steps) {
-        const command = registry.get(step.type);
-        if (!command?.prerequisites)
-            continue;
-        for (const prereq of command.prerequisites) {
-            if (!seen.has(prereq.name)) {
-                seen.set(prereq.name, prereq);
+    if (definition.prerequisites) {
+        for (const spec of definition.prerequisites) {
+            if (!seen.has(spec.name)) {
+                seen.set(spec.name, compilePrerequisiteSpec(spec));
             }
         }
     }
+    collectFromSteps(definition.steps, registry, seen);
     return Array.from(seen.values());
 }
+function collectFromSteps(steps, registry, seen) {
+    for (const step of steps) {
+        if (step.prerequisites) {
+            for (const spec of step.prerequisites) {
+                if (!seen.has(spec.name)) {
+                    seen.set(spec.name, compilePrerequisiteSpec(spec));
+                }
+            }
+        }
+        const command = registry.get(step.type);
+        if (command?.prerequisites) {
+            for (const prereq of command.prerequisites) {
+                if (!seen.has(prereq.name)) {
+                    seen.set(prereq.name, prereq);
+                }
+            }
+        }
+        if (step.steps && step.steps.length > 0) {
+            collectFromSteps(step.steps, registry, seen);
+        }
+    }
+}
 /**
  * Run all prerequisite checks concurrently. Errors are treated as unsatisfied.
  */
@@ -73,4 +152,94 @@ export function formatPrerequisiteErrors(results) {
     }
     return lines.join('\n');
 }
+/**
+ * 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.
+ */
+export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
+    if (prerequisites.length === 0) {
+        return { ok: true, resolvedNames: [] };
+    }
+    const interactive = options.interactive
+        ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const log = options.log ?? ((line) => console.log(line));
+    const initial = await checkPrerequisites(prerequisites);
+    const unmet = prerequisites.filter((_, i) => !initial[i].satisfied);
+    if (unmet.length === 0) {
+        return { ok: true, resolvedNames: [] };
+    }
+    const promptable = unmet.filter(p => interactive && p.promptOnMissing === true && typeof p.envKey === 'string');
+    if (!interactive || promptable.length === 0) {
+        return {
+            ok: false,
+            message: formatPrerequisiteErrors(initial),
+            resolvedNames: [],
+        };
+    }
+    printPreflightBanner(log, unmet.length);
+    const promptLine = options.promptLine ?? readLineFromStdin;
+    const resolvedNames = [];
+    const lock = acquireTTYLock();
+    try {
+        for (const prereq of promptable) {
+            if (options.abortSignal?.aborted) {
+                return {
+                    ok: false,
+                    message: 'Prerequisite resolution aborted',
+                    resolvedNames,
+                };
+            }
+            if (prereq.description)
+                log(prereq.description);
+            if (prereq.url)
+                log(`  Docs: ${prereq.url}`);
+            const prompt = `  ${prereq.name} > `;
+            let answer;
+            try {
+                answer = await promptLine(prompt, options.abortSignal);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    message: `Prerequisite "${prereq.name}" prompt failed: ${err.message}`,
+                    resolvedNames,
+                };
+            }
+            if (!answer || answer.length === 0) {
+                return {
+                    ok: false,
+                    message: `Prerequisite "${prereq.name}" was not provided`,
+                    resolvedNames,
+                };
+            }
+            if (prereq.envKey) {
+                process.env[prereq.envKey] = answer;
+            }
+            resolvedNames.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) {
+        return {
+            ok: false,
+            message: formatPrerequisiteErrors(rerun),
+            resolvedNames,
+        };
+    }
+    return { ok: true, resolvedNames };
+}
+function printPreflightBanner(log, unmetCount) {
+    log('');
+    log('\x1b[1;36m━━━ Preflight: missing prerequisites ━━━\x1b[0m');
+    log(`${unmetCount} prerequisite${unmetCount === 1 ? '' : 's'} need${unmetCount === 1 ? 's' : ''} a value before this spell can cast.`);
+    log('');
+}
 //# sourceMappingURL=prerequisite-checker.js.map

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

@@ -8,7 +8,7 @@ import { executeParallelSteps } from './parallel-executor.js';
 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 { collectPrerequisites, resolveUnmetPrerequisites } from './prerequisite-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';
@@ -99,15 +99,18 @@ export class SpellCaster {
                 }
             }
         }
-        // Pre-flight prerequisite checks (Story #193)
+        // Pre-flight prerequisite checks — walks YAML + step-command sources,
+        // prompts on a TTY for unmet env-type prereqs (issue #460).
         if (!options.dryRun) {
             const prerequisites = collectPrerequisites(definition, this.registry);
             if (prerequisites.length > 0) {
-                const prereqResults = await checkPrerequisites(prerequisites);
-                if (prereqResults.some(r => !r.satisfied)) {
+                const resolution = await resolveUnmetPrerequisites(prerequisites, {
+                    abortSignal: options.signal,
+                });
+                if (!resolution.ok) {
                     return this.failureResult(spellId, startTime, [{
                             code: 'PREREQUISITES_FAILED',
-                            message: formatPrerequisiteErrors(prereqResults),
+                            message: resolution.message ?? 'Prerequisites failed',
                         }], definition.name);
                 }
             }

package/src/modules/spells/dist/core/stdin-reader.js

@@ -0,0 +1,33 @@
+/**
+ * Stdin reader — shared interactive-line-of-input helper.
+ *
+ * Used by both the `prompt` step command and the issue-#460 prerequisite
+ * preflight walker; keeps the abort-signal + trimming semantics in one place.
+ */
+import * as readline from 'node:readline';
+/**
+ * Read one line from stdin, emitting `promptText` first. Resolves with the
+ * user's trimmed answer (empty string if they just hit enter). Honors an
+ * optional abort signal — rejects with `Error('Prompt aborted')` if fired.
+ */
+export async function readLineFromStdin(promptText, abortSignal) {
+    return new Promise((resolve, reject) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const onAbort = () => { rl.close(); reject(new Error('Prompt aborted')); };
+        if (abortSignal) {
+            if (abortSignal.aborted) {
+                rl.close();
+                reject(new Error('Prompt aborted'));
+                return;
+            }
+            abortSignal.addEventListener('abort', onAbort, { once: true });
+        }
+        rl.question(promptText, (answer) => {
+            if (abortSignal)
+                abortSignal.removeEventListener('abort', onAbort);
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+//# sourceMappingURL=stdin-reader.js.map

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

@@ -18,7 +18,7 @@ export { ConnectorAccessorImpl } from './core/connector-accessor.js';
 export { GatedConnectorAccessor } from './core/gated-connector-accessor.js';
 export { checkCapabilities, } from './core/capability-validator.js';
 export { CapabilityGateway, CapabilityDeniedError, DenyAllGateway, DENY_ALL_GATEWAY, discloseStep, discloseSpell, formatStepDisclosure, formatSpellDisclosure, } from './core/capability-gateway.js';
-export { collectPrerequisites, checkPrerequisites, formatPrerequisiteErrors, commandExists, } from './core/prerequisite-checker.js';
+export { collectPrerequisites, checkPrerequisites, formatPrerequisiteErrors, commandExists, compilePrerequisiteSpec, resolveUnmetPrerequisites, } from './core/prerequisite-checker.js';
 export { detectSandboxCapability, resetSandboxCache, resolveSandboxConfig, resolveEffectiveSandbox, formatSandboxLog, loadSandboxConfigFromProject, DEFAULT_SANDBOX_CONFIG, } from './core/platform-sandbox.js';
 export { resolveScopePath, } from './core/sandbox-utils.js';
 export { generateSandboxProfile, wrapWithSandboxExec, } from './core/sandbox-profile.js';