moflo 4.8.64 → 4.8.66

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -584,8 +584,16 @@ status_line:
   show_adrs: true                # ADR compliance (dashboard only)
   show_agentdb: true             # AgentDB vectors/size (dashboard only)
   show_tests: true               # Test file count (dashboard only)
+
+# Spell step sandboxing (OS-level process isolation for bash steps)
+# Platform support: macOS (sandbox-exec), Linux/WSL (bwrap). Windows has no OS sandbox.
+sandbox:
+  enabled: false                 # Set to true to wrap bash steps in an OS sandbox
+  tier: auto                     # auto | denylist-only | full
 ```
 
+If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
+
 ### Key Behaviors
 
 | Config | Effect |
@@ -606,6 +614,9 @@ status_line:
 | `model_routing.enabled: true` | Auto-select haiku/sonnet/opus based on task complexity |
 | `status_line.mode: dashboard` | Switch to multi-line status display |
 | `status_line.show_swarm: false` | Hide swarm agent count from status bar |
+| `sandbox.enabled: true` | Wrap bash steps in an OS sandbox (macOS/Linux/WSL) — absolute disable when `false`, regardless of tier |
+| `sandbox.tier: full` | Require OS sandbox; throw at runtime if the platform tool is unavailable |
+| `sandbox.tier: denylist-only` | Keep Layer 1 denylist only; skip OS isolation even when enabled |
 
 ---
 

package/.claude/guidance/shipped/moflo-spell-sandboxing.md

@@ -210,6 +210,29 @@ The engine **automatically rewrites** `claude -p` commands in bash steps — str
 | **[SENSITIVE]** | `agent`, `net`, `browser` | Can read external data or spawn processes |
 | **[DESTRUCTIVE]** | `shell`, `fs:write`, `browser:evaluate`, `credentials` | Can permanently modify/delete data |
 
+## OS-Level Sandbox Configuration (`moflo.yaml`)
+
+Capabilities and the gateway always apply. An **additional** OS-level process sandbox (Layer 3) wraps bash steps on macOS (`sandbox-exec`) and Linux/WSL (`bwrap`). It is controlled by the `sandbox:` block in `moflo.yaml`:
+
+```yaml
+sandbox:
+  enabled: false   # Master toggle — false = OS sandbox off (denylist + gateway still apply)
+  tier: auto       # auto | denylist-only | full
+```
+
+Semantics (from `resolveEffectiveSandbox()` in `src/modules/spells/src/core/platform-sandbox.ts`):
+
+| `enabled` | `tier` | Tool available | OS sandbox runs? | Notes |
+|-----------|--------|----------------|------------------|-------|
+| `false` | (any) | (any) | No | **Absolute disable** — master toggle wins |
+| `true` | `auto` | Yes | Yes | Use detected tool (bwrap/sandbox-exec) |
+| `true` | `auto` | No | No | Graceful fallback; logs "not available" |
+| `true` | `denylist-only` | (any) | No | Layer 1 only, skip OS isolation |
+| `true` | `full` | Yes | Yes | Require OS sandbox |
+| `true` | `full` | No | — | **Throws** at spell start |
+
+Existing projects that predate this block get it auto-appended on session start — never require `moflo init` to re-run after a version bump.
+
 ## See Also
 
 - `.claude/guidance/shipped/moflo-spell-engine.md` — Spell engine usage and YAML format

package/bin/lib/yaml-upgrader.mjs

@@ -0,0 +1,80 @@
+/**
+ * moflo.yaml section upgrader.
+ *
+ * Users must never be required to re-run `moflo init` after upgrading moflo.
+ * When we ship a new top-level config section (e.g. `sandbox:`), this module
+ * idempotently appends the missing block — with sensible defaults and inline
+ * comments — to the user's existing moflo.yaml, without touching any values
+ * they've already set.
+ *
+ * See: .claude/guidance/internal/upgrade-contract.md
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+
+/**
+ * Registry of top-level config sections that moflo ships with default blocks.
+ *
+ * Each entry: { key, block } where `block` is the raw YAML snippet (including
+ * its leading comment) to append when the top-level `<key>:` is absent.
+ *
+ * When adding a new top-level section to the init template in moflo-init.ts,
+ * also add the same block here so existing users get it on their next session.
+ */
+export const REQUIRED_SECTIONS = [
+  {
+    key: 'sandbox',
+    block: `# Spell step sandboxing (OS-level process isolation for bash steps)
+# Platform support: macOS (sandbox-exec), Linux/WSL (bwrap). Windows has no OS sandbox.
+# Tiers:
+#   auto          — Use best available sandbox for this platform (recommended when enabled)
+#   denylist-only — Layer 1 only: block catastrophic commands, no OS isolation
+#   full          — Require full OS isolation; throws if the sandbox tool is unavailable
+sandbox:
+  enabled: false                 # Set to true to wrap bash steps in an OS sandbox
+  tier: auto                     # auto | denylist-only | full
+`,
+  },
+];
+
+/**
+ * Return true if the YAML text already defines the given top-level key.
+ * Matches `^<key>:` at column 0 on any line, which is how YAML roots look.
+ */
+export function hasTopLevelSection(yamlText, key) {
+  const pattern = new RegExp(`^${key}\\s*:`, 'm');
+  return pattern.test(yamlText);
+}
+
+/**
+ * Compute what ensureYamlSections() would append, without writing anything.
+ * Returns the list of section keys that are missing from the given yaml text.
+ */
+export function missingSections(yamlText, registry = REQUIRED_SECTIONS) {
+  return registry
+    .filter((entry) => !hasTopLevelSection(yamlText, entry.key))
+    .map((entry) => entry.key);
+}
+
+/**
+ * Append any missing registered sections to the yaml file at `yamlPath`.
+ *
+ * - Idempotent: sections already present are left alone.
+ * - Non-destructive: user values are never read, parsed, or rewritten.
+ * - Returns the list of section keys that were appended (empty if no change).
+ */
+export function ensureYamlSections(yamlPath, registry = REQUIRED_SECTIONS) {
+  if (!existsSync(yamlPath)) return [];
+
+  const original = readFileSync(yamlPath, 'utf-8');
+  const toAppend = registry.filter((entry) => !hasTopLevelSection(original, entry.key));
+  if (toAppend.length === 0) return [];
+
+  const needsTrailingNewline = !original.endsWith('\n');
+  const separator = needsTrailingNewline ? '\n\n' : original.endsWith('\n\n') ? '' : '\n';
+  const appended = toAppend.map((entry) => entry.block.trimEnd()).join('\n\n');
+  const next = `${original}${separator}${appended}\n`;
+
+  writeFileSync(yamlPath, next, 'utf-8');
+  return toAppend.map((entry) => entry.key);
+}

package/bin/session-start-launcher.mjs

@@ -355,6 +355,25 @@ try {
   }
 } catch { /* non-fatal */ }
 
+// ── 3d-yaml. Append missing top-level sections to moflo.yaml ───────────────
+// Users must never be required to re-run `moflo init` after a version bump.
+// When moflo ships a new top-level config section (e.g. sandbox:), append it
+// with defaults + comments if the user's yaml doesn't already have it.
+// Fully idempotent and never touches user-set values.
+// See: .claude/guidance/internal/upgrade-contract.md
+try {
+  const upgraderPaths = [
+    resolve(projectRoot, 'node_modules/moflo/bin/lib/yaml-upgrader.mjs'),
+    resolve(projectRoot, 'bin/lib/yaml-upgrader.mjs'),
+  ];
+  const upgraderPath = upgraderPaths.find((p) => existsSync(p));
+  const mofloYaml = resolve(projectRoot, 'moflo.yaml');
+  if (upgraderPath && existsSync(mofloYaml)) {
+    const { ensureYamlSections } = await import(`file://${upgraderPath.replace(/\\/g, '/')}`);
+    ensureYamlSections(mofloYaml);
+  }
+} catch { /* non-fatal — yaml stays as-is, user can still edit manually */ }
+
 // ── 3d. Ensure global `flo` shim exists ─────────────────────────────────────
 // Installs a tiny shim into npm's global bin so bare `flo` resolves to the
 // local project's node_modules/.bin/flo. Idempotent — skips if already present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.64",
