mimetic-cli 0.1.3 → 0.1.5

package/dist/program.js

@@ -2,11 +2,13 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
+import { loadEnvFile } from "./env-file.js";
 import { draftFeedback, listFeedback, renderIssueMarkdown, renderIssueUrl, verifyFeedback } from "./feedback.js";
 import { runInit } from "./init.js";
+import { inspectLabManifest, listLabManifests, resolveLabManifest } from "./labs.js";
 import { renderObserver, serveObserver } from "./observer.js";
 import { DEFAULT_OSS_REPOS, runOssLab } from "./oss-lab.js";
-import { runOssMetaLab } from "./oss-meta-lab.js";
+import { cleanupOssMetaLabSandboxes, runOssMetaLab, startOssMetaLabLiveRefresh } from "./oss-meta-lab.js";
 import { doctor, listRuns, readReview, runDryRun, verifyRun } from "./run.js";
 export const CLI_RESPONSE_SCHEMA = "mimetic.cli-response.v1";
 function readCliVersion() {
@@ -51,9 +53,12 @@ export const plannedCommands = [
         issue: "https://github.com/danielgwilson/mimetic-cli/issues/7",
         docs: commonDocs,
         options: [
+            { flags: "[lab]", description: "Optional lab id or .yaml path." },
             { flags: "--dry-run", description: "Generate contract proof without browser, keys, or provider spend." },
+            { flags: "--app-url <url>", description: "Capture live desktop/mobile browser evidence against a running loopback app URL." },
             { flags: "--actor codex-tui|codex-exec", description: "Explicitly opt into a local Codex actor." },
-            { flags: "--sims <count>", description: "Simulation count. Codex exec supports 1-4 lanes; Codex TUI supports 1." },
+            { flags: "--sims <count>", description: "Simulation count. Codex exec runs requested lanes with bounded concurrency; Codex TUI supports 1." },
+            { flags: "--env-file <path>", description: "Load a local env file for this run without persisting values." },
             { flags: "--cwd <path>", description: "Target project directory.", defaultValue: "." }
         ]
     },
@@ -81,8 +86,11 @@ export const plannedCommands = [
         issue: "https://github.com/danielgwilson/mimetic-cli/issues/10",
         docs: commonDocs,
         options: [
+            { flags: "[lab]", description: "Optional lab id or .yaml path to run and observe." },
+            { flags: "--lab <id-or-path>", description: "Explicit lab id or .yaml path." },
             { flags: "--run <id>", description: "Watch an existing run id or latest pointer." },
             { flags: "--sims <count>", description: "Start a fresh synthetic run with this many sims before rendering.", defaultValue: "4 when --run is omitted" },
+            { flags: "--env-file <path>", description: "Load a local env file for this watch without persisting values." },
             { flags: "--open", description: "Open the observer in the default browser.", defaultValue: "true for human output" },
             { flags: "--detach", description: "Render/open once and exit without attached watch server." },
             { flags: "--port <port>", description: "Local observer server port when following.", defaultValue: "0" },
@@ -113,10 +121,12 @@ export function createProgram(io = {}) {
         "",
         "Examples:",
         "  mimetic watch",
+        "  mimetic watch first-run",
+        "  mimetic watch --lab .mimetic/labs/local.yaml",
         "  mimetic watch --run latest --detach",
         "  mimetic watch --json --no-open",
-        "  mimetic lab oss --repos developit/mitt,lukeed/clsx",
-        "  mimetic lab oss-smoke --limit 1 --keep",
+        "  mimetic lab list",
+        "  mimetic lab run first-run --json --no-open",
         "  mimetic verify --run latest --json",
         "",
         "Public-safety boundary:",
@@ -180,15 +190,56 @@ function registerDoctorCommand(parent, io) {
 function registerRunCommand(parent, io) {
     parent
         .command("run")
+        .argument("[lab]", "Optional lab id or .yaml path.")
         .description("Run a persona/scenario simulation or synthetic dry-run bundle.")
         .option("--dry-run", "Generate contract proof without browser, keys, or provider spend.")
+        .option("--app-url <url>", "Capture live desktop/mobile browser evidence against a running loopback app URL.")
         .addOption(new Option("--actor <actor>", "Explicit live actor to run.").choices(["codex-tui", "codex-exec"]))
-        .option("--sims <count>", "Simulation count. Codex exec supports 1-4 lanes; Codex TUI supports 1.")
+        .option("--sims <count>", "Simulation count. Codex exec runs requested lanes with bounded concurrency; Codex TUI supports 1.")
         .option("--timeout-ms <ms>", "Local actor timeout in milliseconds.", String(240_000))
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load a local env file for this run without persisting values.")
         .option("--run-id <id>", "Explicit run id for deterministic fixture tests.")
         .option("--json", "Print a machine-readable JSON response.")
-        .action(async (options, command) => {
+        .action(async (lab, options, command) => {
+        if (!await applyEnvFileOption({
+            command,
+            cwd: options.cwd,
+            envFile: options.envFile,
+            io
+        })) {
+            return;
+        }
+        if (lab) {
+            if (options.appUrl !== undefined || options.actor !== undefined) {
+                const result = {
+                    schema: "mimetic.run-result.v1",
+                    ok: false,
+                    cwd: options.cwd,
+                    warnings: [],
+                    error: {
+                        code: "MIMETIC_APP_URL_OPTION_CONFLICT",
+                        message: "Use lab manifests with lab-compatible options only; --app-url and --actor belong to direct `mimetic run`."
+                    }
+                };
+                writeResult(command, io, result, formatRunHuman);
+                io.setExitCode(2);
+                return;
+            }
+            await runLabCommand({
+                command,
+                io,
+                lab,
+                mode: "run",
+                options: {
+                    cwd: options.cwd,
+                    ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+                    ...(options.runId === undefined ? {} : { runId: options.runId }),
+                    ...(options.sims === undefined ? {} : { sims: options.sims })
+                }
+            });
+            return;
+        }
         const simCount = options.sims === undefined ? undefined : parsePositiveInteger(options.sims);
         const timeoutMs = options.timeoutMs === undefined ? undefined : parseTimeoutMs(options.timeoutMs);
         if (options.sims !== undefined && simCount === null) {
@@ -199,7 +250,7 @@ function registerRunCommand(parent, io) {
                 warnings: [],
                 error: {
                     code: "MIMETIC_INVALID_SIM_COUNT",
-                    message: "--sims must be an integer between 1 and 64."
+                    message: "--sims must be a positive integer."
                 }
             };
             writeResult(command, io, result, formatRunHuman);
@@ -224,6 +275,7 @@ function registerRunCommand(parent, io) {
         const result = await runDryRun({
             cwd: options.cwd,
             ...(options.actor === undefined ? {} : { actor: options.actor }),
+            ...(options.appUrl === undefined ? {} : { appUrl: options.appUrl }),
             ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
             ...(options.runId === undefined ? {} : { runId: options.runId }),
             ...(simCount === undefined || simCount === null ? {} : { simCount }),
@@ -274,11 +326,22 @@ function registerRunsCommand(parent, io) {
 function registerWatchCommand(parent, io) {
     parent
         .command("watch")
+        .argument("[lab]", "Optional lab id or .yaml path to run and observe.")
         .description("Run sims, open the observer, and keep the shell attached.")
+        .option("--lab <id-or-path>", "Explicit lab id or .yaml path.")
         .option("--run <id>", "Watch an existing run id or latest pointer.")
+        .option("--dry-run", "Lab only: render contract evidence without live provider spend.")
         .option("--sims <count>", "Start a fresh synthetic run with this many sims before rendering. Defaults to 4 when --run is omitted.")
+        .option("--count <count>", "Lab only: override headed desktop lane count.")
+        .option("--limit <count>", "Lab only: override smoke lab repo limit.")
+        .option("--repo <owner/repo>", "Lab only: GitHub repo slug. Repeatable.", collectRepeated, [])
+        .option("--repos <owner/repo,...>", "Lab only: comma-separated GitHub repo slugs.")
+        .option("--redact-repos", "Lab only: redact repo labels in durable artifacts.")
+        .option("--no-redact-repos", "Lab only: persist repo labels. Use only for public-safe runs.")
+        .option("--keep", "Lab only: keep disposable clone sandbox for debugging.")
         .option("--run-id <id>", "Explicit run id for deterministic fixture tests.")
         .option("--cwd <path>", "Target project directory.", ".")
+        .option("--env-file <path>", "Load a local env file for this watch without persisting values.")
         .option("--open", "Open the observer in the default browser.")
         .option("--no-open", "Render without opening a browser.")
         .addOption(new Option("--follow", "Deprecated; human output follows by default.").hideHelp())
@@ -289,6 +352,8 @@ function registerWatchCommand(parent, io) {
         "",
         "Happy path:",
         "  mimetic watch",
+        "  mimetic watch first-run",
+        "  mimetic watch --lab .mimetic/labs/local.yaml",
         "",
         "Agent/CI path:",
         "  mimetic watch --json --no-open",
@@ -296,7 +361,70 @@ function registerWatchCommand(parent, io) {
         "Existing evidence:",
         "  mimetic watch --run latest --detach"
     ].join("\n"))
-        .action(async (options, command) => {
+        .action(async (labArg, options, command) => {
+        const lab = options.lab ?? labArg;
+        if (options.lab !== undefined && labArg !== undefined) {
+            const result = {
+                schema: "mimetic.run-result.v1",
+                ok: false,
+                cwd: options.cwd,
+                warnings: [],
+                error: {
+                    code: "MIMETIC_WATCH_OPTION_CONFLICT",
+                    message: "Use either positional lab or --lab, not both."
+                }
+            };
+            writeResult(command, io, result, formatRunHuman);
+            io.setExitCode(2);
+            return;
+        }
+        if (!await applyEnvFileOption({
+            command,
+            cwd: options.cwd,
+            envFile: options.envFile,
+            io
+        })) {
+            return;
+        }
+        if (lab) {
+            if (options.run !== undefined) {
+                const result = {
+                    schema: "mimetic.run-result.v1",
+                    ok: false,
+                    cwd: options.cwd,
+                    warnings: [],
+                    error: {
+                        code: "MIMETIC_WATCH_OPTION_CONFLICT",
+                        message: "Use either a lab to start evidence or --run to watch existing evidence, not both."
+                    }
+                };
+                writeResult(command, io, result, formatRunHuman);
+                io.setExitCode(2);
+                return;
+            }
+            await runLabCommand({
+                command,
+                io,
+                lab,
+                mode: "watch",
+                options: {
+                    cwd: options.cwd,
+                    ...(options.count === undefined ? {} : { count: options.count }),
+                    ...(options.detach === undefined ? {} : { detach: options.detach }),
+                    ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+                    ...(options.keep === undefined ? {} : { keep: options.keep }),
+                    ...(options.limit === undefined ? {} : { limit: options.limit }),
+                    ...(options.open === undefined ? {} : { open: options.open }),
+                    port: options.port,
+                    ...(options.redactRepos === undefined ? {} : { redactRepos: options.redactRepos }),
+                    repo: options.repo,
+                    ...(options.repos === undefined ? {} : { repos: options.repos }),
+                    ...(options.runId === undefined ? {} : { runId: options.runId }),
+                    ...(options.sims === undefined ? {} : { sims: options.sims })
+                }
+            });
+            return;
+        }
         const runOptionSource = typeof command.getOptionValueSource === "function"
             ? command.getOptionValueSource("run")
             : undefined;
@@ -311,7 +439,7 @@ function registerWatchCommand(parent, io) {
                 warnings: [],
                 error: {
                     code: "MIMETIC_INVALID_SIM_COUNT",
-                    message: "--sims must be an integer between 1 and 64."
+                    message: "--sims must be a positive integer."
                 }
             };
             writeResult(command, io, result, formatRunHuman);
@@ -494,12 +622,83 @@ function registerFeedbackCommands(parent, io) {
 function registerLabCommands(parent, io) {
     const lab = parent
         .command("lab")
-        .description("Run experimental Mimetic proof loops against disposable public targets.");
+        .description("List, inspect, and run Mimetic lab manifests.");
     lab
-        .command("oss")
-        .description("Watch headed Codex/E2B OSS meta-sims setting up Mimetic inside public repos.")
-        .option("--repos <owner/repo,...>", "Comma-separated public GitHub repo slugs.")
-        .option("--repo <owner/repo>", "Public GitHub repo slug. Repeatable.", collectRepeated, [])
+        .command("list")
+        .description("List committed and ignored Mimetic lab manifests.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", "Print a machine-readable JSON response.")
+        .action(async (options, command) => {
+        const result = await listLabManifests(options.cwd);
+        writeResult(command, io, result, formatLabListHuman);
+        io.setExitCode(0);
+    });
+    lab
+        .command("inspect")
+        .argument("<lab>", "Lab id or .yaml path.")
+        .description("Inspect a Mimetic lab manifest without running it.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", "Print a machine-readable JSON response.")
+        .action(async (labName, options, command) => {
+        const result = await inspectLabManifest(options.cwd, labName);
+        writeResult(command, io, result, formatLabInspectHuman);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+    lab
+        .command("run")
+        .argument("<lab>", "Lab id or .yaml path.")
+        .description("Run a Mimetic lab manifest.")
+        .option("--env-file <path>", "Load a local env file for this lab without persisting values.")
+        .option("--dry-run", "Render contract evidence without live provider spend.")
+        .option("--open", "Open the observer in the default browser.")
+        .option("--no-open", "Render without opening a browser.")
+        .option("--detach", "Render/open once and exit without attached watch server.")
+        .option("--port <port>", "Local observer server port when following.", "0")
+        .option("--sims <count>", "Override synthetic sims or headed desktop lanes.")
+        .option("--count <count>", "Override headed desktop lane count.")
+        .option("--limit <count>", "Override smoke lab repo limit.")
+        .option("--run-id <id>", "Explicit lab run id.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--repo <owner/repo>", "GitHub repo slug. Repeatable.", collectRepeated, [])
+        .option("--repos <owner/repo,...>", "Comma-separated GitHub repo slugs.")
+        .option("--redact-repos", "Redact repo labels in durable lab artifacts.")
+        .option("--no-redact-repos", "Persist repo labels in durable lab artifacts. Use only for public-safe runs.")
+        .option("--keep", "Smoke labs only: keep disposable clone sandbox for debugging.")
+        .option("--json", "Print a machine-readable JSON response.")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  mimetic lab run first-run",
+        "  mimetic lab run oss --dry-run --json --no-open",
+        "  mimetic lab run .mimetic/labs/private-dogfood.yaml --env-file .mimetic/local/provider.env",
+        "",
+        "Human watch path:",
+        "  mimetic watch first-run",
+        "  mimetic watch --lab .mimetic/labs/local.yaml"
+    ].join("\n"))
+        .action(async (labName, options, command) => {
+        if (!await applyEnvFileOption({
+            command,
+            cwd: options.cwd,
+            envFile: options.envFile,
+            io
+        })) {
+            return;
+        }
+        await runLabCommand({
+            command,
+            io,
+            lab: labName,
+            mode: "run",
+            options
+        });
+    });
+    lab
+        .command("oss", { hidden: true })
+        .description("Alias: run the bundled OSS meta-lab manifest.")
+        .option("--env-file <path>", "Load a local env file for this lab without persisting values.")
+        .option("--repos <owner/repo,...>", "Comma-separated GitHub repo slugs.")
+        .option("--repo <owner/repo>", "GitHub repo slug. Repeatable.", collectRepeated, [])
         .option("--count <count>", "Number of headed desktop sims to assign.", String(DEFAULT_OSS_REPOS.length))
         .option("--sims <count>", "Alias for --count.")
         .option("--run-id <id>", "Explicit lab run id.")
@@ -508,6 +707,8 @@ function registerLabCommands(parent, io) {
         .option("--open", "Open the observer in the default browser.")
         .option("--no-open", "Render without opening a browser.")
         .option("--detach", "Render/open once and exit without attached watch server.")
+        .option("--redact-repos", "Redact repo labels in durable lab artifacts.")
+        .option("--no-redact-repos", "Persist repo labels in durable lab artifacts. Defaults to redacted when a GitHub token is present.")
         .option("--port <port>", "Local observer server port when following.", "0")
         .option("--smoke", "Run the disposable local clone smoke harness instead of headed meta-sims.")
         .option("--limit <count>", "Smoke mode only: number of selected repos to trial.", String(DEFAULT_OSS_REPOS.length))
@@ -515,30 +716,42 @@ function registerLabCommands(parent, io) {
         .option("--json", "Print a machine-readable JSON response.")
         .addHelpText("after", [
         "",
-        "Happy path:",
-        "  mimetic lab oss",
+        "Preferred paths:",
+        "  mimetic watch oss",
+        "  mimetic lab run oss",
         "",
         "Repo selection:",
-        "  mimetic lab oss --repos developit/mitt,lukeed/clsx,sindresorhus/is-plain-obj,ai/nanoid",
-        "  mimetic lab oss --repo developit/mitt --repo lukeed/clsx --count 4",
+        "  mimetic watch --lab .mimetic/labs/local-oss.yaml",
+        "  mimetic lab run oss --repos CorentinTh/it-tools,drawdb-io/drawdb,maciekt07/TodoApp,lissy93/dashy",
+        "  mimetic lab run oss --repo CorentinTh/it-tools --repo drawdb-io/drawdb --count 4",
         "",
         "Agent/CI path:",
-        "  mimetic lab oss --dry-run --json --no-open",
+        "  mimetic lab run oss --dry-run --json --no-open",
         "",
         "Disposable clone smoke:",
+        "  mimetic lab run oss-smoke --limit 1 --keep",
         "  mimetic lab oss-smoke --limit 1 --keep",
-        "  mimetic lab oss --smoke --limit 1 --keep",
         "",
         "Shape:",
-        "  The top-level Observer shows headed E2B desktop lanes. Each desktop is intended",
-        "  to run Codex TUI, clone its assigned public OSS repo, set up Mimetic, and keep",
-        "  that repo's nested Mimetic Observer visible in the E2B browser.",
+        "  The top-level Observer shows headed E2B desktop lanes. Each desktop clones",
+        "  its assigned authorized repo, sets up Mimetic, starts the target app where",
+        "  feasible, opens desktop/mobile app windows plus the nested Observer, and",
+        "  starts a nonblocking Codex actor attempt.",
         "",
         "Safety:",
-        "  Only public GitHub owner/repo slugs are accepted. No keys or private artifacts",
-        "  are written into committed Mimetic source."
+        "  Only GitHub owner/repo slugs are accepted. Live stream auth URLs are",
+        "  runtime-only. Repo labels are redacted by default when a GitHub token",
+        "  is present; pass --no-redact-repos only for public-safe runs."
     ].join("\n"))
         .action(async (options, command) => {
+        if (!await applyEnvFileOption({
+            command,
+            cwd: options.cwd,
+            envFile: options.envFile,
+            io
+        })) {
+            return;
+        }
         if (options.smoke) {
             await runOssSmokeAction({ command, io, options });
             return;
@@ -569,38 +782,56 @@ function registerLabCommands(parent, io) {
         const wantsMachine = wantsJson(command);
         const shouldOpen = options.open === false ? false : wantsMachine ? options.open === true : true;
         const wantsFollow = !wantsMachine && options.detach !== true && options.dryRun !== true;
-        const result = await runOssMetaLab({
-            cwd: options.cwd,
-            open: wantsFollow ? false : shouldOpen,
-            repos: [...options.repo, ...(options.repos ? [options.repos] : [])],
-            ...(count === null ? { count: Number.NaN } : { count }),
-            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
-            ...(options.runId === undefined ? {} : { runId: options.runId })
-        });
+        const repoOverrideRequested = options.repo.length > 0 || options.repos !== undefined;
+        const redactRepoNames = options.redactRepos ?? (repoOverrideRequested ? true : undefined);
         let server = null;
+        let liveRefresh = null;
+        let result;
+        try {
+            result = await runOssMetaLab({
+                ...(wantsFollow ? { completionTimeoutMs: 0 } : {}),
+                cwd: options.cwd,
+                ...(wantsFollow
+                    ? {
+                        onObserverReady: async (observer) => {
+                            if (!server) {
+                                server = await serveObserver(observer, { open: shouldOpen, port });
+                            }
+                        }
+                    }
+                    : {}),
+                open: wantsFollow ? false : shouldOpen,
+                ...(redactRepoNames === undefined ? {} : { redactRepoNames }),
+                repos: [...options.repo, ...(options.repos ? [options.repos] : [])],
+                ...(count === null ? { count: Number.NaN } : { count }),
+                ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+                ...(options.runId === undefined ? {} : { runId: options.runId })
+            });
+        }
+        catch (error) {
+            const earlyServer = server;
+            await earlyServer?.close().catch((cleanupError) => {
+                io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+            });
+            server = null;
+            throw error;
+        }
         let output = result;
-        if (result.ok && wantsFollow && result.observer?.ok) {
+        if (server && shouldServeOssMetaLabObserver(result, { wantsFollow: true })) {
+            liveRefresh = startOssMetaLabLiveRefresh(result);
+            output = withOssMetaLabServer(result, server);
+        }
+        else if (shouldServeOssMetaLabObserver(result, { wantsFollow })) {
             server = await serveObserver(result.observer, { open: shouldOpen, port });
-            output = {
-                ...result,
-                observer: {
-                    ...result.observer,
-                    observerUrl: server.url,
-                    serverUrl: server.url,
-                    opened: server.opened,
-                    ...(server.openCommand ? { openCommand: server.openCommand } : {}),
-                    warnings: [
-                        ...result.observer.warnings,
-                        "Live OSS meta-lab server is polling observer-data.json with no-store caching.",
-                        ...(server.warning ? [server.warning] : [])
-                    ]
-                },
-                warnings: [
-                    ...result.warnings,
-                    "Live OSS meta-lab server is polling observer-data.json with no-store caching.",
-                    ...(server.warning ? [server.warning] : [])
-                ]
-            };
+            liveRefresh = startOssMetaLabLiveRefresh(result);
+            output = withOssMetaLabServer(result, server);
+        }
+        else {
+            const earlyServer = server;
+            await earlyServer?.close().catch((error) => {
+                io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+            server = null;
         }
         const exitCode = exitCodeForOssMetaLab(output);
         writeResult(command, io, output, formatOssMetaLabHuman);
@@ -610,12 +841,23 @@ function registerLabCommands(parent, io) {
             // return the user's shell, and JSON mode should exit after printing the result.
             setTimeout(() => process.exit(exitCode), 50);
         }
-        if (output.ok && server && output.observer?.ok) {
-            await followObserver(io, output.observer, server);
+        if (server && output.observer?.ok) {
+            await followObserver(io, output.observer, server, output.liveRequested
+                ? {
+                    onStop: async () => {
+                        await liveRefresh?.stop();
+                        const cleanup = await cleanupOssMetaLabSandboxes(output);
+                        return [
+                            `E2B sandbox cleanup killed ${cleanup.killed}, skipped ${cleanup.skipped}.`,
+                            ...cleanup.errors.map((error) => `E2B sandbox cleanup error: ${error}`)
+                        ];
+                    }
+                }
+                : {});
         }
     });
     lab
-        .command("oss-smoke")
+        .command("oss-smoke", { hidden: true })
         .description("Clone lightweight public OSS repos, try Mimetic setup/proof, then discard clones.")
         .option("--repos <owner/repo,...>", "Comma-separated public GitHub repo slugs.")
         .option("--repo <owner/repo>", "Public GitHub repo slug. Repeatable.", collectRepeated, [])
@@ -628,7 +870,7 @@ function registerLabCommands(parent, io) {
         "",
         "Examples:",
         "  mimetic lab oss-smoke",
-        "  mimetic lab oss-smoke --repos developit/mitt,lukeed/clsx",
+        "  mimetic lab oss-smoke --repos CorentinTh/it-tools,drawdb-io/drawdb",
         "  mimetic lab oss-smoke --limit 1 --keep --json",
         "",
         "Safety:",
@@ -652,6 +894,297 @@ async function runOssSmokeAction(args) {
     writeResult(args.command, args.io, result, formatOssLabHuman);
     args.io.setExitCode(result.ok ? 0 : 2);
 }
+async function runLabCommand(args) {
+    const resolved = await resolveLabManifest(args.options.cwd, args.lab);
+    if (!resolved.ok) {
+        writeResult(args.command, args.io, resolved, formatLabResolveFailureHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    switch (resolved.manifest.kind) {
+        case "synthetic":
+            await runSyntheticLabCommand({ ...args, manifest: resolved.manifest });
+            return;
+        case "oss-meta":
+            await runOssMetaLabCommand({ ...args, manifest: resolved.manifest });
+            return;
+        case "oss-smoke":
+            await runOssSmokeLabCommand({ ...args, manifest: resolved.manifest });
+            return;
+    }
+}
+async function runSyntheticLabCommand(args) {
+    const simCount = parseLabCount(args.options.sims, args.manifest.sims ?? args.manifest.count ?? 4);
+    if (simCount === null) {
+        const result = {
+            schema: "mimetic.run-result.v1",
+            ok: false,
+            cwd: args.options.cwd,
+            warnings: [],
+            error: {
+                code: "MIMETIC_INVALID_SIM_COUNT",
+                message: "--sims must be a positive integer."
+            }
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    const runResult = await runDryRun({
+        cwd: args.options.cwd,
+        dryRun: args.options.dryRun ?? args.manifest.defaults?.dryRun ?? true,
+        simCount,
+        ...(args.options.runId === undefined ? {} : { runId: args.options.runId })
+    });
+    if (args.mode === "run") {
+        writeResult(args.command, args.io, runResult, formatRunHuman);
+        args.io.setExitCode(runResult.ok ? 0 : 2);
+        return;
+    }
+    if (!runResult.ok || !runResult.runId) {
+        writeResult(args.command, args.io, runResult, formatRunHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    const openOverride = args.options.open ?? args.manifest.defaults?.open;
+    await renderAndMaybeFollowObserver({
+        command: args.command,
+        cwd: args.options.cwd,
+        io: args.io,
+        port: args.options.port ?? "0",
+        runInput: runResult.runId,
+        ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+        ...(openOverride === undefined ? {} : { open: openOverride })
+    });
+}
+async function runOssSmokeLabCommand(args) {
+    const limit = parseLabCount(args.options.limit ?? args.options.sims, args.manifest.limit ?? args.manifest.count ?? args.manifest.repos?.length ?? DEFAULT_OSS_REPOS.length);
+    if (limit === null) {
+        const result = {
+            schema: "mimetic.oss-lab-result.v1",
+            ok: false,
+            cleanup: { kept: Boolean(args.options.keep), sandboxRemoved: false },
+            completedAt: new Date().toISOString(),
+            cwd: args.options.cwd,
+            error: {
+                code: "MIMETIC_INVALID_OSS_LIMIT",
+                message: "--limit must be a positive integer."
+            },
+            repos: [],
+            runId: args.options.runId ?? "not-created",
+            sandboxPath: ".mimetic/tmp/oss-lab/not-created",
+            startedAt: new Date().toISOString(),
+            warnings: []
+        };
+        writeResult(args.command, args.io, result, formatOssLabHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    const result = await runOssLab({
+        cwd: args.options.cwd,
+        limit,
+        repos: labRepos(args.options, args.manifest),
+        ...(args.options.keep === undefined ? {} : { keep: args.options.keep }),
+        ...(args.options.runId === undefined ? {} : { runId: args.options.runId })
+    });
+    writeResult(args.command, args.io, result, formatOssLabHuman);
+    args.io.setExitCode(result.ok ? 0 : 2);
+}
+async function runOssMetaLabCommand(args) {
+    const count = parseLabCount(args.options.count ?? args.options.sims, args.manifest.count ?? args.manifest.sims ?? args.manifest.repos?.length ?? DEFAULT_OSS_REPOS.length);
+    const port = parseObserverPort(args.options.port ?? "0");
+    if (port === null) {
+        const result = {
+            schema: "mimetic.oss-meta-lab-result.v1",
+            ok: false,
+            assignments: [],
+            cwd: args.options.cwd,
+            dryRun: args.options.dryRun === true,
+            error: {
+                code: "MIMETIC_META_RUN_FAILED",
+                message: "--port must be an integer between 0 and 65535."
+            },
+            liveRequested: args.options.dryRun !== true,
+            repos: labRepos(args.options, args.manifest),
+            sandboxes: [],
+            warnings: []
+        };
+        writeResult(args.command, args.io, result, formatOssMetaLabHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    const wantsMachine = wantsJson(args.command);
+    const dryRun = args.options.dryRun ?? args.manifest.defaults?.dryRun;
+    const shouldOpen = args.options.open === false
+        ? false
+        : wantsMachine
+            ? args.options.open === true
+            : args.options.open ?? args.manifest.defaults?.open ?? args.mode === "watch";
+    const wantsFollow = args.mode === "watch" && !wantsMachine && args.options.detach !== true && dryRun !== true;
+    const repoOverrideRequested = (args.options.repo?.length ?? 0) > 0 || args.options.repos !== undefined;
+    const defaultRedactRepos = repoOverrideRequested ? true : args.manifest.defaults?.redactRepos;
+    const redactRepoNames = args.options.redactRepos ?? defaultRedactRepos;
+    let server = null;
+    let liveRefresh = null;
+    let result;
+    try {
+        result = await runOssMetaLab({
+            ...(wantsFollow ? { completionTimeoutMs: 0 } : {}),
+            cwd: args.options.cwd,
+            ...(wantsFollow
+                ? {
+                    onObserverReady: async (observer) => {
+                        if (!server) {
+                            server = await serveObserver(observer, { open: shouldOpen, port });
+                        }
+                    }
+                }
+                : {}),
+            open: wantsFollow ? false : shouldOpen,
+            ...(dryRun === undefined ? {} : { dryRun }),
+            ...(redactRepoNames === undefined ? {} : { redactRepoNames }),
+            repos: labRepos(args.options, args.manifest),
+            ...(count === null ? { count: Number.NaN } : { count }),
+            ...(args.options.runId === undefined ? {} : { runId: args.options.runId })
+        });
+    }
+    catch (error) {
+        const earlyServer = server;
+        await earlyServer?.close().catch((cleanupError) => {
+            args.io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+        });
+        server = null;
+        throw error;
+    }
+    let output = result;
+    if (server && shouldServeOssMetaLabObserver(result, { wantsFollow: true })) {
+        liveRefresh = startOssMetaLabLiveRefresh(result);
+        output = withOssMetaLabServer(result, server);
+    }
+    else if (shouldServeOssMetaLabObserver(result, { wantsFollow })) {
+        server = await serveObserver(result.observer, { open: shouldOpen, port });
+        liveRefresh = startOssMetaLabLiveRefresh(result);
+        output = withOssMetaLabServer(result, server);
+    }
+    else {
+        const earlyServer = server;
+        await earlyServer?.close().catch((error) => {
+            args.io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        });
+        server = null;
+    }
+    const exitCode = exitCodeForOssMetaLab(output);
+    writeResult(args.command, args.io, output, formatOssMetaLabHuman);
+    args.io.setExitCode(exitCode);
+    if (shouldForceExitAfterOssMetaLab(output, { detach: args.options.detach === true, wantsMachine })) {
+        setTimeout(() => process.exit(exitCode), 50);
+    }
+    if (server && output.observer?.ok) {
+        await followObserver(args.io, output.observer, server, output.liveRequested
+            ? {
+                onStop: async () => {
+                    await liveRefresh?.stop();
+                    const cleanup = await cleanupOssMetaLabSandboxes(output);
+                    return [
+                        `E2B sandbox cleanup killed ${cleanup.killed}, skipped ${cleanup.skipped}.`,
+                        ...cleanup.errors.map((error) => `E2B sandbox cleanup error: ${error}`)
+                    ];
+                }
+            }
+            : {});
+    }
+}
+async function renderAndMaybeFollowObserver(args) {
+    const port = parseObserverPort(args.port);
+    if (port === null) {
+        const result = {
+            schema: "mimetic.run-result.v1",
+            ok: false,
+            cwd: args.cwd,
+            warnings: [],
+            error: {
+                code: "MIMETIC_INVALID_PORT",
+                message: "--port must be an integer between 0 and 65535."
+            }
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    const wantsMachine = wantsJson(args.command);
+    const shouldOpen = args.open === false ? false : wantsMachine ? args.open === true : true;
+    const wantsFollow = !wantsMachine && args.detach !== true;
+    const rendered = await renderObserver(args.cwd, args.runInput, { open: wantsFollow ? false : shouldOpen });
+    let server = null;
+    let result = rendered;
+    if (rendered.ok && wantsFollow) {
+        server = await serveObserver(rendered, { open: shouldOpen, port });
+        result = withObserverServer(rendered, server);
+    }
+    writeResult(args.command, args.io, result, formatObserverHuman);
+    args.io.setExitCode(result.ok ? 0 : 2);
+    if (result.ok && server) {
+        await followObserver(args.io, result, server);
+    }
+}
+async function applyEnvFileOption(args) {
+    if (!args.envFile) {
+        return true;
+    }
+    const result = await loadEnvFile(args.cwd, args.envFile);
+    if (result.ok) {
+        return true;
+    }
+    writeResult(args.command, args.io, result, formatEnvFileHuman);
+    args.io.setExitCode(2);
+    return false;
+}
+function labRepos(options, manifest) {
+    return [
+        ...(options.repo ?? []),
+        ...(options.repos ? [options.repos] : []),
+        ...(options.repo?.length || options.repos ? [] : manifest.repos ?? [])
+    ];
+}
+function parseLabCount(value, fallback) {
+    return value === undefined ? fallback : parsePositiveInteger(value);
+}
+function withObserverServer(rendered, server) {
+    return {
+        ...rendered,
+        observerUrl: server.url,
+        serverUrl: server.url,
+        opened: server.opened,
+        ...(server.openCommand ? { openCommand: server.openCommand } : {}),
+        warnings: [
+            ...rendered.warnings,
+            "Live observer server is polling observer-data.json with no-store caching.",
+            ...(server.warning ? [server.warning] : [])
+        ]
+    };
+}
+function withOssMetaLabServer(result, server) {
+    return {
+        ...result,
+        observer: {
+            ...result.observer,
+            observerUrl: server.url,
+            serverUrl: server.url,
+            opened: server.opened,
+            ...(server.openCommand ? { openCommand: server.openCommand } : {}),
+            warnings: [
+                ...result.observer.warnings,
+                "Live OSS meta-lab server is polling observer-data.json with no-store caching.",
+                ...(server.warning ? [server.warning] : [])
+            ]
+        },
+        warnings: [
+            ...result.warnings,
+            "Live OSS meta-lab server is polling observer-data.json with no-store caching.",
+            ...(server.warning ? [server.warning] : [])
+        ]
+    };
+}
 function writeResult(command, io, result, formatHuman) {
     if (wantsJson(command)) {
         io.writeOut(`${JSON.stringify(result, null, 2)}\n`);
@@ -710,12 +1243,62 @@ function formatObserverHuman(result) {
         ...result.warnings.map((warning) => `warning: ${warning}`)
     ].join("\n") + "\n";
 }
+function formatEnvFileHuman(result) {
+    if (!result.ok) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    return [
+        "mimetic env-file loaded",
+        `env-file: ${result.envFile}`,
+        `loaded: ${result.loaded.length ? result.loaded.join(", ") : "none"}`,
+        `skipped-existing: ${result.skipped.length ? result.skipped.join(", ") : "none"}`
+    ].join("\n") + "\n";
+}
+function formatLabListHuman(result) {
+    if (result.labs.length === 0) {
+        return [
+            `No Mimetic labs found in ${result.cwd}`,
+            "Create one under mimetic/labs/*.yaml, .mimetic/labs/*.yaml, or pass a .yaml path.",
+            ...result.warnings.map((warning) => `warning: ${warning}`)
+        ].join("\n") + "\n";
+    }
+    return [
+        "mimetic labs",
+        ...result.labs.map((lab) => `- ${lab.id} ${lab.kind} ${lab.origin} ${lab.path}${lab.title ? ` (${lab.title})` : ""}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`)
+    ].join("\n") + "\n";
+}
+function formatLabInspectHuman(result) {
+    if (!result.ok || !result.manifest) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    return [
+        "mimetic lab",
+        `id: ${result.manifest.id}`,
+        `kind: ${result.manifest.kind}`,
+        ...(result.manifest.title ? [`title: ${result.manifest.title}`] : []),
+        ...(result.manifest.description ? [`description: ${result.manifest.description}`] : []),
+        ...(result.path ? [`path: ${result.path}`] : []),
+        ...(result.origin ? [`origin: ${result.origin}`] : []),
+        ...(result.manifest.sims === undefined ? [] : [`sims: ${result.manifest.sims}`]),
+        ...(result.manifest.count === undefined ? [] : [`count: ${result.manifest.count}`]),
+        ...(result.manifest.limit === undefined ? [] : [`limit: ${result.manifest.limit}`]),
+        ...(result.manifest.repos?.length ? [`repos: ${result.manifest.repos.join(", ")}`] : []),
+        ...result.warnings.map((warning) => `warning: ${warning}`)
+    ].join("\n") + "\n";
+}
+function formatLabResolveFailureHuman(result) {
+    return [
+        `${result.error.code}: ${result.error.message}`,
+        ...result.warnings.map((warning) => `warning: ${warning}`)
+    ].join("\n") + "\n";
+}
 function parsePositiveInteger(value) {
     if (!/^\d+$/.test(value)) {
         return null;
     }
     const parsed = Number.parseInt(value, 10);
-    return parsed >= 1 && parsed <= 64 ? parsed : null;
+    return Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : null;
 }
 function parseTimeoutMs(value) {
     if (!/^\d+$/.test(value)) {
@@ -731,19 +1314,32 @@ function parseObserverPort(value) {
     const parsed = Number.parseInt(value, 10);
     return parsed >= 0 && parsed <= 65535 ? parsed : null;
 }
-async function followObserver(io, result, server) {
+async function followObserver(io, result, server, options = {}) {
     io.writeOut(`watching: ${result.serverUrl ?? result.observerUrl ?? result.observerPath}\n`);
     io.writeOut("watching: press Ctrl-C to stop\n");
     await new Promise((resolve) => {
         process.once("SIGINT", () => {
-            server.close()
-                .catch((error) => {
-                io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
-            })
-                .finally(() => {
+            (async () => {
+                try {
+                    await server.close();
+                }
+                catch (error) {
+                    io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+                }
+                if (options.onStop) {
+                    try {
+                        const messages = await options.onStop();
+                        for (const message of messages) {
+                            io.writeOut(`watch cleanup: ${message}\n`);
+                        }
+                    }
+                    catch (error) {
+                        io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+                    }
+                }
                 io.writeOut("watch stopped\n");
                 resolve();
-            });
+            })();
         });
     });
 }
@@ -775,11 +1371,9 @@ function formatOssLabHuman(result) {
     ].join("\n") + "\n";
 }
 function formatOssMetaLabHuman(result) {
-    if (!result.ok && result.error) {
-        return `${result.error.code}: ${result.error.message}\n`;
-    }
     return [
-        `mimetic lab oss ${result.dryRun ? "dry-run" : "watch"}`,
+        `mimetic lab oss ${result.ok ? (result.dryRun ? "dry-run" : "watch") : "failed"}`,
+        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
         `run: ${result.runId ?? "not-created"}`,
         `repos: ${result.repos.join(", ")}`,
         ...(result.count === undefined ? [] : [`desktops: ${result.count}`]),
@@ -876,6 +1470,10 @@ export function shouldForceExitAfterOssMetaLab(output, options) {
         && (options.detach || options.wantsMachine)
         && output.sandboxes.some((sandbox) => sandbox.urlPresent);
 }
+export function shouldServeOssMetaLabObserver(output, options) {
+    return options.wantsFollow
+        && output.observer?.ok === true;
+}
 export function exitCodeForOssMetaLab(output) {
     return output.ok ? 0 : 2;
 }