@boxes-dev/dvb 0.2.4 → 0.2.5

package/dist/devbox/commands/init/index.js

@@ -2,24 +2,25 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 import fs from "node:fs/promises";
 import os from "node:os";
-import readline from "node:readline/promises";
+import { cancel as clackCancel, confirm as clackConfirm, isCancel, log as clackLog, note as clackNote, select as clackSelect, selectKey as clackSelectKey, taskLog as clackTaskLog, } from "@clack/prompts";
 import { resolveSocketInfo } from "@boxes-dev/core";
 import { createSecretStore, loadConfig, createSpritesClient, fingerprintFromOrigin, fingerprintFromRootCommit, normalizeGitRemoteUrl, resolveSpritesApiUrl, SpritesApiError, slugify, } from "@boxes-dev/core";
 import { DAEMON_TIMEOUT_MS, ensureDaemonRunning, requestJson, requireDaemonFeatures, } from "../../daemonClient.js";
 import { ensureSpritesToken } from "../../auth.js";
 import { fetchSpriteDaemonRelease, getConvexUrl, issueSpriteDaemonToken, } from "../../controlPlane.js";
 import { logger } from "../../logger.js";
-import { createStatusLine } from "../../ui/statusLine.js";
 import { parseInitArgs } from "./args.js";
 import { confirmCopyWorktree, findRepoRoot, mapGlobalGitConfigDestinations, readGlobalGitConfigFiles, readHeadState, readNullSeparatedPaths, readRepoOrigin, readRootCommit, readWorktreeState, resolveGitCommonDir, runCommand, } from "./repo.js";
 import { createFileListArchive, createGitMetaArchive, writePatch } from "./packaging.js";
-import { bootstrapDevbox, ensureSpriteDaemonService, expandHome, ensureWeztermMuxService, installSpriteDaemon, installWeztermMux, shellQuote, writeRemoteCodexConfig, } from "./remote.js";
+import { bootstrapDevbox, ensureSpriteDaemonService, expandHome, ensureWeztermMuxService, installSpriteDaemon, shellQuote, stageRemoteSetupArtifacts, writeRemoteCodexConfig, } from "./remote.js";
+import { ensureWeztermMuxInstalled } from "../../../wezterm/ensureMux.js";
 import { ensureDevboxToml, readRepoMarker, writeRepoMarker } from "./registry.js";
-import { readInitState, writeInitState } from "./state.js";
+import { INIT_STEP_KEYS, readInitState, writeInitState } from "./state.js";
 import { ensureSshConfig, ensureSshKey, copyToClipboard, openBrowser, parseGitRemote, readRemoteOrigin, setRemoteOrigin, verifySshAuth, } from "./ssh.js";
 import { ensureKnownHostsFile, ensureLocalMountKey, ensureRemoteMountAccess, ensureSshdService, readLocalMountPublicKey, } from "../mountSsh.js";
-import { createSetupArtifacts, promptForPlanApproval, promptForServicesApproval, readSetupPlan, readServicesPlan, runLocalServicesScan, runLocalSetupScan, runRemoteCodexSetup, uploadSetupPlan, writeSetupPlan, writeSetupSchema, writeServicesPlan, writeServicesSchema, } from "./codex/index.js";
+import { createSetupArtifacts, promptForPlanApproval, promptForServicesApproval, readSetupPlan, readSetupEnvSecretsPlan, readSetupExternalPlan, readSetupExtraArtifactsPlan, readServicesPlan, runLocalServicesScan, runLocalSetupEnvSecretsScan, runLocalSetupExternalScan, runLocalSetupExtraArtifactsScan, runRemoteCodexSetup, uploadSetupPlan, mergeSetupScans, writeSetupPlan, writeSetupEnvSecretsSchema, writeSetupExternalSchema, writeSetupExtraArtifactsSchema, writeServicesPlan, writeServicesSchema, } from "./codex/index.js";
 import { mergeServicesToml, splitShellCommand, } from "../servicesToml.js";
+import { runInitStep } from "./progress.js";
 const resolveInitStatus = (steps, complete) => {
     if (complete || steps?.codexApplied)
         return "complete";
@@ -54,6 +55,32 @@ const buildServicesTomlUpdates = (services) => {
     }
     return updates;
 };