+  "version": "4.8.66",
   "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",
@@ -112,7 +112,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.19.37",
     "eslint": "^8.0.0",
-    "moflo": "^4.8.63",
+    "moflo": "^4.8.65",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

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

@@ -340,6 +340,16 @@ mcp:
   tool_defer: deferred           # Defer 150+ tool schemas; loaded on demand via ToolSearch
   auto_start: false              # Auto-start MCP server on session begin
 
+# Spell step sandboxing (OS-level process isolation for bash steps)
+# Platform support: macOS (sandbox-exec), Linux/WSL (bwrap). Windows has no OS sandbox.
+# Tiers:
+#   auto          — Use best available sandbox for this platform (recommended when enabled)
+#   denylist-only — Layer 1 only: block catastrophic commands, no OS isolation
+#   full          — Require full OS isolation; throws if the sandbox tool is unavailable
+sandbox:
+  enabled: false                 # Set to true to wrap bash steps in an OS sandbox
+  tier: auto                     # auto | denylist-only | full
+
 # Status line display (shown at bottom of Claude Code)
 # mode: "compact" (default), "single-line", or "dashboard" (full multi-line)
 status_line:

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

@@ -60,7 +60,8 @@ async function executeAndTrack(engine, definition, args) {
     const spellId = `sp-${Date.now()}`;
     const tracked = trackStart(spellId, definition.name, definition.description);
     try {
-        const result = await engine.bridgeExecuteSpell(definition, args, { spellId });
+        const sandboxConfig = await engine.loadSandboxConfigFromProject(findProjectRoot());
+        const result = await engine.bridgeExecuteSpell(definition, args, { spellId, sandboxConfig });
         trackResult(tracked, result);
         return serializeResult(result);
     }
@@ -202,7 +203,8 @@ export const spellTools = [
             }
             // Run from raw content via bridge
             const engine = await loadSpellEngine();
-            const result = await engine.bridgeRunSpell(content, sourceFile, args, { dryRun });
+            const sandboxConfig = await engine.loadSandboxConfigFromProject(findProjectRoot());
+            const result = await engine.bridgeRunSpell(content, sourceFile, args, { dryRun, sandboxConfig });
             const tracked = trackStart(result.spellId, spellName);
             trackResult(tracked, result);
             return serializeResult(result);

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

package/src/modules/cli/package.json

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

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

@@ -152,11 +152,12 @@ export async function loadSandboxConfigFromProject(projectRoot) {
 /**
  * Combine detected capability with user config to determine effective sandbox behavior.
  *
+ * @param config — resolved user config (enabled + tier)
+ * @param capability — optional capability override (for tests; skips OS detection)
  * @returns EffectiveSandbox — includes display status for spell-start logging.
  * @throws Error if tier is 'full' but no OS sandbox is available.
  */
-export function resolveEffectiveSandbox(config) {
-    const capability = detectSandboxCapability();
+export function resolveEffectiveSandbox(config, capability = detectSandboxCapability()) {
     // Config disabled or tier is denylist-only => no OS sandbox
     if (!config.enabled || config.tier === 'denylist-only') {
         return {