moflo 4.8.69 → 4.8.71

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

@@ -233,6 +233,71 @@ Semantics (from `resolveEffectiveSandbox()` in `src/modules/spells/src/core/plat
 
 Existing projects that predate this block get it auto-appended on session start — never require `moflo init` to re-run after a version bump.
 
+## Authoring Checklist — Always Double-Check Step Permissions
+
+Before shipping any new or edited spell step, walk through every item. Silently-missing permissions don't fail with `CAPABILITY_DENIED` — they fail confusingly several steps later.
+
+1. **What does the command actually do?** List every external effect — file reads/writes, git/gh calls, outbound HTTP, Claude subagents, credential use.
+2. **Which capabilities map to those effects?** `fs:read`, `fs:write`, `shell`, `net`, `credentials`, `agent`, `browser`, `memory`.
+3. **What is the minimum `permissionLevel`?**
+   - Pure analysis (read only) → `readonly`
+   - Edits project files but no shell/network → `standard`
+   - Runs shell commands, **or needs network inside a bwrap-sandboxed step** → `elevated`
+   - Spawns Claude subagents with unrestricted tools → `autonomous`
+4. **Does this step need network?** If so, either give it `permissionLevel: elevated` or declare the `net` capability explicitly. See the Troubleshooting section — bwrap strips network from any bash step that has neither, and the failure surfaces as a DNS error, not a permission error.
+5. **Does the command chain multiple statements (`;`, `&&`, `||`)?** Lead the command with `set -e`. A trailing tolerated-failure cleanup like `git stash pop ... || true` will otherwise return 0 for the whole step even when the real work (checkout, pull, push) failed.
+6. **Does this step produce state that later steps rely on?** If this step silently no-ops, will the downstream symptom be understandable? If not, tighten the failure mode (`set -e`, explicit error, `failOnError: true`).
+
+When reviewing a spell PR, scan every bash step for a missing `permissionLevel` and ask: *does this step touch the network, or does it depend on network state from earlier?* If yes, `elevated` (or an explicit `net` grant) is required.
+
+## Troubleshooting
+
+### Symptom: bash step fails with DNS / SSH resolution errors inside a spell
+
+Typical error messages from inside a bash step:
+
+- `ssh: Could not resolve hostname github.com: Temporary failure in name resolution`
+- `fatal: Could not read from remote repository.`
+- `curl: (6) Could not resolve host ...`
+- `getaddrinfo ENOTFOUND ...`
+- Any other DNS/connection failure, even though the **same command works in your normal shell**.
+
+**Tell-tale clue:** the error mentions `Temporary failure in name resolution` (a glibc-specific wording). That means the step is running inside a Linux sandbox (`bwrap` on Linux / WSL), **not** your outer shell — Git Bash or PowerShell won't produce that exact message.
+
+**Root cause:** `src/modules/spells/src/core/bwrap-sandbox.ts` isolates the network by default:
+
+```ts
+if (!hasNet && !needsToolHomeAccess(options.permissionLevel)) {
+  args.push('--unshare-net');   // ← no network, no DNS
+}
+```
+
+A bash step gets network access only when **one** of these is true:
+
+1. The step declares a `net` capability, **or**
+2. The step's `permissionLevel` is `elevated` or `autonomous`.
+
+If neither applies, bwrap runs the command in a namespace with `--unshare-net`, and DNS silently fails. There is no log line announcing the network was taken away — you just see the command's own DNS error.
+
+**Fix:** for any bash step that does `git pull`/`git push`/`git fetch`, `gh` API calls, `curl`, `npm install`, or any other outbound network:
+
+```yaml
+- id: create-branch
+  type: bash
+  permissionLevel: elevated       # ← grants network in bwrap
+  config:
+    command: "git pull origin main && ..."
+```
+
+Or declare the `net` capability explicitly if the step doesn't need the full `elevated` profile (note: `bash-command.ts` must include `net` in its declared capabilities for the engine to accept the grant — otherwise you'll see `Capability violation: step type "bash" does not declare capability "net"`).
+
+**Quick diagnosis checklist** when a spell's bash step can't reach the network:
+
+1. Does the same command work in your outer shell? If yes, it's sandbox-related, not config.
+2. Is the error wording glibc-style (`Temporary failure in name resolution`)? → bwrap is involved.
+3. Open the spell YAML — does the failing step have `permissionLevel: elevated`? If not, add it and retry.
+4. If you use `set -e` in a multi-command bash step, **do it**. Without it, a trailing `... || true` (common for stash-pop cleanups) will mask the real network failure and you'll see a confusing error several steps later (e.g. "pathspec did not match" when a branch that was never pulled/created is later checked out).
+
 ## See Also
 
 - `.claude/guidance/shipped/moflo-spell-engine.md` — Spell engine usage and YAML format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.69",
+  "version": "4.8.71",
   "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.68",
+    "moflo": "^4.8.70",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

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

@@ -1332,37 +1332,67 @@ export const doctorCommand = {
                 return { name: 'Spell Engine', status: 'warn', message: 'Unable to check spell engine' };
             }
         }
-        // Check sandbox tier — reports which OS-level sandbox is available (#412)
+        // Check sandbox tier — reports OS sandbox capability AND, if the project
+        // has `sandbox.enabled: true`, whether the effective sandbox would
+        // actually start (e.g. Windows Docker image pulled and configured).
         async function checkSandboxTier() {
             try {
-                // Walk up to CLI package root, then resolve sibling spells package
-                // (works from both src/ and dist/src/ locations)
                 const __doctorDir = dirname(fileURLToPath(import.meta.url));
                 let cliPkgRoot = __doctorDir;
                 while (cliPkgRoot !== dirname(cliPkgRoot) && !existsSync(join(cliPkgRoot, 'package.json'))) {
                     cliPkgRoot = dirname(cliPkgRoot);
                 }
                 const sandboxPath = resolve(cliPkgRoot, '..', 'spells', 'dist', 'core', 'platform-sandbox.js');
-                const { detectSandboxCapability } = await import(pathToFileURL(sandboxPath).href);
+                const sandboxModule = await import(pathToFileURL(sandboxPath).href);
+                const { detectSandboxCapability, loadSandboxConfigFromProject, resolveEffectiveSandbox, } = sandboxModule;
                 const cap = detectSandboxCapability();
-                if (cap.available) {
+                const config = await loadSandboxConfigFromProject(process.cwd());
+                // If sandboxing isn't enabled in moflo.yaml, just report capability.
+                if (!config.enabled) {
+                    if (cap.available) {
+                        return {
+                            name: 'Sandbox Tier',
+                            status: 'pass',
+                            message: `${cap.tool} available (${cap.platform}) — sandboxing off in moflo.yaml`,
+                        };
+                    }
+                    const offHint = {
+                        win32: 'Install Docker Desktop and set sandbox.dockerImage in moflo.yaml to enable sandboxing',
+                        linux: 'Install bubblewrap: sudo apt install bubblewrap',
+                        darwin: 'sandbox-exec should be available on macOS — check /usr/bin/sandbox-exec',
+                    };
                     return {
                         name: 'Sandbox Tier',
                         status: 'pass',
-                        message: `${cap.tool} (${cap.platform})`,
+                        message: `sandboxing off (${cap.platform}, denylist active)`,
+                        fix: offHint[cap.platform],
+                    };
+                }
+                // Sandboxing is enabled — run the real resolver and surface any error.
+                try {
+                    const effective = resolveEffectiveSandbox(config);
+                    if (effective.useOsSandbox) {
+                        const imageHint = effective.config.dockerImage ? `, ${effective.config.dockerImage}` : '';
+                        return {
+                            name: 'Sandbox Tier',
+                            status: 'pass',
+                            message: `${cap.tool} ready (${cap.platform}${imageHint})`,
+                        };
+                    }
+                    return {
+                        name: 'Sandbox Tier',
+                        status: 'warn',
+                        message: `denylist only (${cap.platform})`,
+                    };
+                }
+                catch (err) {
+                    return {
+                        name: 'Sandbox Tier',
+                        status: 'warn',
+                        message: `sandboxing enabled but not ready (${cap.platform})`,
+                        fix: err instanceof Error ? err.message : String(err),
                     };
                 }
-                const platformHint = {
-                    win32: 'Windows has no OS-level sandbox — denylist and capability gateway still active',
-                    linux: 'Install bubblewrap: sudo apt install bubblewrap',
-                    darwin: 'sandbox-exec should be available on macOS — check /usr/bin/sandbox-exec',
-                };
-                return {
-                    name: 'Sandbox Tier',
-                    status: 'warn',
-                    message: `denylist only (${cap.platform})`,
-                    fix: platformHint[cap.platform] ?? 'No OS sandbox available for this platform',
-                };
             }
             catch (err) {
                 return {

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

@@ -58,6 +58,8 @@ steps:
       # on dirty tree, missing auth, or unreachable remote.
       - id: checkout-base
         type: bash
+        # elevated — bwrap network access for git pull (see single-branch create-branch).
+        permissionLevel: elevated
         preflight:
           - name: "no unmerged files"
             command: "git diff --name-only --diff-filter=U"
@@ -123,6 +125,8 @@ steps:
       # 5: Pull merged changes
       - id: pull-merged
         type: bash
+        # elevated — bwrap network access for git pull (see checkout-base).
+        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"

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

@@ -55,6 +55,11 @@ steps:
   # Preflights run BEFORE any step — fail fast on dirty tree or auth issues
   - id: create-branch
     type: bash
+    # elevated — needed for bwrap to share the host network so `git pull`
+    # can reach github. Without it, bwrap adds --unshare-net and the pull
+    # fails with a DNS / SSH resolution error even though the outer shell
+    # has working network.
+    permissionLevel: elevated
     preflight:
       - name: "no unmerged files"
         command: "git diff --name-only --diff-filter=U"
@@ -134,6 +139,8 @@ steps:
   # Preflight: verify origin remote exists so push won't fail mid-way
   - id: push-branch
     type: bash
+    # elevated — bwrap network access for git push (see create-branch).
+    permissionLevel: elevated
     preflight:
       - name: "origin remote configured"
         command: "git remote get-url origin"

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

package/src/modules/cli/package.json

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

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

@@ -10,6 +10,7 @@ import { resolvePermissions } from '../core/permission-resolver.js';
 import { checkDestructivePatterns, checkDestructivePatternsScoped, formatDestructiveError, validateDestructiveScope, formatScopeViolation, } from './destructive-pattern-checker.js';
 import { wrapWithSandboxExec } from '../core/sandbox-profile.js';
 import { wrapWithBwrap } from '../core/bwrap-sandbox.js';
+import { wrapWithDocker } from '../core/docker-sandbox.js';
 export const bashCommand = {
     type: 'bash',
     description: 'Run a shell command and capture output',
@@ -155,6 +156,19 @@ export const bashCommand = {
                         permissionLevel: context.permissionLevel,
                     });
                 }
+                else if (tool === 'docker') {
+                    const image = context.sandbox.config.dockerImage;
+                    if (!image) {
+                        // Defence-in-depth — resolveEffectiveSandbox should have thrown
+                        // already when the image is missing. If we somehow get here,
+                        // fall through to unsandboxed rather than crashing the step.
+                        throw new Error('Docker sandboxing enabled but no dockerImage configured');
+                    }
+                    sandboxWrap = wrapWithDocker(command, caps, projectRoot, {
+                        image,
+                        permissionLevel: context.permissionLevel,
+                    });
+                }
             }
             catch (err) {
                 console.log(`[bash] ${tool} wrapping failed, running unsandboxed: ${err.message}`);

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

@@ -0,0 +1,195 @@
+/**
+ * Windows Docker Sandbox Wrapper
+ *
+ * Wraps a bash command with `docker run` for execution inside a Linux
+ * container. Mirrors the bwrap/sandbox-exec interface so `bash-command.ts`
+ * can dispatch to any platform's sandbox identically.
+ *
+ * Design notes vs bwrap:
+ *   - Paths must be translated: Windows `C:\path` won't exist in the
+ *     container. projectRoot mounts at `/workspace` (the container's CWD);
+ *     scopes inside projectRoot translate to `/workspace/<rel>`; absolute
+ *     scopes outside the project are skipped with a log line.
+ *   - Tool home paths mount under `/root/<rel>` so that claude/gh/git inside
+ *     the container read and write the same config files the user edits on
+ *     Windows.
+ *   - `--network none` is the default; `net` cap or elevated/autonomous omit
+ *     it (default bridge) — mirrors the bwrap policy.
+ *   - `--rm` handles cleanup automatically.
+ *
+ * @see https://github.com/eric-cielo/moflo/issues/412
+ */
+import { homedir } from 'node:os';
+import { posix, isAbsolute, relative } from 'node:path';
+/** Container path where projectRoot is mounted. */
+const CONTAINER_WORKSPACE = '/workspace';
+/** Container path where the user's home is projected (for tool home mounts). */
+const CONTAINER_HOME = '/root';
+/**
+ * Tool home paths mounted rw for elevated/autonomous steps so claude, gh,
+ * git, npm can persist their config/credentials/cache. Mirrors the bwrap
+ * allowlist; Windows-specific Application Support paths aren't included
+ * because the Linux tools inside the container look at POSIX paths.
+ */
+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',
+];
+function needsToolHomeAccess(level) {
+    return level === 'elevated' || level === 'autonomous';
+}
+/**
+ * Normalise a host path into the form Docker Desktop accepts on `-v` mounts.
+ * Docker for Windows accepts either native Windows paths or the `/c/...`
+ * form — we pass the native path through untouched since `execFile`-style
+ * spawning avoids shell-quoting issues.
+ */
+function normaliseHostPath(p) {
+    return p;
+}
+/**
+ * Translate a host scope path into a container path.
+ *
+ * - If inside `projectRoot` → mount at `/workspace/<relative>` (no extra bind)
+ * - If outside → return null (caller will add a dedicated bind at the same
+ *   POSIX-form path and log that the path is being projected)
+ */
+function translateScopePath(scopePath, projectRoot) {
+    if (!isAbsolute(scopePath)) {
+        const cleaned = scopePath.replace(/^\.\/+/, '');
+        return {
+            containerPath: posix.join(CONTAINER_WORKSPACE, cleaned),
+            needsBind: false,
+        };
+    }
+    const rel = relative(projectRoot, scopePath);
+    const isInside = !rel.startsWith('..') && !isAbsolute(rel);
+    if (isInside) {
+        return {
+            containerPath: posix.join(CONTAINER_WORKSPACE, rel.replace(/\\/g, '/')),
+            needsBind: false,
+        };
+    }
+    // Outside project — give it a dedicated mount at a synthetic container path.
+    // We use a hash-free, deterministic name based on the leaf so repeated
+    // scopes produce stable paths.
+    return {
+        containerPath: `/mnt/sandbox/${toSafeSegment(scopePath)}`,
+        needsBind: true,
+    };
+}
+function toSafeSegment(hostPath) {
+    return hostPath
+        .replace(/[\\:]+/g, '_')
+        .replace(/\//g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+/**
+ * Build `docker run` arguments from step capabilities.
+ *
+ * Default posture: project mounted read-only at `/workspace`, no network,
+ * no tool home access. Capabilities grant additional permissions:
+ *   - fs:read scoped   → `-v <host>:<container>:ro` for each outside-project
+ *                        path; inside-project paths are already covered by
+ *                        the workspace bind
+ *   - fs:read unscoped → no-op (workspace is already read-only)
+ *   - fs:write scoped  → promotes scoped paths to rw
+ *   - fs:write unscoped → promotes `/workspace` to rw
+ *   - net              → omit `--network none`
+ *
+ * When `permissionLevel` is `elevated` or `autonomous`:
+ *   - Mount tool home paths rw at `/root/<rel>`
+ *   - Share the host network (omit `--network none`)
+ */
+export function buildDockerArgs(command, capabilities, projectRoot, options) {
+    const args = ['run', '--rm', '-i'];
+    // ── Workspace mount (read-only by default) ──────────────────────────
+    const fsWrite = capabilities.find(c => c.type === 'fs:write');
+    const projectRw = Boolean(fsWrite && (!fsWrite.scope || fsWrite.scope.length === 0));
+    args.push('-v', `${normaliseHostPath(projectRoot)}:${CONTAINER_WORKSPACE}${projectRw ? '' : ':ro'}`);
+    args.push('-w', CONTAINER_WORKSPACE);
+    // Track container paths we've already bound so we don't double-mount.
+    const mountedContainerPaths = new Set([CONTAINER_WORKSPACE]);
+    // ── fs:write scoped — rw binds for each path ────────────────────────
+    // Inside-project scopes use overlay binds: Docker Desktop honours a second
+    // `-v` whose container target is a subpath of the first, and the second
+    // mount's mode wins for its subtree. That gives us per-scope rw without
+    // opening the whole workspace — the same posture bwrap provides via
+    // `--ro-bind /` + `--bind <scope>`.
+    if (fsWrite && fsWrite.scope && fsWrite.scope.length > 0) {
+        for (const scopePath of fsWrite.scope) {
+            const resolved = isAbsolute(scopePath) ? scopePath : posix.join(projectRoot, scopePath.replace(/^\.\/+/, ''));
+            const { containerPath } = translateScopePath(resolved, projectRoot);
+            if (mountedContainerPaths.has(containerPath))
+                continue;
+            args.push('-v', `${normaliseHostPath(resolved)}:${containerPath}`);
+            mountedContainerPaths.add(containerPath);
+        }
+    }
+    // ── fs:read scoped — ro binds for outside-project paths ─────────────
+    const fsRead = capabilities.find(c => c.type === 'fs:read');
+    if (fsRead && fsRead.scope && fsRead.scope.length > 0) {
+        for (const scopePath of fsRead.scope) {
+            const resolved = isAbsolute(scopePath) ? scopePath : posix.join(projectRoot, scopePath.replace(/^\.\/+/, ''));
+            const { containerPath, needsBind } = translateScopePath(resolved, projectRoot);
+            if (!needsBind)
+                continue;
+            if (mountedContainerPaths.has(containerPath))
+                continue;
+            args.push('-v', `${normaliseHostPath(resolved)}:${containerPath}:ro`);
+            mountedContainerPaths.add(containerPath);
+        }
+    }
+    // ── Tool home paths (elevated/autonomous only) ──────────────────────
+    if (needsToolHomeAccess(options.permissionLevel)) {
+        const home = options.homeDir ?? homedir();
+        if (home) {
+            for (const rel of TOOL_HOME_PATHS) {
+                const hostPath = posix.join(home.replace(/\\/g, '/'), rel);
+                const containerPath = posix.join(CONTAINER_HOME, rel);
+                if (mountedContainerPaths.has(containerPath))
+                    continue;
+                args.push('-v', `${normaliseHostPath(hostPath)}:${containerPath}`);
+                mountedContainerPaths.add(containerPath);
+            }
+        }
+    }
+    // ── Network isolation ───────────────────────────────────────────────
+    const hasNet = capabilities.some(c => c.type === 'net');
+    if (!hasNet && !needsToolHomeAccess(options.permissionLevel)) {
+        args.push('--network', 'none');
+    }
+    // ── Image + command ─────────────────────────────────────────────────
+    args.push(options.image);
+    args.push('bash', '-c', command);
+    return args;
+}
+/**
+ * Wrap a bash command for execution inside a Docker container.
+ *
+ * Returns a `SandboxWrapResult` identical in shape to the bwrap/sandbox-exec
+ * wrappers. `--rm` handles container cleanup, so `cleanup()` is a no-op.
+ */
+export function wrapWithDocker(command, capabilities, projectRoot, options) {
+    const args = buildDockerArgs(command, capabilities, projectRoot, options);
+    return {
+        bin: options.dockerBin ?? 'docker',
+        args,
+        cleanup: () => { },
+    };
+}
+//# sourceMappingURL=docker-sandbox.js.map

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

@@ -19,6 +19,8 @@ export const DEFAULT_SANDBOX_CONFIG = {
     enabled: false,
     tier: 'auto',
 };
+/** Recommended image for first-time Windows Docker sandbox setup. */
+export const RECOMMENDED_DOCKER_IMAGE = 'node:20-bookworm-slim';
 // ============================================================================
 // Detection (cached)
 // ============================================================================
@@ -122,9 +124,14 @@ export function resolveSandboxConfig(raw) {
         return DEFAULT_SANDBOX_CONFIG;
     const enabled = raw.enabled;
     const tier = raw.tier;
+    const dockerImageRaw = raw.dockerImage ?? raw.docker_image;
+    const dockerImage = typeof dockerImageRaw === 'string' && dockerImageRaw.trim().length > 0
+        ? dockerImageRaw.trim()
+        : undefined;
     return {
         enabled: typeof enabled === 'boolean' ? enabled : DEFAULT_SANDBOX_CONFIG.enabled,
         tier: isValidTier(tier) ? tier : DEFAULT_SANDBOX_CONFIG.tier,
+        ...(dockerImage ? { dockerImage } : {}),
     };
 }
 function isValidTier(value) {
@@ -167,10 +174,25 @@ export function resolveEffectiveSandbox(config, capability = detectSandboxCapabi
             displayStatus: `OS sandbox: disabled (denylist active)`,
         };
     }
-    // tier: full — require OS sandbox
+    // Windows: give beginner-friendly setup instructions when sandboxing is
+    // enabled but Docker isn't ready. Runs before the generic "not available"
+    // branch so Windows users see actionable guidance instead of a terse
+    // "not available (win32)" message.
+    if (capability.platform === 'win32') {
+        if (!capability.available) {
+            throw new Error(formatWindowsDockerNotReadyMessage());
+        }
+        if (!config.dockerImage) {
+            throw new Error(formatWindowsDockerImageMissingMessage());
+        }
+        if (!dockerImageExists(config.dockerImage)) {
+            throw new Error(formatWindowsDockerImageNotPulledMessage(config.dockerImage));
+        }
+    }
+    // tier: full — require OS sandbox on non-Windows platforms
     if (config.tier === 'full' && !capability.available) {
         throw new Error(`Sandbox tier "full" requires an OS sandbox but none was detected on ${capability.platform}. ` +
-            `Install bubblewrap (Linux), or Docker Desktop (Windows), or set sandbox.tier to "auto".`);
+            `Install bubblewrap (Linux) or set sandbox.tier to "auto".`);
     }
     if (!capability.available) {
         return {
@@ -187,6 +209,83 @@ export function resolveEffectiveSandbox(config, capability = detectSandboxCapabi
         displayStatus: `OS sandbox: ${capability.tool} (${capability.platform})`,
     };
 }
+/**
+ * Check whether a Docker image is available locally (already pulled).
+ * Returns false on any error (daemon down, image missing, docker not in PATH).
+ */
+function dockerImageExists(image) {
+    try {
+        execSync(`docker image inspect ${shellQuote(image)}`, { stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Minimal shell quoting for image names — keeps the execSync call safe. */
+function shellQuote(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+// ── Beginner-friendly setup messages (Windows) ──────────────────────────
+function formatWindowsDockerNotReadyMessage() {
+    return [
+        'Sandboxing is enabled, but Docker Desktop is not ready on this machine.',
+        '',
+        'Windows sandboxing runs your spell steps inside a Docker container so',
+        'they cannot touch the rest of your system. This is a one-time setup:',
+        '',
+        '  1. Install Docker Desktop (free):',
+        '       https://www.docker.com/products/docker-desktop/',
+        '',
+        '  2. After installing, start Docker Desktop from the Start menu.',
+        '     Wait for the whale icon in your system tray to stop animating —',
+        '     that means Docker is ready.',
+        '',
+        '  3. Open PowerShell (or any terminal) and pull the recommended image:',
+        `       docker pull ${RECOMMENDED_DOCKER_IMAGE}`,
+        '',
+        '  4. Add this to your moflo.yaml:',
+        '       sandbox:',
+        '         enabled: true',
+        `         dockerImage: ${RECOMMENDED_DOCKER_IMAGE}`,
+        '',
+        'Not ready to set this up? You can turn sandboxing off instead by setting',
+        '`sandbox.enabled: false` in moflo.yaml.',
+    ].join('\n');
+}
+function formatWindowsDockerImageMissingMessage() {
+    return [
+        'Sandboxing is enabled, but no Docker image is configured.',
+        '',
+        'Docker is ready on this machine — it just needs to know which image to',
+        'run your spell steps inside. This is a one-time setup:',
+        '',
+        '  1. Open PowerShell (or any terminal) and pull the recommended image:',
+        `       docker pull ${RECOMMENDED_DOCKER_IMAGE}`,
+        '',
+        '  2. Add this to your moflo.yaml:',
+        '       sandbox:',
+        '         enabled: true',
+        `         dockerImage: ${RECOMMENDED_DOCKER_IMAGE}`,
+        '',
+        `The recommended image (${RECOMMENDED_DOCKER_IMAGE}) includes node, npm,`,
+        'bash, git, and curl. Any image with bash will work.',
+    ].join('\n');
+}
+function formatWindowsDockerImageNotPulledMessage(image) {
+    return [
+        `Sandboxing is enabled, but the Docker image "${image}" is not available`,
+        'on this machine yet.',
+        '',
+        'To fix this, open PowerShell (or any terminal) and run:',
+        `       docker pull ${image}`,
+        '',
+        'This only needs to happen once — Docker caches the image afterwards.',
+        '',
+        'If Docker Desktop is not running, start it from the Start menu first',
+        'and wait for the whale icon in your system tray to stop animating.',
+    ].join('\n');
+}
 /**
  * Format a one-line log message for spell startup.
  */

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

@@ -135,8 +135,12 @@ export function generateSandboxProfile(capabilities, projectRoot, options = {})
         }
     }
     // ── net ──────────────────────────────────────────────────────────────
+    // Elevated/autonomous steps spawn CLI tools (claude, gh, git, npm) that
+    // need network to reach their APIs. Mirror the tool-home-paths policy
+    // and bwrap's host-network share so those tools can reach
+    // api.anthropic.com, api.github.com, etc. without DNS/TLS failures.
     const hasNet = capabilities.some(c => c.type === 'net');
-    if (hasNet) {
+    if (hasNet || needsToolHomeAccess(options.permissionLevel)) {
         lines.push('');
         lines.push('; Network access');
         lines.push('(allow network*)');