+const extractCheckpointId = (events) => {
+    const idPattern = /\bv\d+\b/;
+    const matchId = (value) => {
+        if (typeof value !== "string")
+            return null;
+        const match = value.match(idPattern);
+        return match?.[0] ?? null;
+    };
+    for (const event of events) {
+        const direct = event.id ??
+            event.checkpoint_id ??
+            event.checkpointId ??
+            event.checkpointID ??
+            event.checkpoint;
+        if (typeof direct === "string" && /^v\d+$/.test(direct)) {
+            return direct;
+        }
+        const candidates = [event.data, event.message, event.raw, event.error];
+        for (const candidate of candidates) {
+            const extracted = matchId(candidate);
+            if (extracted)
+                return extracted;
+        }
+    }
+    return null;
+};
 const writeRemoteServicesToml = async ({ client, canonical, workdir, services, }) => {
     if (services.length === 0)
         return;
@@ -76,34 +103,67 @@ const writeRemoteServicesToml = async ({ client, canonical, workdir, services, }
     const merged = mergeServicesToml(baseContent, updates);
     await client.writeFile(canonical, path.posix.join(workdir.replace(/\/$/, ""), "devbox.toml"), Buffer.from(merged));
 };
-const promptYesNo = async (question, defaultYes = false) => {
-    if (!process.stdin.isTTY) {
-        return defaultYes;
-    }
-    const suffix = defaultYes ? " (Y/n): " : " (y/N): ";
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
+const enableRemoteServices = async ({ client, canonical, services, status, }) => {
+    if (services.length === 0)
+        return;
+    logger.info("init_services_enable_start", {
+        box: canonical,
+        serviceCount: services.length,
     });
-    const answer = await rl.question(`${question}${suffix}`);
-    rl.close();
-    const normalized = answer.trim().toLowerCase();
-    if (!normalized)
-        return defaultYes;
-    return normalized === "y" || normalized === "yes";
+    for (const service of services) {
+        const name = service.name.trim();
+        if (!name) {
+            throw new Error("Service name is required in services.json.");
+        }
+        status?.stage(`Enabling service: ${name}`);
+        const parts = splitShellCommand(service.command ?? "");
+        const [cmd, ...args] = parts;
+        if (!cmd) {
+            throw new Error(`Service "${name}" is missing a command.`);
+        }
+        const input = {
+            cmd,
+            ...(args.length > 0 ? { args } : {}),
+            ...(service.httpPort !== null ? { httpPort: service.httpPort } : {}),
+        };
+        await client.createService(canonical, name, input);
+    }
+    logger.info("init_services_enable_complete", { box: canonical });
+};
+const throwInitCanceled = () => {
+    clackCancel("Init canceled.");
+    throw new Error("Init canceled.");
 };
-const promptToContinue = async (message) => {
-    if (!process.stdin.isTTY) {
+const promptBeforeOpenBrowser = async ({ url, title, consequence, }) => {
+    if (!process.stdin.isTTY)
         return false;
-    }
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
+    clackNote(url, title);
+    const choice = await clackSelectKey({
+        message: `Open ${title} in your browser?`,
+        options: [
+            { value: "o", label: "Open in browser" },
+            { value: "s", label: "Skip" },
+        ],
+        initialValue: "o",
     });
-    await rl.question(message);
-    rl.close();
+    if (isCancel(choice)) {
+        throwInitCanceled();
+    }
+    if (choice === "s") {
+        clackLog.warn(consequence);
+        return false;
+    }
     return true;
 };
+const toPosixPath = (value) => value.split(path.sep).join(path.posix.sep);
+const toRepoRelativePath = (repoRoot, filePath) => {
+    const resolved = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(repoRoot, filePath);
+    const relative = path.relative(repoRoot, resolved) || filePath;
+    return toPosixPath(relative);
+};
+const isOutsideRepoPath = (relativePath) => relativePath === ".." || relativePath.startsWith(`..${path.posix.sep}`);
 const ensureWorkdirOwnership = async ({ client, canonical, workdir, status, json, }) => {
     const checkResult = await client.exec(canonical, [
         "/bin/bash",
@@ -133,26 +193,273 @@ const ensureWorkdirOwnership = async ({ client, canonical, workdir, status, json
         }
     }
 };
+const ensureGitSafeDirectory = async ({ client, canonical, workdir, status, }) => {
+    status.stage("Configuring git safe.directory");
+    logger.info("init_git_safe_directory_configure_start", {
+        box: canonical,
+        workdir,
+    });
+    const script = [
+        "set -euo pipefail",
+        `repo=${shellQuote(workdir)}`,
+        'if [ ! -d "$repo" ]; then',
+        '  echo "Missing repo workdir: $repo" >&2',
+        "  exit 1",
+        "fi",
+        'if [ ! -d "$repo/.git" ]; then',
+        "  exit 0",
+        "fi",
+        "if ! command -v git >/dev/null 2>&1; then",
+        "  exit 0",
+        "fi",
+        "",
+        'ensure_safe_in_file() {',
+        '  cfg="$1"',
+        '  existing="$(git config --file "$cfg" --get-all safe.directory 2>/dev/null || true)"',
+        '  if printf \'%s\\n\' "$existing" | grep -Fxq "$repo"; then',
+        "    return 0",
+        "  fi",
+        '  git config --file "$cfg" --add safe.directory "$repo"',
+        "}",
+        "",
+        // Ensure the repo is trusted for the sprite user (most devbox flows).
+        'ensure_safe_in_file "/home/sprite/.gitconfig"',
+        // If we created/modified the file as root, best-effort fix the owner.
+        'if [ "$(id -u)" -eq 0 ]; then',
+        "  chown sprite:sprite /home/sprite/.gitconfig >/dev/null 2>&1 || true",
+        "elif command -v sudo >/dev/null 2>&1; then",
+        "  sudo -n chown sprite:sprite /home/sprite/.gitconfig >/dev/null 2>&1 || true",
+        "fi",
+        "",
+        // Best-effort: also trust the repo for root, in case tools run git as root.
+        'if [ "$(id -u)" -eq 0 ]; then',
+        '  ensure_safe_in_file "/root/.gitconfig"',
+        "elif command -v sudo >/dev/null 2>&1; then",
+        '  root_existing="$(sudo -n git config --file /root/.gitconfig --get-all safe.directory 2>/dev/null || true)"',
+        '  if ! printf \'%s\\n\' "$root_existing" | grep -Fxq "$repo"; then',
+        '    sudo -n git config --file /root/.gitconfig --add safe.directory "$repo" >/dev/null 2>&1 || true',
+        "  fi",
+        "fi",
+    ].join("\n");
+    const result = await client.exec(canonical, [
+        "/bin/bash",
+        "--noprofile",
+        "--norc",
+        "-e",
+        "-u",
+        "-o",
+        "pipefail",
+        "-c",
+        script,
+    ]);
+    if (result.exitCode !== 0) {
+        const details = result.stderr || result.stdout || "";
+        throw new Error(details
+            ? `Failed to configure git safe.directory: ${details.trim()}`
+            : `Failed to configure git safe.directory (exit ${result.exitCode})`);
+    }
+    logger.info("init_git_safe_directory_configure_complete", {
+        box: canonical,
+        workdir,
+    });
+};
 export const runInit = async (args) => {
     const parsed = parseInitArgs(args);
-    const statusEnabled = process.stderr.isTTY && !parsed.json;
-    const status = createStatusLine({ enabled: statusEnabled });
+    const progressEnabled = process.stdout.isTTY && !parsed.json;
     const run = async () => {
-        status.stage("Detecting repository");
-        const cwd = process.cwd();
-        const repoRoot = await findRepoRoot(cwd);
-        const repoName = path.basename(repoRoot);
-        const slug = slugify(repoName);
-        const localHomeDir = process.env.HOME ?? os.homedir();
-        const repoMarker = await readRepoMarker(repoRoot);
-        const origin = await readRepoOrigin(repoRoot);
-        const normalizedOrigin = origin ? normalizeGitRemoteUrl(origin) : null;
-        const fingerprint = origin
-            ? fingerprintFromOrigin(origin)
-            : repoMarker?.fingerprint ??
-                fingerprintFromRootCommit(await readRootCommit(repoRoot), randomUUID());
-        let initState = await readInitState(repoRoot);
-        const initFingerprintMismatch = Boolean(initState?.fingerprint) && initState?.fingerprint !== fingerprint;
+        const detected = await runInitStep({
+            enabled: progressEnabled,
+            title: "Detecting repository",
+            fn: async () => {
+                const cwd = process.cwd();
+                const repoRoot = await findRepoRoot(cwd);
+                const repoName = path.basename(repoRoot);
+                const slug = slugify(repoName);
+                const localHomeDir = process.env.HOME ?? os.homedir();
+                // Recoverability contract:
+                // - Every init step must be idempotent and/or checkpointed in init-state.json.
+                // - `complete` must only be true when the setup is actually usable without
+                //   additional `dvb init --resume` work.
+                // See: apps/cli/docs/INIT_RECOVERABILITY.md
+                const repoMarker = await readRepoMarker(repoRoot);
+                const origin = await readRepoOrigin(repoRoot);
+                const normalizedOrigin = origin ? normalizeGitRemoteUrl(origin) : null;
+                const fingerprint = origin
+                    ? fingerprintFromOrigin(origin)
+                    : repoMarker?.fingerprint ??
+                        fingerprintFromRootCommit(await readRootCommit(repoRoot), randomUUID());
+                let initState = await readInitState(repoRoot);
+                const initFingerprintMismatch = Boolean(initState?.fingerprint) &&
+                    initState?.fingerprint !== fingerprint;
+                if (!initFingerprintMismatch &&
+                    initState?.complete &&
+                    !initState.steps.codexApplied) {
+                    // Older versions could mark init "complete" even though Codex setup had not
+                    // been applied yet. Treat this as incomplete so `dvb init --resume` can
+                    // recover.
+                    initState = { ...initState, complete: false };
+                    await writeInitState(repoRoot, initState);
+                }
+                return {
+                    repoRoot,
+                    repoName,
+                    slug,
+                    localHomeDir,
+                    repoMarker,
+                    origin,
+                    normalizedOrigin,
+                    fingerprint,
+                    initState,
+                    initFingerprintMismatch,
+                };
+            },
+        });
+        const { repoRoot, repoName, slug, localHomeDir, repoMarker, origin, normalizedOrigin, fingerprint, } = detected;
+        let initState = detected.initState;
+        const initFingerprintMismatch = detected.initFingerprintMismatch;
+        if (parsed.status) {
+            if (parsed.resume ||
+                parsed.force ||
+                parsed.codexSetupOnly ||
+                parsed.alias ||
+                parsed.name) {
+                throw new Error("`dvb init --status` cannot be combined with other init flags (except --json).");
+            }
+            const socketInfo = resolveSocketInfo();
+            let daemonError = null;
+            let registryProject = null;
+            try {
+                await ensureDaemonRunning(socketInfo.socketPath);
+                await requireDaemonFeatures(socketInfo.socketPath, ["registry"]);
+                const existingProject = await requestJson(socketInfo.socketPath, "GET", `/registry/project?fingerprint=${encodeURIComponent(fingerprint)}`, DAEMON_TIMEOUT_MS.registry);
+                registryProject = existingProject.body.project ?? null;
+            }
+            catch (error) {
+                daemonError = error instanceof Error ? error.message : String(error);
+            }
+            const localStatus = initState && !initFingerprintMismatch
+                ? resolveInitStatus(initState.steps, initState.complete)
+                : null;
+            const recommendsResume = Boolean(initState && !initFingerprintMismatch && !initState.complete);
+            const recommendsInit = !registryProject && (!initState || initFingerprintMismatch);
+            const recommendsForce = !recommendsResume &&
+                (!initState || initFingerprintMismatch) &&
+                Boolean(registryProject?.initStatus && registryProject.initStatus !== "complete");
+            const lines = [];
+            lines.push("INIT STATUS");
+            lines.push("");
+            lines.push("Repo");
+            lines.push(`  root: ${repoRoot}`);
+            lines.push(`  origin: ${normalizedOrigin ?? origin ?? "(none)"}`);
+            lines.push(`  fingerprint: ${fingerprint}`);
+            lines.push("");
+            lines.push("Local state");
+            if (repoMarker?.canonical) {
+                lines.push(`  box marker (.devbox/box.json): present (alias: ${repoMarker.alias ?? "(none)"}, box: ${repoMarker.canonical})`);
+            }
+            else {
+                lines.push("  box marker (.devbox/box.json): missing");
+            }
+            if (initState) {
+                const completeText = initFingerprintMismatch
+                    ? `${String(Boolean(initState.complete))} (fingerprint mismatch)`
+                    : String(Boolean(initState.complete));
+                lines.push(`  init checkpoint (.devbox/init-state.json): present (updated: ${initState.updatedAt}, complete: ${completeText})`);
+                if (initState.canonical || initState.alias || initState.workdir) {
+                    lines.push(`    box: ${initState.canonical ?? "(unknown)"} (alias: ${initState.alias ?? "(unknown)"})`);
+                    lines.push(`    workdir: ${initState.workdir ?? "(unknown)"}`);
+                }
+                if (initState.checkpoints?.preCodexSetup || initState.checkpoints?.postCodexSetup) {
+                    const pre = initState.checkpoints?.preCodexSetup;
+                    const post = initState.checkpoints?.postCodexSetup;
+                    lines.push("    snapshots:");
+                    if (pre) {
+                        lines.push(`      pre-codex-setup: ${pre.id} (created: ${pre.createdAt})`);
+                    }
+                    if (post) {
+                        lines.push(`      post-codex-setup: ${post.id} (created: ${post.createdAt})`);
+                    }
+                }
+                if (localStatus) {
+                    lines.push(`  inferred init status: ${localStatus}`);
+                }
+                lines.push("  steps:");
+                const steps = initState.steps ?? {};
+                for (const key of INIT_STEP_KEYS) {
+                    lines.push(`    ${key}: ${steps[key] ? "yes" : "no"}`);
+                }
+            }
+            else {
+                lines.push("  init checkpoint (.devbox/init-state.json): missing");
+            }
+            lines.push("");
+            lines.push("Registry");
+            lines.push(`  daemon socket: ${socketInfo.socketPath}`);
+            if (daemonError) {
+                lines.push(`  daemon: unavailable (${daemonError})`);
+            }
+            else if (registryProject) {
+                lines.push("  project: present");
+                lines.push(`    box: ${registryProject.canonical}`);
+                lines.push(`    alias: ${registryProject.alias ?? "(none)"}`);
+                lines.push(`    initStatus: ${registryProject.initStatus ?? "(none)"}`);
+                lines.push(`    initUpdatedAt: ${registryProject.initUpdatedAt ?? "(none)"}`);
+                if (registryProject.localPaths && registryProject.localPaths.length > 0) {
+                    lines.push(`    localPaths: ${registryProject.localPaths.length} path(s)`);
+                }
+            }
+            else {
+                lines.push("  project: not found");
+            }
+            lines.push("");
+            lines.push("Recommended");
+            if (recommendsResume) {
+                lines.push("  dvb init --resume");
+            }
+            else if (recommendsInit) {
+                lines.push("  dvb init");
+            }
+            else if (recommendsForce) {
+                lines.push("  Resume is not available from this clone (no init checkpoint).");
+                lines.push("  If init was started elsewhere, re-run `dvb init --resume` from that repo.");
+                lines.push("  Otherwise, restart init with `dvb init --force` (re-provisions the remote workdir).");
+            }
+            else {
+                lines.push("  (none)");
+            }
+            lines.push("");
+            if (parsed.json) {
+                console.log(JSON.stringify({
+                    ok: true,
+                    repo: {
+                        root: repoRoot,
+                        origin: normalizedOrigin ?? origin ?? null,
+                        fingerprint,
+                    },
+                    local: {
+                        marker: repoMarker ?? null,
+                        initState: initState ?? null,
+                        initFingerprintMismatch,
+                        inferredStatus: localStatus,
+                    },
+                    registry: {
+                        socketPath: socketInfo.socketPath,
+                        error: daemonError,
+                        project: registryProject,
+                    },
+                    recommended: recommendsResume
+                        ? "dvb init --resume"
+                        : recommendsInit
+                            ? "dvb init"
+                            : recommendsForce
+                                ? "dvb init --force"
+                                : null,
+                }, null, 2));
+                return;
+            }
+            console.log(lines.join("\n"));
+            return;
+        }
         if (parsed.resume) {
             if (initFingerprintMismatch) {
                 throw new Error("Init state does not match this repo. Remove .devbox/init-state.json and run `dvb init` again.");
@@ -203,6 +510,63 @@ export const runInit = async (args) => {
             };
             await writeInitState(repoRoot, initState);
         };
+        const recordCodexCheckpoint = async ({ client, canonical, phase, }) => {
+            const createdAt = new Date().toISOString();
+            const label = phase === "preCodexSetup" ? "pre-codex-setup" : "post-codex-setup";
+            const comment = `dvb init: ${label} repo=${repoName} fingerprint=${fingerprint} at=${createdAt}`;
+            const events = await client.createCheckpoint(canonical, { comment });
+            const id = extractCheckpointId(events);
+            if (!id) {
+                logger.warn("init_checkpoint_id_missing", {
+                    box: canonical,
+                    fingerprint,
+                    phase: label,
+                });
+                return { id: null, comment, createdAt };
+            }
+            const record = { id, comment, createdAt };
+            if (initState) {
+                await updateInitState({
+                    checkpoints: { ...(initState.checkpoints ?? {}), [phase]: record },
+                });
+            }
+            const metaPath = `/home/sprite/.devbox/projects/${fingerprint}.json`;
+            try {
+                let meta = {};
+                try {
+                    const raw = await client.readFile(canonical, { path: metaPath });
+                    const parsed = JSON.parse(Buffer.from(raw).toString("utf8"));
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        meta = parsed;
+                    }
+                }
+                catch (error) {
+                    if (!(error instanceof SpritesApiError && error.status === 404)) {
+                        throw error;
+                    }
+                }
+                const existingCheckpoints = meta.checkpoints && typeof meta.checkpoints === "object" && !Array.isArray(meta.checkpoints)
+                    ? meta.checkpoints
+                    : {};
+                const updated = {
+                    ...meta,
+                    checkpoints: {
+                        ...existingCheckpoints,
+                        [phase]: record,
+                    },
+                };
+                await client.writeFile(canonical, metaPath, Buffer.from(JSON.stringify(updated, null, 2)));
+            }
+            catch (error) {
+                logger.warn("init_checkpoint_meta_update_failed", {
+                    box: canonical,
+                    fingerprint,
+                    phase: label,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return { id, comment, createdAt };
+        };
         if (parsed.codexSetupOnly) {
             if (!repoMarker?.canonical) {
                 throw new Error("Repo is not initialized. Run `dvb init` first.");
@@ -229,21 +593,32 @@ export const runInit = async (args) => {
             catch {
                 // artifacts are optional in setup-only flow
             }
-            status.stage("Starting dvbd");
             const socketInfo = resolveSocketInfo();
-            await ensureDaemonRunning(socketInfo.socketPath);
-            await requireDaemonFeatures(socketInfo.socketPath, ["ports"]);
-            status.stage("Loading devbox config");
-            const config = await loadConfig(process.env.HOME ? { homeDir: process.env.HOME } : undefined);
-            const store = await createSecretStore(config?.tokenStore, process.env.HOME ? { homeDir: process.env.HOME } : undefined);
-            const token = await store.getToken();
-            if (!token) {
-                throw new Error("Sprites token missing. Run `dvb setup` first.");
-            }
-            const apiBaseUrl = resolveSpritesApiUrl(config);
-            const client = createSpritesClient({
-                apiBaseUrl,
-                token,
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Starting dvbd",
+                fn: async () => {
+                    await ensureDaemonRunning(socketInfo.socketPath);
+                    await requireDaemonFeatures(socketInfo.socketPath, ["ports"]);
+                },
+            });
+            const { config, client } = await runInitStep({
+                enabled: progressEnabled,
+                title: "Loading devbox config",
+                fn: async () => {
+                    const config = await loadConfig(process.env.HOME ? { homeDir: process.env.HOME } : undefined);
+                    const store = await createSecretStore(config?.tokenStore, process.env.HOME ? { homeDir: process.env.HOME } : undefined);
+                    const token = await store.getToken();
+                    if (!token) {
+                        throw new Error("Sprites token missing. Run `dvb setup` first.");
+                    }
+                    const apiBaseUrl = resolveSpritesApiUrl(config);
+                    const client = createSpritesClient({
+                        apiBaseUrl,
+                        token,
+                    });
+                    return { config, client };
+                },
             });
             const canonical = repoMarker.canonical;
             let expandedWorkdir = expandHome(`~/${slug}`);
@@ -270,34 +645,139 @@ export const runInit = async (args) => {
             catch {
                 servicesPlan = null;
             }
-            await uploadSetupPlan({
-                client,
-                canonical,
-                localSetupPath: setupPath,
-                remoteSetupPath,
-                localArtifactsBundlePath: artifactsBundlePath,
-                localArtifactsManifestPath: artifactsManifestPath,
-                remoteArtifactsBundlePath: artifactsBundlePath
-                    ? remoteArtifactsBundlePath
-                    : null,
-                remoteArtifactsManifestPath: artifactsBundlePath
-                    ? remoteArtifactsManifestPath
-                    : null,
-                status,
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Configuring git safe.directory",
+                fn: async ({ status }) => {
+                    await ensureGitSafeDirectory({
+                        client,
+                        canonical,
+                        workdir: expandedWorkdir,
+                        status,
+                    });
+                },
+            });
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Uploading setup plan",
+                fn: async ({ status }) => {
+                    await uploadSetupPlan({
+                        client,
+                        canonical,
+                        localSetupPath: setupPath,
+                        remoteSetupPath,
+                        localArtifactsBundlePath: artifactsBundlePath,
+                        localArtifactsManifestPath: artifactsManifestPath,
+                        remoteArtifactsBundlePath: artifactsBundlePath
+                            ? remoteArtifactsBundlePath
+                            : null,
+                        remoteArtifactsManifestPath: artifactsBundlePath
+                            ? remoteArtifactsManifestPath
+                            : null,
+                        status,
+                    });
+                },
             });
-            await runRemoteCodexSetup({
-                client,
-                canonical,
-                expandedWorkdir,
-                remoteSetupPath,
-                remoteArtifactsBundlePath,
-                remoteArtifactsManifestPath,
-                socketInfo,
-                status,
-                pathSetup,
-                entrypoints: servicesPlan?.appEntrypoints ?? [],
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Staging setup artifacts",
+                fn: async ({ status }) => {
+                    status.stage("Copying repo artifacts and staging external files");
+                    await stageRemoteSetupArtifacts({
+                        client,
+                        canonical,
+                        workdir: expandedWorkdir,
+                        artifactsBundlePath: remoteArtifactsBundlePath,
+                        artifactsManifestPath: remoteArtifactsManifestPath,
+                    });
+                },
+            });
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Snapshotting filesystem (pre-setup) (optional)",
+                fn: async ({ fail, ok }) => {
+                    try {
+                        const checkpoint = await recordCodexCheckpoint({
+                            client,
+                            canonical,
+                            phase: "preCodexSetup",
+                        });
+                        if (checkpoint.id) {
+                            ok(`Snapshot created: ${checkpoint.id}`);
+                        }
+                    }
+                    catch (error) {
+                        logger.warn("init_checkpoint_create_failed", {
+                            box: canonical,
+                            fingerprint,
+                            phase: "pre-codex-setup",
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        fail("Snapshotting filesystem (pre-setup) (optional) (failed)");
+                        if (!parsed.json) {
+                            console.warn("Warning: failed to create pre-setup filesystem snapshot. Continuing without it.");
+                        }
+                    }
+                },
+            });
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Enabling devbox services",
+                fn: async ({ status }) => {
+                    await enableRemoteServices({
+                        client,
+                        canonical,
+                        services: servicesPlan?.backgroundServices ?? [],
+                        status,
+                    });
+                },
+            });
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Applying setup plan",
+                fn: async ({ status }) => {
+                    await runRemoteCodexSetup({
+                        client,
+                        canonical,
+                        expandedWorkdir,
+                        remoteSetupPath,
+                        remoteArtifactsBundlePath,
+                        remoteArtifactsManifestPath,
+                        socketInfo,
+                        status,
+                        pathSetup,
+                        entrypoints: servicesPlan?.appEntrypoints ?? [],
+                    });
+                },
+            });
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Snapshotting filesystem (post-setup) (optional)",
+                fn: async ({ fail, ok }) => {
+                    try {
+                        const checkpoint = await recordCodexCheckpoint({
+                            client,
+                            canonical,
+                            phase: "postCodexSetup",
+                        });
+                        if (checkpoint.id) {
+                            ok(`Snapshot created: ${checkpoint.id}`);
+                        }
+                    }
+                    catch (error) {
+                        logger.warn("init_checkpoint_create_failed", {
+                            box: canonical,
+                            fingerprint,
+                            phase: "post-codex-setup",
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        fail("Snapshotting filesystem (post-setup) (optional) (failed)");
+                        if (!parsed.json) {
+                            console.warn("Warning: failed to create post-setup filesystem snapshot. Continuing without it.");
+                        }
+                    }
+                },
             });
-            status.stop();
             if (parsed.json) {
                 console.log(JSON.stringify({ ok: true }, null, 2));
                 return;
@@ -305,13 +785,23 @@ export const runInit = async (args) => {
             console.log("Codex setup complete.");
             return;
         }
-        status.stage("Starting dvbd");
         const socketInfo = resolveSocketInfo();
-        await ensureDaemonRunning(socketInfo.socketPath);
-        await requireDaemonFeatures(socketInfo.socketPath, ["registry"]);
-        status.stage("Checking sprites");
-        const existingProject = await requestJson(socketInfo.socketPath, "GET", `/registry/project?fingerprint=${encodeURIComponent(fingerprint)}`, DAEMON_TIMEOUT_MS.registry);
-        const existingEntry = existingProject.body.project ?? null;
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Starting dvbd",
+            fn: async () => {
+                await ensureDaemonRunning(socketInfo.socketPath);
+                await requireDaemonFeatures(socketInfo.socketPath, ["registry"]);
+            },
+        });
+        const existingEntry = await runInitStep({
+            enabled: progressEnabled,
+            title: "Checking sprites",
+            fn: async () => {
+                const existingProject = await requestJson(socketInfo.socketPath, "GET", `/registry/project?fingerprint=${encodeURIComponent(fingerprint)}`, DAEMON_TIMEOUT_MS.registry);
+                return existingProject.body.project ?? null;
+            },
+        });
         if (existingEntry && !parsed.force) {
             if (shouldResume) {
                 if (initState?.canonical &&
@@ -335,14 +825,20 @@ export const runInit = async (args) => {
         const remoteArtifactsBundlePath = path.posix.join(expandedWorkdir, ".devbox", "setup-artifacts.tgz");
         const remoteArtifactsManifestPath = path.posix.join(expandedWorkdir, ".devbox", "setup-artifacts.json");
         const pathSetup = 'export PATH="$(npm bin -g 2>/dev/null):$PATH"';
-        status.stage("Loading devbox config");
-        const config = await loadConfig(process.env.HOME ? { homeDir: process.env.HOME } : undefined);
-        const store = await createSecretStore(config?.tokenStore, process.env.HOME ? { homeDir: process.env.HOME } : undefined);
-        const { token, controlPlaneToken } = await ensureSpritesToken(store, (message) => status.stage(message));
-        const apiBaseUrl = resolveSpritesApiUrl(config);
-        const client = createSpritesClient({
-            apiBaseUrl,
-            token,
+        const { config, client, controlPlaneToken } = await runInitStep({
+            enabled: progressEnabled,
+            title: "Loading devbox config",
+            fn: async ({ status }) => {
+                const config = await loadConfig(process.env.HOME ? { homeDir: process.env.HOME } : undefined);
+                const store = await createSecretStore(config?.tokenStore, process.env.HOME ? { homeDir: process.env.HOME } : undefined);
+                const { token, controlPlaneToken } = await ensureSpritesToken(store, (message) => status.stage(message));
+                const apiBaseUrl = resolveSpritesApiUrl(config);
+                const client = createSpritesClient({
+                    apiBaseUrl,
+                    token,
+                });
+                return { config, client, controlPlaneToken };
+            },
         });
         const username = os.userInfo().username;
         let canonical = (shouldResume && initState?.canonical ? initState.canonical : null) ??
@@ -368,25 +864,32 @@ export const runInit = async (args) => {
         };
         const skipCreate = shouldResume && initState?.steps.spritesCreated && initState.canonical;
         if (!skipCreate) {
-            status.stage("Creating devbox");
-            const createResult = await createSprite(canonical);
-            if (createResult === "exists" && !parsed.force) {
-                if (canonicalHint) {
-                    throw new Error(`Sprite already exists: ${canonical}`);
-                }
-                const suffix = fingerprint.slice(0, 6);
-                canonical = `${canonical}-${suffix}`;
-                status.stage("Resolving devbox name");
-                const second = await createSprite(canonical);
-                if (second === "exists") {
-                    throw new Error(`Sprite already exists: ${canonical}`);
-                }
-            }
-            await updateInitState({
-                canonical,
-                alias,
-                workdir,
-                steps: { spritesCreated: true },
+            canonical = await runInitStep({
+                enabled: progressEnabled,
+                title: "Creating devbox",
+                fn: async ({ status }) => {
+                    let nextCanonical = canonical;
+                    const createResult = await createSprite(nextCanonical);
+                    if (createResult === "exists" && !parsed.force) {
+                        if (canonicalHint) {
+                            throw new Error(`Sprite already exists: ${nextCanonical}`);
+                        }
+                        const suffix = fingerprint.slice(0, 6);
+                        nextCanonical = `${nextCanonical}-${suffix}`;
+                        status.stage("Resolving devbox name");
+                        const second = await createSprite(nextCanonical);
+                        if (second === "exists") {
+                            throw new Error(`Sprite already exists: ${nextCanonical}`);
+                        }
+                    }
+                    await updateInitState({
+                        canonical: nextCanonical,
+                        alias,
+                        workdir,
+                        steps: { spritesCreated: true },
+                    });
+                    return nextCanonical;
+                },
             });
         }
         const aliasLookup = await requestJson(socketInfo.socketPath, "GET", `/registry/alias?alias=${encodeURIComponent(alias)}`, DAEMON_TIMEOUT_MS.registry);
@@ -422,109 +925,134 @@ export const runInit = async (args) => {
                 });
             }
         };
-        status.stage("Bootstrapping devbox");
-        try {
-            await bootstrapDevbox(client, canonical);
-        }
-        catch (error) {
-            logger.warn("devbox_bootstrap_failed", {
-                box: canonical,
-                error: String(error),
-            });
-            if (!parsed.json) {
-                status.stop();
-                const message = error instanceof Error && error.message
-                    ? error.message
-                    : String(error);
-                console.warn(`Warning: devbox bootstrap failed. ${message}`);
-            }
-        }
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Bootstrapping devbox",
+            fn: async ({ fail }) => {
+                try {
+                    await bootstrapDevbox(client, canonical);
+                }
+                catch (error) {
+                    logger.warn("devbox_bootstrap_failed", {
+                        box: canonical,
+                        error: String(error),
+                    });
+                    fail("Bootstrapping devbox (failed)");
+                    if (!parsed.json) {
+                        const message = error instanceof Error && error.message
+                            ? error.message
+                            : String(error);
+                        console.warn(`Warning: devbox bootstrap failed. ${message}`);
+                    }
+                }
+            },
+        });
         const initialStatus = resolveInitStatus(initState?.steps, initState?.complete);
         if (!shouldResume || !initState?.steps.registrySynced) {
-            status.stage("Syncing sprites");
-            await requestJson(socketInfo.socketPath, "POST", "/registry/upsert", DAEMON_TIMEOUT_MS.registry, {
-                project: buildProjectEntry(initialStatus),
-                box: {
-                    canonical,
-                    org: config?.org,
-                    createdAt: new Date().toISOString(),
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Syncing sprites",
+                fn: async () => {
+                    await requestJson(socketInfo.socketPath, "POST", "/registry/upsert", DAEMON_TIMEOUT_MS.registry, {
+                        project: buildProjectEntry(initialStatus),
+                        box: {
+                            canonical,
+                            org: config?.org,
+                            createdAt: new Date().toISOString(),
+                        },
+                        alias: { alias, canonical },
+                    });
+                    await updateInitState({
+                        canonical,
+                        alias,
+                        workdir,
+                        steps: { registrySynced: true },
+                    });
                 },
-                alias: { alias, canonical },
-            });
-            await updateInitState({
-                canonical,
-                alias,
-                workdir,
-                steps: { registrySynced: true },
             });
         }
         if (!shouldResume || !initState?.steps.daemonInstalled) {
-            status.stage("Installing sprite daemon");
-            try {
-                const convexUrl = getConvexUrl();
-                if (!controlPlaneToken) {
-                    throw new Error("Control plane session required to install daemon.");
-                }
-                if (!convexUrl) {
-                    throw new Error("Convex URL unavailable.");
-                }
-                const release = await fetchSpriteDaemonRelease(controlPlaneToken);
-                if (!release) {
-                    throw new Error("No sprite daemon release available.");
-                }
-                const heartbeatToken = await issueSpriteDaemonToken(controlPlaneToken, canonical);
-                if (!heartbeatToken) {
-                    throw new Error("Daemon token unavailable.");
-                }
-                await installSpriteDaemon({
-                    client,
-                    spriteName: canonical,
-                    release,
-                    convexUrl,
-                    heartbeatToken,
-                });
-                await updateInitState({ steps: { daemonInstalled: true } });
-            }
-            catch (error) {
-                logger.warn("sprite_daemon_install_failed", {
-                    box: canonical,
-                    error: String(error),
-                });
-                if (!parsed.json) {
-                    status.stop();
-                    const message = error instanceof Error && error.message
-                        ? error.message
-                        : String(error);
-                    console.warn(`Warning: failed to install sprite daemon. ${message}`);
-                }
-            }
-        }
-        status.stage("Ensuring sprite daemon service");
-        try {
-            await ensureSpriteDaemonService({ client, spriteName: canonical });
-            await updateInitState({ steps: { daemonServiceEnsured: true } });
-        }
-        catch (error) {
-            logger.warn("sprite_daemon_service_failed", {
-                box: canonical,
-                error: String(error),
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Installing sprite daemon",
+                fn: async ({ fail }) => {
+                    try {
+                        const convexUrl = getConvexUrl();
+                        if (!controlPlaneToken) {
+                            throw new Error("Control plane session required to install daemon.");
+                        }
+                        if (!convexUrl) {
+                            throw new Error("Convex URL unavailable.");
+                        }
+                        const release = await fetchSpriteDaemonRelease(controlPlaneToken);
+                        if (!release) {
+                            throw new Error("No sprite daemon release available.");
+                        }
+                        const heartbeatToken = await issueSpriteDaemonToken(controlPlaneToken, canonical);
+                        if (!heartbeatToken) {
+                            throw new Error("Daemon token unavailable.");
+                        }
+                        await installSpriteDaemon({
+                            client,
+                            spriteName: canonical,
+                            release,
+                            convexUrl,
+                            heartbeatToken,
+                        });
+                        await updateInitState({ steps: { daemonInstalled: true } });
+                    }
+                    catch (error) {
+                        logger.warn("sprite_daemon_install_failed", {
+                            box: canonical,
+                            error: String(error),
+                        });
+                        fail("Installing sprite daemon (failed)");
+                        if (!parsed.json) {
+                            const message = error instanceof Error && error.message
+                                ? error.message
+                                : String(error);
+                            console.warn(`Warning: failed to install sprite daemon. ${message}`);
+                        }
+                    }
+                },
             });
-            if (!parsed.json) {
-                status.stop();
-                const message = error instanceof Error && error.message
-                    ? error.message
-                    : String(error);
-                console.warn(`Warning: failed to ensure sprite daemon service. ${message}`);
-            }
         }
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Ensuring sprite daemon service",
+            fn: async ({ fail }) => {
+                try {
+                    await ensureSpriteDaemonService({ client, spriteName: canonical });
+                    await updateInitState({ steps: { daemonServiceEnsured: true } });
+                }
+                catch (error) {
+                    logger.warn("sprite_daemon_service_failed", {
+                        box: canonical,
+                        error: String(error),
+                    });
+                    fail("Ensuring sprite daemon service (failed)");
+                    if (!parsed.json) {
+                        const message = error instanceof Error && error.message
+                            ? error.message
+                            : String(error);
+                        console.warn(`Warning: failed to ensure sprite daemon service. ${message}`);
+                    }
+                }
+            },
+        });
         const setupDir = path.join(repoRoot, ".devbox");
         const setupPath = path.join(setupDir, "setup.json");
         const servicesPath = path.join(setupDir, "services.json");
+        const scansDir = path.join(setupDir, "scans");
+        const setupEnvSecretsScanPath = path.join(scansDir, "setup-env-secrets.json");
+        const setupExternalScanPath = path.join(scansDir, "setup-external.json");
+        const setupExtraArtifactsScanPath = path.join(scansDir, "setup-extra-artifacts.json");
         let setupArtifacts = null;
         const nonInteractive = !process.stdin.isTTY || parsed.json;
         const skipSetupPlan = shouldResume && initState?.steps.setupPlanWritten;
         const skipServicesPlan = shouldResume && initState?.steps.servicesPlanWritten;
         const skipServicesConfig = shouldResume && initState?.steps.servicesConfigWritten;
+        const skipServicesEnable = shouldResume && initState?.steps.servicesEnabled;
         const skipSetupUpload = nonInteractive || (shouldResume && initState?.steps.setupUploaded);
         const skipCodexApply = nonInteractive || (shouldResume && initState?.steps.codexApplied);
         let approvedPlan = null;
@@ -532,334 +1060,567 @@ export const runInit = async (args) => {
         const setupTempDir = await fs.mkdtemp(path.join(os.tmpdir(), "devbox-setup-"));
         try {
             await fs.mkdir(setupDir, { recursive: true });
-            if (!skipSetupPlan || !skipServicesPlan) {
-                let setupSchemaPath = null;
-                let servicesSchemaPath = null;
-                if (!skipSetupPlan) {
-                    setupSchemaPath = await writeSetupSchema(setupTempDir);
+            const tryReadSetupPlan = async () => {
+                try {
+                    return await readSetupPlan(setupPath);
                 }
-                if (!skipServicesPlan) {
-                    servicesSchemaPath = await writeServicesSchema(setupTempDir);
+                catch {
+                    return null;
                 }
-                if (!skipSetupPlan && !setupSchemaPath) {
-                    throw new Error("Setup schema path missing.");
+            };
+            const tryReadServicesPlan = async () => {
+                try {
+                    return await readServicesPlan(servicesPath);
                 }
-                if (!skipServicesPlan && !servicesSchemaPath) {
-                    throw new Error("Services schema path missing.");
+                catch {
+                    return null;
                 }
-                status.stage("Analyzing local environment");
-                await Promise.all([
-                    skipSetupPlan
-                        ? Promise.resolve()
-                        : runLocalSetupScan({
-                            cwd: repoRoot,
-                            schemaPath: setupSchemaPath,
-                            outputPath: setupPath,
-                            homeDir: localHomeDir,
-                            onProgress: (message) => {
-                                const base = "Analyzing local environment — setup";
-                                status.stage(`${base} — ${message}`);
-                            },
-                        }),
-                    skipServicesPlan
-                        ? Promise.resolve()
-                        : runLocalServicesScan({
-                            cwd: repoRoot,
-                            schemaPath: servicesSchemaPath,
-                            outputPath: servicesPath,
-                            homeDir: localHomeDir,
-                            onProgress: (message) => {
-                                const base = "Analyzing local environment — services";
-                                status.stage(`${base} — ${message}`);
-                            },
-                        }),
-                ]);
-            }
-            if (!skipSetupPlan) {
-                const setupPlan = await readSetupPlan(setupPath);
-                if (nonInteractive) {
-                    approvedPlan = setupPlan;
+            };
+            const tryReadEnvSecretsScan = async () => {
+                try {
+                    return await readSetupEnvSecretsPlan(setupEnvSecretsScanPath);
                 }
-                else {
-                    if (!process.stdin.isTTY || parsed.json) {
-                        throw new Error("Interactive terminal required to approve setup.");
-                    }
-                    status.stage("Reviewing setup findings");
-                    status.stop();
-                    approvedPlan = await promptForPlanApproval(setupPlan);
+                catch {
+                    return null;
                 }
-                await writeSetupPlan(setupPath, approvedPlan);
-                await updateInitState({ steps: { setupPlanWritten: true } });
-            }
-            else {
-                approvedPlan = await readSetupPlan(setupPath);
-            }
-            if (!skipServicesPlan) {
-                const servicesPlan = await readServicesPlan(servicesPath);
-                if (nonInteractive) {
-                    approvedServices = servicesPlan;
+            };
+            const tryReadExternalScan = async () => {
+                try {
+                    return await readSetupExternalPlan(setupExternalScanPath);
                 }
-                else {
-                    if (!process.stdin.isTTY || parsed.json) {
-                        throw new Error("Interactive terminal required to approve services.");
-                    }
-                    status.stage("Reviewing run services findings");
-                    status.stop();
-                    approvedServices = await promptForServicesApproval(servicesPlan);
+                catch {
+                    return null;
                 }
-                await writeServicesPlan(servicesPath, approvedServices);
-                await updateInitState({ steps: { servicesPlanWritten: true } });
+            };
+            const tryReadExtraArtifactsScan = async () => {
+                try {
+                    return await readSetupExtraArtifactsPlan(setupExtraArtifactsScanPath);
+                }
+                catch {
+                    return null;
+                }
+            };
+            const shouldRetryCodexScan = (scanFullyCompleted, ...arrays) => !scanFullyCompleted && arrays.every((array) => array.length === 0);
+            let setupPlan = skipSetupPlan || !shouldResume ? null : await tryReadSetupPlan();
+            let servicesPlan = skipServicesPlan || !shouldResume ? null : await tryReadServicesPlan();
+            const needsSetupScan = !skipSetupPlan && !setupPlan;
+            let envSecretsScan = !needsSetupScan || !shouldResume ? null : await tryReadEnvSecretsScan();
+            let externalScan = !needsSetupScan || !shouldResume ? null : await tryReadExternalScan();
+            let extraArtifactsScan = !needsSetupScan || !shouldResume
+                ? null
+                : await tryReadExtraArtifactsScan();
+            if (servicesPlan &&
+                shouldRetryCodexScan(servicesPlan.scanFullyCompleted, servicesPlan.appEntrypoints, servicesPlan.backgroundServices)) {
+                servicesPlan = null;
             }
-            else {
-                approvedServices = await readServicesPlan(servicesPath);
+            if (envSecretsScan &&
+                shouldRetryCodexScan(envSecretsScan.scanFullyCompleted, envSecretsScan.envFiles, envSecretsScan.secretFiles)) {
+                envSecretsScan = null;
             }
-            if (!skipSetupUpload) {
-                status.stage("Packaging setup artifacts");
-                setupArtifacts = await createSetupArtifacts({
-                    repoRoot,
-                    plan: approvedPlan,
-                    outputDir: setupDir,
-                    tempDir: setupTempDir,
-                    homeDir: localHomeDir,
-                });
+            if (externalScan &&
+                shouldRetryCodexScan(externalScan.scanFullyCompleted, externalScan.externalDependencies, externalScan.externalConfigs)) {
+                externalScan = null;
             }
-        }
-        finally {
-            await fs.rm(setupTempDir, { recursive: true, force: true });
-        }
-        const skipProvision = shouldResume && initState?.steps.workdirProvisioned;
-        if (!skipProvision || !skipSetupUpload) {
-            if (!skipProvision) {
-                status.stage("Packaging repo");
+            if (extraArtifactsScan &&
+                shouldRetryCodexScan(extraArtifactsScan.scanFullyCompleted, extraArtifactsScan.extraArtifacts)) {
+                extraArtifactsScan = null;
             }
-            const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "devbox-init-"));
-            const bundlePath = path.join(tempDir, "repo.bundle");
-            const archivePath = path.join(tempDir, "repo.tgz");
-            const gitMetaPath = path.join(tempDir, "git-meta.tgz");
-            const gitMetaListPath = path.join(tempDir, "git-meta.list");
-            const stagedPatchPath = path.join(tempDir, "staged.patch");
-            const unstagedPatchPath = path.join(tempDir, "unstaged.patch");
-            const untrackedPath = path.join(tempDir, "untracked.tgz");
-            const untrackedListPath = path.join(tempDir, "untracked.list");
-            const globalGitConfigSources = await readGlobalGitConfigFiles(repoRoot);
-            const globalGitConfigMappings = mapGlobalGitConfigDestinations(globalGitConfigSources, localHomeDir);
-            try {
-                const remoteBundlePath = "/home/sprite/.devbox/upload.bundle";
-                const remoteArchivePath = "/home/sprite/.devbox/upload.tgz";
-                const remoteGitMetaPath = "/home/sprite/.devbox/git-meta.tgz";
-                const remoteStagedPatchPath = "/home/sprite/.devbox/staged.patch";
-                const remoteUnstagedPatchPath = "/home/sprite/.devbox/unstaged.patch";
-                const remoteUntrackedPath = "/home/sprite/.devbox/untracked.tgz";
-                status.stage("Checking remote git");
-                const gitCheck = await client.exec(canonical, [
-                    "/bin/bash",
-                    "-lc",
-                    "git --version",
-                ]);
-                const remoteHasGit = gitCheck.exitCode === 0;
-                const remoteDirs = new Set();
-                remoteDirs.add(path.posix.dirname(remoteBundlePath));
-                remoteDirs.add(path.posix.dirname(remoteArchivePath));
-                remoteDirs.add(path.posix.dirname(remoteGitMetaPath));
-                remoteDirs.add(path.posix.dirname(remoteStagedPatchPath));
-                remoteDirs.add(path.posix.dirname(remoteUnstagedPatchPath));
-                remoteDirs.add(path.posix.dirname(remoteUntrackedPath));
-                for (const mapping of globalGitConfigMappings) {
-                    remoteDirs.add(path.posix.dirname(mapping.dest));
-                }
-                if (remoteDirs.size > 0) {
-                    status.stage("Preparing remote directories");
-                    const prepResult = await client.exec(canonical, [
-                        "/bin/bash",
-                        "-lc",
-                        `mkdir -p ${[...remoteDirs].map(shellQuote).join(" ")}`,
+            const needsServicesScan = !skipServicesPlan && !servicesPlan;
+            const needsEnvSecretsScan = needsSetupScan && !envSecretsScan;
+            const needsExternalScan = needsSetupScan && !externalScan;
+            const needsExtraArtifactsScan = needsSetupScan && !extraArtifactsScan;
+            if (needsSetupScan || needsServicesScan) {
+                const runLocalEnvironmentAnalysis = async ({ updateEnvSecrets, updateExternal, updateExtraArtifacts, updateServices, }) => {
+                    let envSecretsSchemaPath = null;
+                    let externalSchemaPath = null;
+                    let extraArtifactsSchemaPath = null;
+                    let servicesSchemaPath = null;
+                    if (needsEnvSecretsScan) {
+                        envSecretsSchemaPath =
+                            await writeSetupEnvSecretsSchema(setupTempDir);
+                    }
+                    if (needsExternalScan) {
+                        externalSchemaPath = await writeSetupExternalSchema(setupTempDir);
+                    }
+                    if (needsExtraArtifactsScan) {
+                        extraArtifactsSchemaPath =
+                            await writeSetupExtraArtifactsSchema(setupTempDir);
+                    }
+                    if (needsServicesScan) {
+                        servicesSchemaPath = await writeServicesSchema(setupTempDir);
+                    }
+                    if (needsEnvSecretsScan && !envSecretsSchemaPath) {
+                        throw new Error("Env/secrets schema path missing.");
+                    }
+                    if (needsExternalScan && !externalSchemaPath) {
+                        throw new Error("External schema path missing.");
+                    }
+                    if (needsExtraArtifactsScan && !extraArtifactsSchemaPath) {
+                        throw new Error("Extra artifacts schema path missing.");
+                    }
+                    if (needsServicesScan && !servicesSchemaPath) {
+                        throw new Error("Services schema path missing.");
+                    }
+                    if (needsSetupScan) {
+                        await fs.mkdir(scansDir, { recursive: true });
+                    }
+                    const runCodexScanWithImmediateRetry = async ({ run, read, outputPath, update, shouldRetry, }) => {
+                        try {
+                            await run();
+                            let out = await read();
+                            if (shouldRetry(out)) {
+                                update("retrying");
+                                await fs.rm(outputPath, { force: true });
+                                await run();
+                                out = await read();
+                            }
+                            update("done");
+                            return out;
+                        }
+                        catch (error) {
+                            update("failed");
+                            throw error;
+                        }
+                    };
+                    const envSecretsPromise = !needsSetupScan
+                        ? Promise.resolve(null)
+                        : !needsEnvSecretsScan
+                            ? Promise.resolve(envSecretsScan)
+                            : runCodexScanWithImmediateRetry({
+                                run: async () => await runLocalSetupEnvSecretsScan({
+                                    cwd: repoRoot,
+                                    schemaPath: envSecretsSchemaPath,
+                                    outputPath: setupEnvSecretsScanPath,
+                                    onProgress: updateEnvSecrets,
+                                }),
+                                read: async () => await readSetupEnvSecretsPlan(setupEnvSecretsScanPath),
+                                outputPath: setupEnvSecretsScanPath,
+                                update: updateEnvSecrets,
+                                shouldRetry: (plan) => shouldRetryCodexScan(plan.scanFullyCompleted, plan.envFiles, plan.secretFiles),
+                            });
+                    const externalPromise = !needsSetupScan
+                        ? Promise.resolve(null)
+                        : !needsExternalScan
+                            ? Promise.resolve(externalScan)
+                            : runCodexScanWithImmediateRetry({
+                                run: async () => await runLocalSetupExternalScan({
+                                    cwd: repoRoot,
+                                    schemaPath: externalSchemaPath,
+                                    outputPath: setupExternalScanPath,
+                                    homeDir: localHomeDir,
+                                    onProgress: updateExternal,
+                                }),
+                                read: async () => await readSetupExternalPlan(setupExternalScanPath),
+                                outputPath: setupExternalScanPath,
+                                update: updateExternal,
+                                shouldRetry: (plan) => shouldRetryCodexScan(plan.scanFullyCompleted, plan.externalDependencies, plan.externalConfigs),
+                            });
+                    const extraArtifactsPromise = !needsSetupScan
+                        ? Promise.resolve(null)
+                        : !needsExtraArtifactsScan
+                            ? Promise.resolve(extraArtifactsScan)
+                            : runCodexScanWithImmediateRetry({
+                                run: async () => await runLocalSetupExtraArtifactsScan({
+                                    cwd: repoRoot,
+                                    schemaPath: extraArtifactsSchemaPath,
+                                    outputPath: setupExtraArtifactsScanPath,
+                                    onProgress: updateExtraArtifacts,
+                                }),
+                                read: async () => await readSetupExtraArtifactsPlan(setupExtraArtifactsScanPath),
+                                outputPath: setupExtraArtifactsScanPath,
+                                update: updateExtraArtifacts,
+                                shouldRetry: (plan) => shouldRetryCodexScan(plan.scanFullyCompleted, plan.extraArtifacts),
+                            });
+                    const servicesPromise = !needsServicesScan
+                        ? Promise.resolve(servicesPlan)
+                        : runCodexScanWithImmediateRetry({
+                            run: async () => await runLocalServicesScan({
+                                cwd: repoRoot,
+                                schemaPath: servicesSchemaPath,
+                                outputPath: servicesPath,
+                                homeDir: localHomeDir,
+                                onProgress: updateServices,
+                            }),
+                            read: async () => await readServicesPlan(servicesPath),
+                            outputPath: servicesPath,
+                            update: updateServices,
+                            shouldRetry: (plan) => shouldRetryCodexScan(plan.scanFullyCompleted, plan.appEntrypoints, plan.backgroundServices),
+                        });
+                    const [envSecrets, external, extraArtifacts, services] = await Promise.all([
+                        envSecretsPromise,
+                        externalPromise,
+                        extraArtifactsPromise,
+                        servicesPromise,
                     ]);
-                    if (prepResult.exitCode !== 0) {
-                        throw new Error(prepResult.stderr || "Failed to prepare remote dirs");
+                    if (needsServicesScan) {
+                        if (!services) {
+                            throw new Error("Services plan missing.");
+                        }
+                        servicesPlan = services;
+                    }
+                    if (needsSetupScan) {
+                        if (!envSecrets) {
+                            throw new Error("Env/secrets scan missing.");
+                        }
+                        if (!external) {
+                            throw new Error("External scan missing.");
+                        }
+                        if (!extraArtifacts) {
+                            throw new Error("Extra artifacts scan missing.");
+                        }
+                        updateEnvSecrets("merging setup plan");
+                        const merged = mergeSetupScans({
+                            envSecrets,
+                            external,
+                            extraArtifacts,
+                        });
+                        await writeSetupPlan(setupPath, merged);
+                        setupPlan = merged;
                     }
+                };
+                if (!progressEnabled) {
+                    await runLocalEnvironmentAnalysis({
+                        updateEnvSecrets: () => { },
+                        updateExternal: () => { },
+                        updateExtraArtifacts: () => { },
+                        updateServices: () => { },
+                    });
                 }
-                let headState = null;
-                let gitCommonDir = "";
-                let worktreeState = null;
-                let copyWorktree = false;
-                if (!skipProvision) {
-                    status.stage("Inspecting git state");
-                    headState = await readHeadState(repoRoot);
-                    const resolved = await resolveGitCommonDir(repoRoot);
-                    gitCommonDir = resolved.commonDir;
-                    worktreeState = await readWorktreeState(repoRoot);
-                    const hasWorktreeChanges = worktreeState.staged.length > 0 ||
-                        worktreeState.unstaged.length > 0 ||
-                        worktreeState.untracked.length > 0;
-                    if (hasWorktreeChanges && process.stdin.isTTY && !parsed.json) {
-                        status.stop();
-                        copyWorktree = await confirmCopyWorktree(worktreeState);
-                    }
-                    else if (hasWorktreeChanges) {
-                        copyWorktree = true;
+                else {
+                    const log = clackTaskLog({
+                        title: "Analyzing local environment",
+                        limit: 1,
+                        spacing: 0,
+                    });
+                    let active = true;
+                    const colorCategory = (label) => {
+                        if (!process.stdout.hasColors?.())
+                            return label;
+                        const undim = "\u001b[22m";
+                        const dim = "\u001b[2m";
+                        const bold = "\u001b[1m";
+                        const teal = "\u001b[36m";
+                        const resetColor = "\u001b[39m";
+                        return `${undim}${teal}${bold}${label}${resetColor}${undim}${dim}`;
+                    };
+                    const formatRow = (label, message) => {
+                        const normalized = message.replace(/\r?\n/g, " ").trim();
+                        return `${colorCategory(label)}: ${normalized}`;
+                    };
+                    const envSecretsRow = log.group("");
+                    const externalRow = log.group("");
+                    const extraArtifactsRow = log.group("");
+                    const servicesRow = log.group("");
+                    const makeUpdater = (row, label) => (message) => {
+                        if (!active)
+                            return;
+                        row.message(formatRow(label, message));
+                    };
+                    const updateEnvSecrets = makeUpdater(envSecretsRow, "env/secrets");
+                    const updateExternal = makeUpdater(externalRow, "external");
+                    const updateExtraArtifacts = makeUpdater(extraArtifactsRow, "extra artifacts");
+                    const updateServices = makeUpdater(servicesRow, "services");
+                    updateEnvSecrets(needsSetupScan ? (needsEnvSecretsScan ? "starting" : "cached") : "skipped");
+                    updateExternal(needsSetupScan ? (needsExternalScan ? "starting" : "cached") : "skipped");
+                    updateExtraArtifacts(needsSetupScan
+                        ? needsExtraArtifactsScan
+                            ? "starting"
+                            : "cached"
+                        : "skipped");
+                    updateServices(skipServicesPlan ? "skipped" : needsServicesScan ? "starting" : "cached");
+                    try {
+                        await runLocalEnvironmentAnalysis({
+                            updateEnvSecrets,
+                            updateExternal,
+                            updateExtraArtifacts,
+                            updateServices,
+                        });
+                        active = false;
+                        log.success("Analyzing local environment");
+                    }
+                    catch (error) {
+                        active = false;
+                        log.error("Analyzing local environment");
+                        throw error;
                     }
                 }
-                let gitMetaCreated = false;
-                let stagedPatchCreated = false;
-                let unstagedPatchCreated = false;
-                let untrackedCreated = false;
-                if (remoteHasGit) {
-                    if (!skipProvision) {
-                        status.stage("Packaging repo bundle");
-                        await runCommand(repoRoot, "git", [
-                            "bundle",
-                            "create",
-                            bundlePath,
-                            "--all",
-                        ]);
+            }
+            if (!skipSetupPlan && !setupPlan) {
+                setupPlan = await readSetupPlan(setupPath);
+            }
+            if (!skipServicesPlan && !servicesPlan) {
+                servicesPlan = await readServicesPlan(servicesPath);
+            }
+            if (!skipSetupPlan && !setupPlan) {
+                throw new Error("Setup plan missing.");
+            }
+            if (!skipServicesPlan && !servicesPlan) {
+                throw new Error("Services plan missing.");
+            }
+            const scanStepUpdate = {};
+            if (!skipSetupPlan && setupPlan) {
+                if (!initState?.steps.setupEnvSecretsScanned) {
+                    scanStepUpdate.setupEnvSecretsScanned = true;
+                }
+                if (!initState?.steps.setupExternalScanned) {
+                    scanStepUpdate.setupExternalScanned = true;
+                }
+                if (!initState?.steps.setupExtraArtifactsScanned) {
+                    scanStepUpdate.setupExtraArtifactsScanned = true;
+                }
+                if (!initState?.steps.setupPlanScanned) {
+                    scanStepUpdate.setupPlanScanned = true;
+                }
+            }
+            if (!skipServicesPlan &&
+                servicesPlan &&
+                !initState?.steps.servicesPlanScanned) {
+                scanStepUpdate.servicesPlanScanned = true;
+            }
+            if (Object.keys(scanStepUpdate).length > 0) {
+                await updateInitState({ steps: scanStepUpdate });
+            }
+            if (skipSetupPlan) {
+                approvedPlan = await readSetupPlan(setupPath);
+            }
+            if (skipServicesPlan) {
+                approvedServices = await readServicesPlan(servicesPath);
+            }
+            if (shouldResume && (approvedPlan || approvedServices)) {
+                const backfillStepUpdate = {};
+                if (approvedPlan) {
+                    if (!initState?.steps.setupEnvSecretsScanned) {
+                        backfillStepUpdate.setupEnvSecretsScanned = true;
                     }
-                    if (!skipProvision) {
-                        status.stage("Packaging git metadata");
-                        gitMetaCreated = await createGitMetaArchive(gitCommonDir, gitMetaPath, gitMetaListPath);
+                    if (!initState?.steps.setupExternalScanned) {
+                        backfillStepUpdate.setupExternalScanned = true;
                     }
-                    if (copyWorktree && worktreeState) {
-                        status.stage("Packaging worktree changes");
-                        stagedPatchCreated = await writePatch(repoRoot, ["diff", "--binary", "--cached"], stagedPatchPath);
-                        unstagedPatchCreated = await writePatch(repoRoot, ["diff", "--binary"], unstagedPatchPath);
-                        untrackedCreated = await createFileListArchive(repoRoot, worktreeState.untracked, untrackedPath, untrackedListPath);
+                    if (!initState?.steps.setupExtraArtifactsScanned) {
+                        backfillStepUpdate.setupExtraArtifactsScanned = true;
                     }
-                    if (!skipProvision) {
-                        status.stage("Uploading repo bundle");
-                        const bundleData = await fs.readFile(bundlePath);
-                        await client.writeFile(canonical, remoteBundlePath, bundleData);
+                    if (!initState?.steps.setupPlanScanned) {
+                        backfillStepUpdate.setupPlanScanned = true;
                     }
-                    if (gitMetaCreated) {
-                        status.stage("Uploading git metadata");
-                        const gitMetaData = await fs.readFile(gitMetaPath);
-                        await client.writeFile(canonical, remoteGitMetaPath, gitMetaData);
+                }
+                if (approvedServices && !initState?.steps.servicesPlanScanned) {
+                    backfillStepUpdate.servicesPlanScanned = true;
+                }
+                if (Object.keys(backfillStepUpdate).length > 0) {
+                    await updateInitState({ steps: backfillStepUpdate });
+                }
+            }
+            if (nonInteractive) {
+                if (setupPlan)
+                    approvedPlan = setupPlan;
+                if (servicesPlan)
+                    approvedServices = servicesPlan;
+            }
+            else if (setupPlan || servicesPlan) {
+                if (!process.stdin.isTTY || parsed.json) {
+                    throw new Error("Interactive terminal required to approve setup.");
+                }
+                const statCache = new Map();
+                const readPathInfo = async (candidatePath) => {
+                    const cached = statCache.get(candidatePath);
+                    if (cached)
+                        return cached;
+                    const resolved = path.isAbsolute(candidatePath)
+                        ? candidatePath
+                        : path.resolve(repoRoot, candidatePath);
+                    const relative = toRepoRelativePath(repoRoot, candidatePath);
+                    const outsideRepo = isOutsideRepoPath(relative);
+                    let isDirectory = false;
+                    try {
+                        const stat = await fs.stat(resolved);
+                        isDirectory = stat.isDirectory();
                     }
-                    if (stagedPatchCreated) {
-                        status.stage("Uploading staged changes");
-                        await client.writeFile(canonical, remoteStagedPatchPath, await fs.readFile(stagedPatchPath));
+                    catch {
+                        isDirectory = false;
                     }
-                    if (unstagedPatchCreated) {
-                        status.stage("Uploading unstaged changes");
-                        await client.writeFile(canonical, remoteUnstagedPatchPath, await fs.readFile(unstagedPatchPath));
+                    const info = { relative, outsideRepo, isDirectory };
+                    statCache.set(candidatePath, info);
+                    return info;
+                };
+                const buildApprovalSummary = async ({ setup, services, }) => {
+                    const lines = [];
+                    lines.push("Setup");
+                    lines.push(`- .env files: ${setup.envFiles.length}`);
+                    for (const entry of setup.envFiles) {
+                        lines.push(`  - ${toRepoRelativePath(repoRoot, entry.path)}`);
                     }
-                    if (untrackedCreated) {
-                        status.stage("Uploading untracked files");
-                        await client.writeFile(canonical, remoteUntrackedPath, await fs.readFile(untrackedPath));
+                    lines.push(`- Secret/config files: ${setup.secretFiles.length}`);
+                    for (const entry of setup.secretFiles) {
+                        lines.push(`  - ${toRepoRelativePath(repoRoot, entry.path)}`);
                     }
-                    if (!skipProvision && globalGitConfigMappings.length > 0) {
-                        status.stage("Uploading git config");
-                        for (const mapping of globalGitConfigMappings) {
-                            const data = await fs.readFile(mapping.source);
-                            await client.writeFile(canonical, mapping.dest, data);
+                    lines.push(`- Other artifacts: ${setup.extraArtifacts.length}`);
+                    for (const entry of setup.extraArtifacts) {
+                        lines.push(`  - ${toRepoRelativePath(repoRoot, entry.path)}`);
+                    }
+                    lines.push(`- External dependencies: ${setup.externalDependencies.length}`);
+                    for (const entry of setup.externalDependencies) {
+                        lines.push(`  - ${entry.version ? `${entry.name}@${entry.version}` : entry.name}`);
+                    }
+                    lines.push(`- External config/secret files: ${setup.externalConfigs.length}`);
+                    for (const entry of setup.externalConfigs) {
+                        lines.push(`  - ${toRepoRelativePath(repoRoot, entry.path)}`);
+                    }
+                    lines.push("");
+                    lines.push("Services");
+                    lines.push(`- App entrypoints: ${services.appEntrypoints.length}`);
+                    for (const entry of services.appEntrypoints) {
+                        lines.push(`  - ${entry.command}`);
+                    }
+                    lines.push(`- Background services: ${services.backgroundServices.length}`);
+                    for (const entry of services.backgroundServices) {
+                        lines.push(`  - ${entry.name}`);
+                    }
+                    const candidatePaths = new Set();
+                    for (const entry of [
+                        ...setup.envFiles,
+                        ...setup.secretFiles,
+                        ...setup.extraArtifacts,
+                        ...setup.externalConfigs,
+                    ]) {
+                        candidatePaths.add(entry.path);
+                    }
+                    const outsideRepoPaths = [];
+                    const directoryPaths = [];
+                    for (const candidatePath of candidatePaths) {
+                        const info = await readPathInfo(candidatePath);
+                        if (info.outsideRepo)
+                            outsideRepoPaths.push(info.relative);
+                        if (info.isDirectory)
+                            directoryPaths.push(info.relative);
+                    }
+                    outsideRepoPaths.sort();
+                    directoryPaths.sort();
+                    const hasRisk = outsideRepoPaths.length > 0 || directoryPaths.length > 0;
+                    const warningLines = [];
+                    if (outsideRepoPaths.length > 0) {
+                        warningLines.push("Outside repo:");
+                        for (const entry of outsideRepoPaths) {
+                            warningLines.push(`- ${entry}`);
                         }
+                        warningLines.push("");
                     }
-                    if (!skipProvision) {
-                        const backup = `${expandedWorkdir}.bak-${Date.now()}`;
-                        const checkoutCommand = headState?.branch
-                            ? `git checkout -B ${shellQuote(headState.branch)} ${shellQuote(headState.commit)}`
-                            : `git checkout --detach ${shellQuote(headState?.commit ?? "")}`;
-                        status.stage("Provisioning workdir");
-                        const remoteCommand = [
-                            "set -euo pipefail",
-                            "unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE",
-                            `if [ -d ${shellQuote(expandedWorkdir)} ]; then`,
-                            parsed.force
-                                ? `  mv ${shellQuote(expandedWorkdir)} ${shellQuote(backup)}`
-                                : `  echo "Target exists: ${expandedWorkdir}" >&2; exit 1`,
-                            "fi",
-                            `mkdir -p ${shellQuote(path.dirname(expandedWorkdir))}`,
-                            `git init -b devbox-init ${shellQuote(expandedWorkdir)}`,
-                            `cd ${shellQuote(expandedWorkdir)}`,
-                            `git fetch ${shellQuote(remoteBundlePath)} 'refs/*:refs/*'`,
-                            `if [ -f ${shellQuote(remoteGitMetaPath)} ]; then`,
-                            `  tar -xzf ${shellQuote(remoteGitMetaPath)} -C .git`,
-                            "fi",
-                            checkoutCommand,
-                            `if [ -f ${shellQuote(remoteStagedPatchPath)} ]; then`,
-                            `  git apply --index ${shellQuote(remoteStagedPatchPath)}`,
-                            "fi",
-                            `if [ -f ${shellQuote(remoteUnstagedPatchPath)} ]; then`,
-                            `  git apply ${shellQuote(remoteUnstagedPatchPath)}`,
-                            "fi",
-                            `if [ -f ${shellQuote(remoteUntrackedPath)} ]; then`,
-                            `  tar -xzf ${shellQuote(remoteUntrackedPath)} -C .`,
-                            "fi",
-                        ].join("\n");
-                        const execResult = await client.exec(canonical, [
-                            "/bin/bash",
-                            "--noprofile",
-                            "--norc",
-                            "-e",
-                            "-u",
-                            "-o",
-                            "pipefail",
-                            "-c",
-                            remoteCommand,
-                        ]);
-                        if (execResult.exitCode !== 0) {
-                            throw new Error(execResult.stderr || "Remote init failed");
+                    if (directoryPaths.length > 0) {
+                        warningLines.push("Directories:");
+                        for (const entry of directoryPaths) {
+                            warningLines.push(`- ${entry}`);
                         }
-                        await updateInitState({ steps: { workdirProvisioned: true } });
                     }
-                }
-                else if (!skipProvision) {
-                    status.stage("Packaging repo (archive)");
-                    if (copyWorktree) {
-                        const workingFiles = await readNullSeparatedPaths(repoRoot, [
-                            "ls-files",
-                            "--cached",
-                            "--others",
-                            "--exclude-standard",
-                        ]);
-                        await createFileListArchive(repoRoot, workingFiles, archivePath, untrackedListPath);
+                    return {
+                        summary: lines.join("\n"),
+                        warning: warningLines.length > 0 ? warningLines.join("\n") : null,
+                        hasRisk,
+                    };
+                };
+                let draftSetup = setupPlan;
+                let draftServices = servicesPlan;
+                while (true) {
+                    const nextSetup = skipSetupPlan
+                        ? approvedPlan
+                        : await promptForPlanApproval({
+                            plan: setupPlan,
+                            repoRoot,
+                            initialPlan: draftSetup,
+                        });
+                    const nextServices = skipServicesPlan
+                        ? approvedServices
+                        : await promptForServicesApproval({
+                            plan: servicesPlan,
+                            initialPlan: draftServices,
+                        });
+                    if (!nextSetup) {
+                        throw new Error("Setup plan missing.");
                     }
-                    else {
-                        await runCommand(repoRoot, "git", [
-                            "archive",
-                            "--format=tar.gz",
-                            "-o",
-                            archivePath,
-                            "HEAD",
-                        ]);
+                    if (!nextServices) {
+                        throw new Error("Services plan missing.");
                     }
-                    status.stage("Uploading repo archive");
-                    await client.writeFile(canonical, remoteArchivePath, await fs.readFile(archivePath));
-                    if (globalGitConfigMappings.length > 0) {
-                        status.stage("Uploading git config");
-                        for (const mapping of globalGitConfigMappings) {
-                            const data = await fs.readFile(mapping.source);
-                            await client.writeFile(canonical, mapping.dest, data);
-                        }
+                    const { summary, warning, hasRisk } = await buildApprovalSummary({
+                        setup: nextSetup,
+                        services: nextServices,
+                    });
+                    clackNote(summary, "Selected setup requirements");
+                    if (warning) {
+                        clackNote(warning, "Special attention");
                     }
-                    const backup = `${expandedWorkdir}.bak-${Date.now()}`;
-                    status.stage("Provisioning workdir");
-                    const remoteCommand = [
-                        "set -euo pipefail",
-                        "unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE",
-                        `if [ -d ${shellQuote(expandedWorkdir)} ]; then`,
-                        parsed.force
-                            ? `  mv ${shellQuote(expandedWorkdir)} ${shellQuote(backup)}`
-                            : `  echo "Target exists: ${expandedWorkdir}" >&2; exit 1`,
-                        "fi",
-                        `mkdir -p ${shellQuote(expandedWorkdir)}`,
-                        `tar -xzf ${shellQuote(remoteArchivePath)} -C ${shellQuote(expandedWorkdir)}`,
-                    ].join("\n");
-                    const execResult = await client.exec(canonical, [
-                        "/bin/bash",
-                        "--noprofile",
-                        "--norc",
-                        "-e",
-                        "-u",
-                        "-o",
-                        "pipefail",
-                        "-c",
-                        remoteCommand,
-                    ]);
-                    if (execResult.exitCode !== 0) {
-                        throw new Error(execResult.stderr || "Remote init failed");
+                    const decision = await clackSelect({
+                        message: "Proceed with these selections?",
+                        options: [
+                            { value: "proceed", label: "Proceed" },
+                            { value: "edit", label: "Edit selections" },
+                            { value: "cancel", label: "Cancel" },
+                        ],
+                        initialValue: "proceed",
+                    });
+                    if (isCancel(decision) || decision === "cancel") {
+                        throwInitCanceled();
+                    }
+                    if (decision === "edit") {
+                        draftSetup = nextSetup;
+                        draftServices = nextServices;
+                        continue;
                     }
-                    await updateInitState({ steps: { workdirProvisioned: true } });
+                    if (hasRisk) {
+                        const confirmed = await clackConfirm({
+                            message: "You selected items outside the repo and/or directories. Continue?",
+                            active: "Continue",
+                            inactive: "Edit selections",
+                            initialValue: true,
+                        });
+                        if (isCancel(confirmed)) {
+                            throwInitCanceled();
+                        }
+                        if (!confirmed) {
+                            draftSetup = nextSetup;
+                            draftServices = nextServices;
+                            continue;
+                        }
+                    }
+                    approvedPlan = nextSetup;
+                    approvedServices = nextServices;
+                    break;
                 }
-                if (!skipSetupUpload) {
+            }
+            if (!approvedPlan) {
+                throw new Error("Setup plan missing.");
+            }
+            if (!approvedServices) {
+                throw new Error("Services plan missing.");
+            }
+            const ensuredPlan = approvedPlan;
+            if (!skipSetupPlan) {
+                await writeSetupPlan(setupPath, ensuredPlan);
+                await updateInitState({ steps: { setupPlanWritten: true } });
+            }
+            if (!skipServicesPlan) {
+                await writeServicesPlan(servicesPath, approvedServices);
+                await updateInitState({ steps: { servicesPlanWritten: true } });
+            }
+            if (!skipSetupUpload) {
+                setupArtifacts = await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Packaging setup artifacts",
+                    fn: async () => await createSetupArtifacts({
+                        repoRoot,
+                        plan: ensuredPlan,
+                        outputDir: setupDir,
+                        tempDir: setupTempDir,
+                        homeDir: localHomeDir,
+                    }),
+                });
+            }
+        }
+        finally {
+            await fs.rm(setupTempDir, { recursive: true, force: true });
+        }
+        const skipProvision = shouldResume && initState?.steps.workdirProvisioned;
+        if (skipProvision && !skipSetupUpload) {
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Uploading setup plan",
+                fn: async ({ status }) => {
                     await uploadSetupPlan({
                         client,
                         canonical,
@@ -875,6 +1636,287 @@ export const runInit = async (args) => {
                             : null,
                         status,
                     });
+                },
+            });
+            await updateInitState({ steps: { setupUploaded: true } });
+            await updateRegistryProjectStatus(resolveInitStatus(initState?.steps, initState?.complete));
+        }
+        else if (!skipProvision || !skipSetupUpload) {
+            const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "devbox-init-"));
+            const bundlePath = path.join(tempDir, "repo.bundle");
+            const archivePath = path.join(tempDir, "repo.tgz");
+            const gitMetaPath = path.join(tempDir, "git-meta.tgz");
+            const gitMetaListPath = path.join(tempDir, "git-meta.list");
+            const stagedPatchPath = path.join(tempDir, "staged.patch");
+            const unstagedPatchPath = path.join(tempDir, "unstaged.patch");
+            const untrackedPath = path.join(tempDir, "untracked.tgz");
+            const untrackedListPath = path.join(tempDir, "untracked.list");
+            const globalGitConfigSources = await readGlobalGitConfigFiles(repoRoot);
+            const globalGitConfigMappings = mapGlobalGitConfigDestinations(globalGitConfigSources, localHomeDir);
+            try {
+                const remoteBundlePath = "/home/sprite/.devbox/upload.bundle";
+                const remoteArchivePath = "/home/sprite/.devbox/upload.tgz";
+                const remoteGitMetaPath = "/home/sprite/.devbox/git-meta.tgz";
+                const remoteStagedPatchPath = "/home/sprite/.devbox/staged.patch";
+                const remoteUnstagedPatchPath = "/home/sprite/.devbox/unstaged.patch";
+                const remoteUntrackedPath = "/home/sprite/.devbox/untracked.tgz";
+                const remoteHasGit = await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Preparing remote directories",
+                    fn: async ({ status }) => {
+                        status.stage("Checking remote git");
+                        const gitCheck = await client.exec(canonical, [
+                            "/bin/bash",
+                            "-lc",
+                            "git --version",
+                        ]);
+                        const remoteHasGit = gitCheck.exitCode === 0;
+                        const remoteDirs = new Set();
+                        remoteDirs.add(path.posix.dirname(remoteBundlePath));
+                        remoteDirs.add(path.posix.dirname(remoteArchivePath));
+                        remoteDirs.add(path.posix.dirname(remoteGitMetaPath));
+                        remoteDirs.add(path.posix.dirname(remoteStagedPatchPath));
+                        remoteDirs.add(path.posix.dirname(remoteUnstagedPatchPath));
+                        remoteDirs.add(path.posix.dirname(remoteUntrackedPath));
+                        for (const mapping of globalGitConfigMappings) {
+                            remoteDirs.add(path.posix.dirname(mapping.dest));
+                        }
+                        if (remoteDirs.size > 0) {
+                            status.stage("Preparing remote directories");
+                            const prepResult = await client.exec(canonical, [
+                                "/bin/bash",
+                                "-lc",
+                                `mkdir -p ${[...remoteDirs].map(shellQuote).join(" ")}`,
+                            ]);
+                            if (prepResult.exitCode !== 0) {
+                                throw new Error(prepResult.stderr || "Failed to prepare remote dirs");
+                            }
+                        }
+                        return remoteHasGit;
+                    },
+                });
+                const { headState, gitCommonDir, worktreeState, copyWorktree } = await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Inspecting repo state",
+                    fn: async ({ status }) => {
+                        const headState = await readHeadState(repoRoot);
+                        const resolved = await resolveGitCommonDir(repoRoot);
+                        const worktreeState = await readWorktreeState(repoRoot);
+                        const hasWorktreeChanges = worktreeState.staged.length > 0 ||
+                            worktreeState.unstaged.length > 0 ||
+                            worktreeState.untracked.length > 0;
+                        let copyWorktree = false;
+                        if (hasWorktreeChanges && process.stdin.isTTY && !parsed.json) {
+                            status.stop();
+                            copyWorktree = await confirmCopyWorktree(worktreeState);
+                            status.stage("Inspecting repo state");
+                        }
+                        else if (hasWorktreeChanges) {
+                            copyWorktree = true;
+                        }
+                        return {
+                            headState,
+                            gitCommonDir: resolved.commonDir,
+                            worktreeState,
+                            copyWorktree,
+                        };
+                    },
+                });
+                const packaged = await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Packaging repo",
+                    fn: async ({ status }) => {
+                        let gitMetaCreated = false;
+                        let stagedPatchCreated = false;
+                        let unstagedPatchCreated = false;
+                        let untrackedCreated = false;
+                        if (remoteHasGit) {
+                            status.stage("Packaging repo bundle");
+                            await runCommand(repoRoot, "git", [
+                                "bundle",
+                                "create",
+                                bundlePath,
+                                "--all",
+                            ]);
+                            status.stage("Packaging git metadata");
+                            gitMetaCreated = await createGitMetaArchive(gitCommonDir, gitMetaPath, gitMetaListPath);
+                            if (copyWorktree) {
+                                status.stage("Packaging repo changes");
+                                stagedPatchCreated = await writePatch(repoRoot, ["diff", "--binary", "--cached"], stagedPatchPath);
+                                unstagedPatchCreated = await writePatch(repoRoot, ["diff", "--binary"], unstagedPatchPath);
+                                untrackedCreated = await createFileListArchive(repoRoot, worktreeState.untracked, untrackedPath, untrackedListPath);
+                            }
+                        }
+                        else {
+                            status.stage("Packaging repo archive");
+                            if (copyWorktree) {
+                                const workingFiles = await readNullSeparatedPaths(repoRoot, [
+                                    "ls-files",
+                                    "--cached",
+                                    "--others",
+                                    "--exclude-standard",
+                                ]);
+                                await createFileListArchive(repoRoot, workingFiles, archivePath, untrackedListPath);
+                            }
+                            else {
+                                await runCommand(repoRoot, "git", [
+                                    "archive",
+                                    "--format=tar.gz",
+                                    "-o",
+                                    archivePath,
+                                    "HEAD",
+                                ]);
+                            }
+                        }
+                        return {
+                            gitMetaCreated,
+                            stagedPatchCreated,
+                            unstagedPatchCreated,
+                            untrackedCreated,
+                        };
+                    },
+                });
+                await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Uploading repo",
+                    fn: async ({ status }) => {
+                        if (remoteHasGit) {
+                            status.stage("Uploading repo bundle");
+                            const bundleData = await fs.readFile(bundlePath);
+                            await client.writeFile(canonical, remoteBundlePath, bundleData);
+                            if (packaged.gitMetaCreated) {
+                                status.stage("Uploading git metadata");
+                                const gitMetaData = await fs.readFile(gitMetaPath);
+                                await client.writeFile(canonical, remoteGitMetaPath, gitMetaData);
+                            }
+                            if (packaged.stagedPatchCreated) {
+                                status.stage("Uploading staged changes");
+                                await client.writeFile(canonical, remoteStagedPatchPath, await fs.readFile(stagedPatchPath));
+                            }
+                            if (packaged.unstagedPatchCreated) {
+                                status.stage("Uploading unstaged changes");
+                                await client.writeFile(canonical, remoteUnstagedPatchPath, await fs.readFile(unstagedPatchPath));
+                            }
+                            if (packaged.untrackedCreated) {
+                                status.stage("Uploading untracked files");
+                                await client.writeFile(canonical, remoteUntrackedPath, await fs.readFile(untrackedPath));
+                            }
+                        }
+                        else {
+                            status.stage("Uploading repo archive");
+                            await client.writeFile(canonical, remoteArchivePath, await fs.readFile(archivePath));
+                        }
+                        if (globalGitConfigMappings.length > 0) {
+                            status.stage("Uploading git config");
+                            for (const mapping of globalGitConfigMappings) {
+                                const data = await fs.readFile(mapping.source);
+                                await client.writeFile(canonical, mapping.dest, data);
+                            }
+                        }
+                    },
+                });
+                await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Provisioning workdir",
+                    fn: async () => {
+                        const backup = `${expandedWorkdir}.bak-${Date.now()}`;
+                        if (remoteHasGit) {
+                            const checkoutCommand = headState.branch
+                                ? `git checkout -B ${shellQuote(headState.branch)} ${shellQuote(headState.commit)}`
+                                : `git checkout --detach ${shellQuote(headState.commit)}`;
+                            const remoteCommand = [
+                                "set -euo pipefail",
+                                "unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE",
+                                `if [ -d ${shellQuote(expandedWorkdir)} ]; then`,
+                                parsed.force
+                                    ? `  mv ${shellQuote(expandedWorkdir)} ${shellQuote(backup)}`
+                                    : `  echo "Target exists: ${expandedWorkdir}" >&2; exit 1`,
+                                "fi",
+                                `mkdir -p ${shellQuote(path.dirname(expandedWorkdir))}`,
+                                `git init -b devbox-init ${shellQuote(expandedWorkdir)}`,
+                                `cd ${shellQuote(expandedWorkdir)}`,
+                                `git fetch ${shellQuote(remoteBundlePath)} 'refs/*:refs/*'`,
+                                `if [ -f ${shellQuote(remoteGitMetaPath)} ]; then`,
+                                `  tar -xzf ${shellQuote(remoteGitMetaPath)} -C .git`,
+                                "fi",
+                                checkoutCommand,
+                                `if [ -f ${shellQuote(remoteStagedPatchPath)} ]; then`,
+                                `  git apply --index ${shellQuote(remoteStagedPatchPath)}`,
+                                "fi",
+                                `if [ -f ${shellQuote(remoteUnstagedPatchPath)} ]; then`,
+                                `  git apply ${shellQuote(remoteUnstagedPatchPath)}`,
+                                "fi",
+                                `if [ -f ${shellQuote(remoteUntrackedPath)} ]; then`,
+                                `  tar -xzf ${shellQuote(remoteUntrackedPath)} -C .`,
+                                "fi",
+                            ].join("\n");
+                            const execResult = await client.exec(canonical, [
+                                "/bin/bash",
+                                "--noprofile",
+                                "--norc",
+                                "-e",
+                                "-u",
+                                "-o",
+                                "pipefail",
+                                "-c",
+                                remoteCommand,
+                            ]);
+                            if (execResult.exitCode !== 0) {
+                                throw new Error(execResult.stderr || "Remote init failed");
+                            }
+                        }
+                        else {
+                            const remoteCommand = [
+                                "set -euo pipefail",
+                                "unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE",
+                                `if [ -d ${shellQuote(expandedWorkdir)} ]; then`,
+                                parsed.force
+                                    ? `  mv ${shellQuote(expandedWorkdir)} ${shellQuote(backup)}`
+                                    : `  echo "Target exists: ${expandedWorkdir}" >&2; exit 1`,
+                                "fi",
+                                `mkdir -p ${shellQuote(expandedWorkdir)}`,
+                                `tar -xzf ${shellQuote(remoteArchivePath)} -C ${shellQuote(expandedWorkdir)}`,
+                            ].join("\n");
+                            const execResult = await client.exec(canonical, [
+                                "/bin/bash",
+                                "--noprofile",
+                                "--norc",
+                                "-e",
+                                "-u",
+                                "-o",
+                                "pipefail",
+                                "-c",
+                                remoteCommand,
+                            ]);
+                            if (execResult.exitCode !== 0) {
+                                throw new Error(execResult.stderr || "Remote init failed");
+                            }
+                        }
+                        await updateInitState({ steps: { workdirProvisioned: true } });
+                    },
+                });
+                if (!skipSetupUpload) {
+                    await runInitStep({
+                        enabled: progressEnabled,
+                        title: "Uploading setup plan",
+                        fn: async ({ status }) => {
+                            await uploadSetupPlan({
+                                client,
+                                canonical,
+                                localSetupPath: setupPath,
+                                remoteSetupPath,
+                                localArtifactsBundlePath: setupArtifacts?.bundlePath ?? null,
+                                localArtifactsManifestPath: setupArtifacts?.manifestPath ?? null,
+                                remoteArtifactsBundlePath: setupArtifacts
+                                    ? path.posix.join(expandedWorkdir, ".devbox", "setup-artifacts.tgz")
+                                    : null,
+                                remoteArtifactsManifestPath: setupArtifacts
+                                    ? path.posix.join(expandedWorkdir, ".devbox", "setup-artifacts.json")
+                                    : null,
+                                status,
+                            });
+                        },
+                    });
                     await updateInitState({ steps: { setupUploaded: true } });
                     await updateRegistryProjectStatus(resolveInitStatus(initState?.steps, initState?.complete));
                 }
@@ -883,165 +1925,280 @@ export const runInit = async (args) => {
                 await fs.rm(tempDir, { recursive: true, force: true });
             }
         }
-        await ensureWorkdirOwnership({
-            client,
-            canonical,
-            workdir: expandedWorkdir,
-            status,
-            json: parsed.json === true,
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Ensuring workdir ownership",
+            fn: async ({ status }) => {
+                await ensureWorkdirOwnership({
+                    client,
+                    canonical,
+                    workdir: expandedWorkdir,
+                    status,
+                    json: parsed.json === true,
+                });
+            },
         });
+        const skipGitSafeDirectory = shouldResume && initState?.steps.gitSafeDirectoryConfigured;
+        if (!skipGitSafeDirectory) {
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Configuring git safe.directory",
+                fn: async ({ status }) => {
+                    await ensureGitSafeDirectory({
+                        client,
+                        canonical,
+                        workdir: expandedWorkdir,
+                        status,
+                    });
+                    await updateInitState({ steps: { gitSafeDirectoryConfigured: true } });
+                },
+            });
+        }
         const skipSshdConfig = shouldResume && initState?.steps.sshdConfigured;
         if (!skipSshdConfig) {
-            status.stage("Configuring SSH mount access");
-            await ensureLocalMountKey();
-            await ensureKnownHostsFile();
-            const publicKey = await readLocalMountPublicKey();
-            await ensureRemoteMountAccess(client, canonical, publicKey);
-            await ensureSshdService(client, canonical);
-            await updateInitState({ steps: { sshdConfigured: true } });
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Configuring SSH mount access",
+                fn: async ({ fail }) => {
+                    try {
+                        await ensureLocalMountKey();
+                        await ensureKnownHostsFile();
+                        const publicKey = await readLocalMountPublicKey();
+                        await ensureRemoteMountAccess(client, canonical, publicKey);
+                        await ensureSshdService(client, canonical);
+                        await updateInitState({ steps: { sshdConfigured: true } });
+                    }
+                    catch (error) {
+                        logger.warn("sshd_config_failed", {
+                            box: canonical,
+                            error: String(error),
+                        });
+                        fail("Configuring SSH mount access (failed)");
+                        if (!parsed.json) {
+                            const message = error instanceof Error && error.message
+                                ? error.message
+                                : String(error);
+                            console.warn(`Warning: failed to configure SSH mount access. ${message}`);
+                            console.warn(`To retry later: dvb mount ${alias}`);
+                        }
+                    }
+                },
+            });
         }
         const skipSshAuth = nonInteractive ||
             (shouldResume && initState?.steps.sshAuthConfigured);
         if (!skipSshAuth) {
-            status.stage("Configuring git SSH auth");
-            const remoteOrigin = await readRemoteOrigin(client, canonical, expandedWorkdir);
+            const { remoteOrigin, remoteInfo } = await runInitStep({
+                enabled: progressEnabled,
+                title: "Checking git remote for SSH auth",
+                fn: async () => {
+                    const remoteOrigin = await readRemoteOrigin(client, canonical, expandedWorkdir);
+                    const remoteInfo = remoteOrigin ? parseGitRemote(remoteOrigin) : null;
+                    return { remoteOrigin, remoteInfo };
+                },
+            });
             if (!remoteOrigin) {
                 if (!parsed.json) {
-                    status.stop();
                     console.warn("Warning: unable to detect remote origin on sprite. Skipping SSH setup.");
                 }
             }
+            else if (!remoteInfo) {
+                if (!parsed.json) {
+                    console.warn(`Warning: unrecognized git remote format (${remoteOrigin}). Skipping SSH setup.`);
+                }
+            }
             else {
-                const remoteInfo = parseGitRemote(remoteOrigin);
-                if (!remoteInfo) {
+                let activeOrigin = remoteOrigin;
+                if (remoteInfo.protocol === "https") {
                     if (!parsed.json) {
-                        status.stop();
-                        console.warn(`Warning: unrecognized git remote format (${remoteOrigin}). Skipping SSH setup.`);
+                        clackNote([
+                            `Origin is HTTPS (${remoteOrigin}).`,
+                            "",
+                            "SSH auth will not work unless we switch this remote to SSH:",
+                            remoteInfo.sshUrl,
+                        ].join("\n"), "Git remote");
                     }
-                }
-                else {
-                    let activeOrigin = remoteOrigin;
-                    if (remoteInfo.protocol === "https") {
+                    const shouldSwitch = await clackSelect({
+                        message: "Switch remote origin to SSH for git auth?",
+                        options: [
+                            { value: "switch", label: "Switch to SSH (Recommended)" },
+                            { value: "keep", label: "Keep HTTPS (Skip SSH auth setup)" },
+                            { value: "cancel", label: "Cancel init" },
+                        ],
+                        initialValue: "switch",
+                    });
+                    if (isCancel(shouldSwitch) || shouldSwitch === "cancel") {
+                        throwInitCanceled();
+                    }
+                    if (shouldSwitch === "keep") {
                         if (!parsed.json) {
-                            status.stop();
-                            console.log(`Origin is HTTPS (${remoteOrigin}). SSH auth will not work unless we switch this remote to SSH.`);
+                            console.warn("Skipping SSH auth setup. Configure git credentials for this repo manually before pulling or pushing.");
                         }
-                        const shouldSwitch = await promptYesNo("Switch origin to SSH for sprite git auth?", false);
-                        if (!shouldSwitch) {
-                            if (!parsed.json) {
-                                console.warn("Skipping SSH auth setup. Configure git credentials for this repo manually before pulling or pushing.");
-                            }
-                            activeOrigin = "";
+                        activeOrigin = "";
+                    }
+                    else {
+                        await runInitStep({
+                            enabled: progressEnabled,
+                            title: "Switching git remote to SSH",
+                            fn: async () => {
+                                await setRemoteOrigin(client, canonical, expandedWorkdir, remoteInfo.sshUrl);
+                            },
+                        });
+                        activeOrigin = remoteInfo.sshUrl;
+                    }
+                }
+                if (activeOrigin) {
+                    const publicKey = await runInitStep({
+                        enabled: progressEnabled,
+                        title: "Generating SSH key",
+                        fn: async () => await ensureSshKey(client, canonical, `${alias}@devbox`),
+                    });
+                    await runInitStep({
+                        enabled: progressEnabled,
+                        title: "Updating SSH config",
+                        fn: async () => await ensureSshConfig(client, canonical, remoteInfo.host),
+                    });
+                    if (!parsed.json) {
+                        clackNote(publicKey, `Add this SSH public key to ${remoteInfo.host}`);
+                        const copied = await copyToClipboard(publicKey);
+                        if (copied) {
+                            clackLog.success("Copied SSH public key to clipboard.");
                         }
                         else {
-                            status.stage("Switching git remote to SSH");
-                            await setRemoteOrigin(client, canonical, expandedWorkdir, remoteInfo.sshUrl);
-                            activeOrigin = remoteInfo.sshUrl;
+                            clackLog.warn("Could not copy the SSH key automatically.");
                         }
+                        const shouldOpen = await promptBeforeOpenBrowser({
+                            url: remoteInfo.settingsUrl,
+                            title: `${remoteInfo.host} SSH key page`,
+                            consequence: [
+                                "Skipping browser open.",
+                                "You must add the SSH key before git pull/push will work via SSH.",
+                            ].join(" "),
+                        });
+                        if (shouldOpen) {
+                            const opened = openBrowser(remoteInfo.settingsUrl);
+                            if (!opened) {
+                                clackLog.warn("Unable to open the browser automatically.");
+                            }
+                        }
+                    }
+                    const added = await clackConfirm({
+                        message: "Have you added the SSH key?",
+                        active: "Yes, verify now",
+                        inactive: "Not yet",
+                        initialValue: true,
+                    });
+                    if (isCancel(added)) {
+                        throwInitCanceled();
                     }
-                    if (activeOrigin) {
-                        status.stage("Generating SSH key");
-                        const publicKey = await ensureSshKey(client, canonical, `${alias}@devbox`);
-                        status.stage("Updating SSH config");
-                        await ensureSshConfig(client, canonical, remoteInfo.host);
+                    if (!added) {
                         if (!parsed.json) {
-                            status.stop();
-                            console.log("");
-                            console.log(`Add this SSH public key to ${remoteInfo.host}:`);
-                            console.log(publicKey);
-                            console.log(`Open: ${remoteInfo.settingsUrl}`);
-                            const copied = await copyToClipboard(publicKey);
-                            if (copied) {
-                                console.log("Copied the SSH public key to your clipboard.");
-                            }
-                            else {
-                                console.log("Could not copy the SSH key automatically.");
-                            }
-                            const shouldOpen = await promptToContinue("Press Enter to open the SSH key page in your browser...");
-                            if (shouldOpen) {
-                                const opened = openBrowser(remoteInfo.settingsUrl);
-                                if (!opened) {
-                                    console.log("Unable to open the browser automatically.");
-                                }
-                            }
+                            console.warn("Skipping SSH verification. Add the key and re-run `dvb init --resume` to verify.");
                         }
-                        const added = await promptYesNo("Have you added the SSH key?", false);
-                        if (!added) {
+                    }
+                    else {
+                        const verified = await runInitStep({
+                            enabled: progressEnabled,
+                            title: "Verifying git SSH auth",
+                            fn: async () => await verifySshAuth(client, canonical, remoteInfo.host, expandedWorkdir),
+                        });
+                        if (!verified) {
                             if (!parsed.json) {
-                                console.warn("Skipping SSH verification. Add the key and re-run `dvb init --resume` to verify.");
+                                console.warn("SSH auth verification failed. Confirm the key is added and that the repo access is granted.");
                             }
                         }
                         else {
-                            status.stage("Verifying git SSH auth");
-                            const verified = await verifySshAuth(client, canonical, remoteInfo.host, expandedWorkdir);
-                            if (!verified) {
-                                if (!parsed.json) {
-                                    status.stop();
-                                    console.warn("SSH auth verification failed. Confirm the key is added and that the repo access is granted.");
-                                }
-                            }
-                            else {
-                                await updateInitState({
-                                    steps: { sshAuthConfigured: true },
-                                });
-                            }
+                            await updateInitState({
+                                steps: { sshAuthConfigured: true },
+                            });
                         }
                     }
                 }
             }
         }
-        if (!shouldResume || !initState?.steps.weztermMuxInstalled) {
-            status.stage("Installing WezTerm mux server");
-            try {
-                await installWeztermMux({ client, spriteName: canonical });
-                await updateInitState({ steps: { weztermMuxInstalled: true } });
-            }
-            catch (error) {
-                logger.warn("wezterm_mux_install_failed", {
-                    box: canonical,
-                    error: String(error),
-                });
-                if (!parsed.json) {
-                    status.stop();
-                    const message = error instanceof Error && error.message
-                        ? error.message
-                        : String(error);
-                    console.warn(`Warning: failed to install WezTerm mux server. ${message}`);
+        const weztermMuxPresent = await runInitStep({
+            enabled: progressEnabled,
+            title: "Ensuring WezTerm mux server (optional)",
+            fn: async ({ fail }) => {
+                try {
+                    const installResult = !shouldResume || !initState?.steps.weztermMuxInstalled
+                        ? await ensureWeztermMuxInstalled({
+                            client,
+                            spriteName: canonical,
+                            allowResolveAsset: true,
+                        })
+                        : await ensureWeztermMuxInstalled({
+                            client,
+                            spriteName: canonical,
+                            // If the mux is missing on resume, we still need to resolve a GitHub asset.
+                            allowResolveAsset: true,
+                        });
+                    if (installResult.muxPresent) {
+                        await updateInitState({ steps: { weztermMuxInstalled: true } });
+                    }
+                    return installResult.muxPresent;
                 }
-            }
-        }
-        status.stage("Ensuring WezTerm mux service");
-        try {
-            await ensureWeztermMuxService({ client, spriteName: canonical });
-            await updateInitState({ steps: { weztermMuxServiceEnsured: true } });
-        }
-        catch (error) {
-            logger.warn("wezterm_mux_service_failed", {
-                box: canonical,
-                error: String(error),
+                catch (error) {
+                    logger.warn("wezterm_mux_install_failed", {
+                        box: canonical,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    fail("Ensuring WezTerm mux server (optional) (failed)");
+                    if (!parsed.json) {
+                        const message = error instanceof Error && error.message
+                            ? error.message
+                            : String(error);
+                        console.warn(`Warning: failed to install WezTerm mux server (optional). ${message}\n` +
+                            "Tip: re-run with DEVBOX_LOG_LEVEL=info to see Sprite exec logs on stderr.");
+                    }
+                    return false;
+                }
+            },
+        });
+        if (weztermMuxPresent &&
+            (!shouldResume || !initState?.steps.weztermMuxServiceEnsured)) {
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Ensuring WezTerm mux service (optional)",
+                fn: async ({ fail }) => {
+                    try {
+                        await ensureWeztermMuxService({ client, spriteName: canonical });
+                        await updateInitState({ steps: { weztermMuxServiceEnsured: true } });
+                    }
+                    catch (error) {
+                        logger.warn("wezterm_mux_service_failed", {
+                            box: canonical,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        fail("Ensuring WezTerm mux service (optional) (failed)");
+                        if (!parsed.json) {
+                            const message = error instanceof Error && error.message
+                                ? error.message
+                                : String(error);
+                            console.warn(`Warning: failed to ensure WezTerm mux service (optional). ${message}`);
+                        }
+                    }
+                },
             });
-            if (!parsed.json) {
-                status.stop();
-                const message = error instanceof Error && error.message
-                    ? error.message
-                    : String(error);
-                console.warn(`Warning: failed to ensure WezTerm mux service. ${message}`);
-            }
         }
         if (!skipServicesConfig) {
             if (!approvedServices) {
                 throw new Error("Missing services plan output.");
             }
-            status.stage("Writing devbox.toml services");
-            await writeRemoteServicesToml({
-                client,
-                canonical,
-                workdir: expandedWorkdir,
-                services: approvedServices.backgroundServices,
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Writing devbox.toml services",
+                fn: async () => {
+                    await writeRemoteServicesToml({
+                        client,
+                        canonical,
+                        workdir: expandedWorkdir,
+                        services: approvedServices.backgroundServices,
+                    });
+                    await updateInitState({ steps: { servicesConfigWritten: true } });
+                },
             });
-            await updateInitState({ steps: { servicesConfigWritten: true } });
         }
-        status.stage("Registering project");
         const projectMeta = {
             fingerprint,
             canonical,
@@ -1050,23 +2207,64 @@ export const runInit = async (args) => {
             origin: projectOrigin,
             createdAt: projectCreatedAt,
         };
-        await client.writeFile(canonical, `/home/sprite/.devbox/projects/${fingerprint}.json`, Buffer.from(JSON.stringify(projectMeta, null, 2)));
-        status.stage("Writing local metadata");
-        await ensureDevboxToml(repoRoot, repoName, slug);
-        await writeRepoMarker(repoRoot, { fingerprint, canonical, alias });
-        status.stage("Updating Codex config on sprite");
-        try {
-            await writeRemoteCodexConfig(client, canonical, repoName);
-        }
-        catch (error) {
-            logger.warn("codex_config_update_failed", {
-                error: String(error),
-            });
-            if (!parsed.json) {
-                status.stop();
-                console.warn("Warning: failed to update /home/sprite/.codex/config.toml for full-access sandbox settings.");
-            }
-        }
+        const projectMetaPath = `/home/sprite/.devbox/projects/${fingerprint}.json`;
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Registering project",
+            fn: async () => {
+                let existing = {};
+                try {
+                    const raw = await client.readFile(canonical, { path: projectMetaPath });
+                    const parsed = JSON.parse(Buffer.from(raw).toString("utf8"));
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        existing = parsed;
+                    }
+                }
+                catch (error) {
+                    if (!(error instanceof SpritesApiError && error.status === 404)) {
+                        throw error;
+                    }
+                }
+                const existingCheckpoints = existing.checkpoints &&
+                    typeof existing.checkpoints === "object" &&
+                    !Array.isArray(existing.checkpoints)
+                    ? existing.checkpoints
+                    : {};
+                const stateCheckpoints = initState?.checkpoints ?? {};
+                const merged = {
+                    ...existing,
+                    ...projectMeta,
+                    checkpoints: { ...existingCheckpoints, ...stateCheckpoints },
+                };
+                await client.writeFile(canonical, projectMetaPath, Buffer.from(JSON.stringify(merged, null, 2)));
+            },
+        });
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Writing local metadata",
+            fn: async () => {
+                await ensureDevboxToml(repoRoot, repoName, slug);
+                await writeRepoMarker(repoRoot, { fingerprint, canonical, alias });
+            },
+        });
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Updating Codex config on sprite (optional)",
+            fn: async ({ fail }) => {
+                try {
+                    await writeRemoteCodexConfig(client, canonical, repoName);
+                }
+                catch (error) {
+                    logger.warn("codex_config_update_failed", {
+                        error: String(error),
+                    });
+                    fail("Updating Codex config on sprite (optional) (failed)");
+                    if (!parsed.json) {
+                        console.warn("Warning: failed to update /home/sprite/.codex/config.toml for full-access sandbox settings.");
+                    }
+                }
+            },
+        });
         try {
             const gitignore = await fs.readFile(path.join(repoRoot, ".gitignore"), "utf8");
             if (!gitignore.includes(".devbox")) {
@@ -1076,42 +2274,143 @@ export const runInit = async (args) => {
         catch {
             // ignore missing .gitignore
         }
+        const skipSetupArtifactsStage = skipCodexApply ||
+            (shouldResume && initState?.steps.setupArtifactsStaged);
+        if (!skipSetupArtifactsStage) {
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Staging setup artifacts",
+                fn: async ({ status }) => {
+                    status.stage("Copying repo artifacts and staging external files");
+                    await stageRemoteSetupArtifacts({
+                        client,
+                        canonical,
+                        workdir: expandedWorkdir,
+                        artifactsBundlePath: remoteArtifactsBundlePath,
+                        artifactsManifestPath: remoteArtifactsManifestPath,
+                    });
+                },
+            });
+            await updateInitState({ steps: { setupArtifactsStaged: true } });
+        }
         if (!skipCodexApply) {
-            await runRemoteCodexSetup({
-                client,
-                canonical,
-                expandedWorkdir,
-                remoteSetupPath,
-                remoteArtifactsBundlePath,
-                remoteArtifactsManifestPath,
-                socketInfo,
-                status,
-                pathSetup,
-                entrypoints: approvedServices?.appEntrypoints ?? [],
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Snapshotting filesystem (pre-setup) (optional)",
+                fn: async ({ fail, ok }) => {
+                    try {
+                        const checkpoint = await recordCodexCheckpoint({
+                            client,
+                            canonical,
+                            phase: "preCodexSetup",
+                        });
+                        if (checkpoint.id) {
+                            ok(`Snapshot created: ${checkpoint.id}`);
+                        }
+                    }
+                    catch (error) {
+                        logger.warn("init_checkpoint_create_failed", {
+                            box: canonical,
+                            fingerprint,
+                            phase: "pre-codex-setup",
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        fail("Snapshotting filesystem (pre-setup) (optional) (failed)");
+                        if (!parsed.json) {
+                            console.warn("Warning: failed to create pre-setup filesystem snapshot. Continuing without it.");
+                        }
+                    }
+                },
+            });
+            if (!skipServicesEnable) {
+                await runInitStep({
+                    enabled: progressEnabled,
+                    title: "Enabling devbox services",
+                    fn: async ({ status }) => {
+                        await enableRemoteServices({
+                            client,
+                            canonical,
+                            services: approvedServices?.backgroundServices ?? [],
+                            status,
+                        });
+                        await updateInitState({ steps: { servicesEnabled: true } });
+                    },
+                });
+            }
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Running Codex setup",
+                fn: async ({ status }) => {
+                    await runRemoteCodexSetup({
+                        client,
+                        canonical,
+                        expandedWorkdir,
+                        remoteSetupPath,
+                        remoteArtifactsBundlePath,
+                        remoteArtifactsManifestPath,
+                        socketInfo,
+                        status,
+                        pathSetup,
+                        entrypoints: approvedServices?.appEntrypoints ?? [],
+                    });
+                },
             });
             await updateInitState({ steps: { codexApplied: true } });
             await updateRegistryProjectStatus(resolveInitStatus(initState?.steps, initState?.complete));
+            await runInitStep({
+                enabled: progressEnabled,
+                title: "Snapshotting filesystem (post-setup) (optional)",
+                fn: async ({ fail, ok }) => {
+                    try {
+                        const checkpoint = await recordCodexCheckpoint({
+                            client,
+                            canonical,
+                            phase: "postCodexSetup",
+                        });
+                        if (checkpoint.id) {
+                            ok(`Snapshot created: ${checkpoint.id}`);
+                        }
+                    }
+                    catch (error) {
+                        logger.warn("init_checkpoint_create_failed", {
+                            box: canonical,
+                            fingerprint,
+                            phase: "post-codex-setup",
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        fail("Snapshotting filesystem (post-setup) (optional) (failed)");
+                        if (!parsed.json) {
+                            console.warn("Warning: failed to create post-setup filesystem snapshot. Continuing without it.");
+                        }
+                    }
+                },
+            });
         }
-        await updateInitState({ complete: true });
-        await updateRegistryProjectStatus("complete");
-        status.stop();
+        const finalStatus = resolveInitStatus(initState?.steps, initState?.complete);
+        const isComplete = finalStatus === "complete";
+        await runInitStep({
+            enabled: progressEnabled,
+            title: "Finalizing init",
+            fn: async () => {
+                await updateInitState({ complete: isComplete });
+                await updateRegistryProjectStatus(finalStatus);
+            },
+        });
         if (parsed.json) {
-            console.log(JSON.stringify({ ok: true, canonical, alias, workdir, fingerprint }, null, 2));
+            console.log(JSON.stringify({ ok: true, status: finalStatus, canonical, alias, workdir, fingerprint }, null, 2));
+            return;
+        }
+        if (!isComplete) {
+            console.log(`devbox initialized (setup incomplete): ${alias} -> ${canonical}`);
+            console.log(`workdir: ${workdir}`);
+            console.log("next: run `dvb init --resume` from this repo to finish setup");
+            console.log("sprites: synced to control plane");
             return;
         }
         console.log(`devbox initialized: ${alias} -> ${canonical}`);
         console.log(`workdir: ${workdir}`);
         console.log("sprites: synced to control plane");
     };
-    try {
-        await run();
-    }
-    catch (error) {
-        status.fail("Init failed");
-        throw error;
-    }
-    finally {
-        status.stop();
-    }
+    await run();
 };
 //# sourceMappingURL=index.js.map