unfold-deploy 0.0.0-stage → 0.2.0

package/demos/vercel-success.json

@@ -0,0 +1,343 @@
+{
+ "provider": "vercel",
+ "description": "A preview deploy of a small Next.js app that succeeds.",
+ "command": [
+  "vercel",
+  "deploy",
+  "--logs"
+ ],
+ "cwd": "~/projects/acme-web",
+ "exitCode": 0,
+ "signal": null,
+ "interrupted": false,
+ "chunks": [
+  {
+   "t": 0,
+   "d": "Vercel CLI 65.2.0\r\n"
+  },
+  {
+   "t": 300,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠋\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 380,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠙\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 460,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠹\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 540,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠸\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 620,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠼\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 700,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠴\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 780,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠦\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 860,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠧\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 940,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠇\u001b[39m Retrieving project…"
+  },
+  {
+   "t": 1020,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠋\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1100,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠙\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1180,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠹\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1260,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠸\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1340,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠼\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1420,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠴\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1500,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠦\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1580,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠧\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1660,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠇\u001b[39m Deploying \u001b[1macme/acme-web\u001b[22m"
+  },
+  {
+   "t": 1780,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠋\u001b[39m Uploading \u001b[0m[--------------------] (0.0KB/184.6KB)"
+  },
+  {
+   "t": 2040,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠙\u001b[39m Uploading \u001b[0m[==------------------] (23.1KB/184.6KB)"
+  },
+  {
+   "t": 2300,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠹\u001b[39m Uploading \u001b[0m[=====---------------] (46.1KB/184.6KB)"
+  },
+  {
+   "t": 2560,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠸\u001b[39m Uploading \u001b[0m[=======-------------] (69.2KB/184.6KB)"
+  },
+  {
+   "t": 2820,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠼\u001b[39m Uploading \u001b[0m[==========----------] (92.3KB/184.6KB)"
+  },
+  {
+   "t": 3080,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠴\u001b[39m Uploading \u001b[0m[============--------] (115.4KB/184.6KB)"
+  },
+  {
+   "t": 3340,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠦\u001b[39m Uploading \u001b[0m[===============-----] (138.4KB/184.6KB)"
+  },
+  {
+   "t": 3600,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠧\u001b[39m Uploading \u001b[0m[=================---] (161.5KB/184.6KB)"
+  },
+  {
+   "t": 3860,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠇\u001b[39m Uploading \u001b[0m[====================] (184.6KB/184.6KB)"
+  },
+  {
+   "t": 4160,
+   "d": "\u001b[2K\u001b[1G"
+  },
+  {
+   "t": 4160,
+   "d": "  \u001b[1mInspect         \u001b[22m\u001b[1m\u001b[36mhttps://vercel.com/acme/acme-web/6TfY2pQkzR1mWcN8xLbV3hGd\u001b[39m\u001b[22m\r\n"
+  },
+  {
+   "t": 4180,
+   "d": "  \u001b[1mPreview         \u001b[22m\u001b[1m\u001b[36mhttps://acme-web-7k2m9xq4p-acme.vercel.app\u001b[39m\u001b[22m\r\n"
+  },
+  {
+   "t": 4300,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠋\u001b[39m Queued…"
+  },
+  {
+   "t": 4380,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠙\u001b[39m Queued…"
+  },
+  {
+   "t": 4460,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠹\u001b[39m Queued…"
+  },
+  {
+   "t": 4540,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠸\u001b[39m Queued…"
+  },
+  {
+   "t": 4620,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠼\u001b[39m Queued…"
+  },
+  {
+   "t": 4700,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠴\u001b[39m Queued…"
+  },
+  {
+   "t": 4780,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠦\u001b[39m Queued…"
+  },
+  {
+   "t": 4860,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠧\u001b[39m Queued…"
+  },
+  {
+   "t": 4940,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠇\u001b[39m Queued…"
+  },
+  {
+   "t": 5020,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠏\u001b[39m Queued…"
+  },
+  {
+   "t": 5100,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠋\u001b[39m Queued…"
+  },
+  {
+   "t": 5180,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠙\u001b[39m Queued…"
+  },
+  {
+   "t": 5260,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠹\u001b[39m Queued…"
+  },
+  {
+   "t": 5340,
+   "d": "\u001b[2K\u001b[1G\u001b[36m⠸\u001b[39m Queued…"
+  },
+  {
+   "t": 5340,
+   "d": "\u001b[2K\u001b[1G"
+  },
+  {
+   "t": 5540,
+   "d": "\u001b[2m2026-11-05T18:04:03.460Z\u001b[22m  Running build in Washington, D.C., USA (East) – iad1\r\n"
+  },
+  {
+   "t": 5680,
+   "d": "\u001b[2m2026-11-05T18:04:04.482Z\u001b[22m  Build machine configuration: 2 cores, 8 GB\r\n"
+  },
+  {
+   "t": 5820,
+   "d": "\u001b[2m2026-11-05T18:04:05.504Z\u001b[22m  Retrieving list of deployment files...\r\n"
+  },
+  {
+   "t": 6120,
+   "d": "\u001b[2m2026-11-05T18:04:07.694Z\u001b[22m  Downloading 41 deployment files...\r\n"
+  },
+  {
+   "t": 6620,
+   "d": "\u001b[2m2026-11-05T18:04:11.344Z\u001b[22m  Restored build cache from previous deployment (9QwErTy2uIoPaSdF)\r\n"
+  },
+  {
+   "t": 6820,
+   "d": "\u001b[2m2026-11-05T18:04:12.804Z\u001b[22m  Running \"vercel build\"\r\n"
+  },
+  {
+   "t": 7120,
+   "d": "\u001b[2m2026-11-05T18:04:14.994Z\u001b[22m  Vercel CLI 65.2.0\r\n"
+  },
+  {
+   "t": 7320,
+   "d": "\u001b[2m2026-11-05T18:04:16.454Z\u001b[22m  Installing dependencies...\r\n"
+  },
+  {
+   "t": 8920,
+   "d": "\u001b[2m2026-11-05T18:04:28.134Z\u001b[22m  added 3 packages, and audited 318 packages in 3s\r\n"
+  },
+  {
+   "t": 9120,
+   "d": "\u001b[2m2026-11-05T18:04:29.594Z\u001b[22m  Detected Next.js version: 16.0.1\r\n"
+  },
+  {
+   "t": 9320,
+   "d": "\u001b[2m2026-11-05T18:04:31.054Z\u001b[22m  Running \"npm run build\"\r\n"
+  },
+  {
+   "t": 9460,
+   "d": "\u001b[2m2026-11-05T18:04:32.076Z\u001b[22m  \r\n"
+  },
+  {
+   "t": 9660,
+   "d": "\u001b[2m2026-11-05T18:04:33.536Z\u001b[22m  > acme-web@0.1.0 build\r\n"
+  },
+  {
+   "t": 9800,
+   "d": "\u001b[2m2026-11-05T18:04:34.558Z\u001b[22m  > next build\r\n"
+  },
+  {
+   "t": 9940,
+   "d": "\u001b[2m2026-11-05T18:04:35.580Z\u001b[22m  \r\n"
+  },
+  {
+   "t": 10340,
+   "d": "\u001b[2m2026-11-05T18:04:38.500Z\u001b[22m     ▲ Next.js 16.0.1\r\n"
+  },
+  {
+   "t": 10540,
+   "d": "\u001b[2m2026-11-05T18:04:39.960Z\u001b[22m     Creating an optimized production build ...\r\n"
+  },
+  {
+   "t": 12940,
+   "d": "\u001b[2m2026-11-05T18:04:57.480Z\u001b[22m   ✓ Compiled successfully in 7.4s\r\n"
+  },
+  {
+   "t": 13140,
+   "d": "\u001b[2m2026-11-05T18:04:58.940Z\u001b[22m     Linting and checking validity of types ...\r\n"
+  },
+  {
+   "t": 14540,
+   "d": "\u001b[2m2026-11-05T18:05:09.160Z\u001b[22m     Collecting page data ...\r\n"
+  },
+  {
+   "t": 15240,
+   "d": "\u001b[2m2026-11-05T18:05:14.270Z\u001b[22m   ✓ Generating static pages (7/7)\r\n"
+  },
+  {
+   "t": 15540,
+   "d": "\u001b[2m2026-11-05T18:05:16.460Z\u001b[22m     Finalizing page optimization ...\r\n"
+  },
+  {
+   "t": 15680,
+   "d": "\u001b[2m2026-11-05T18:05:17.482Z\u001b[22m  \r\n"
+  },
+  {
+   "t": 15880,
+   "d": "\u001b[2m2026-11-05T18:05:18.942Z\u001b[22m  Route (app)                                 Size  First Load JS\r\n"
+  },
+  {
+   "t": 15900,
+   "d": "\u001b[2m2026-11-05T18:05:19.088Z\u001b[22m  ┌ ○ /                                    5.21 kB         112 kB\r\n"
+  },
+  {
+   "t": 15920,
+   "d": "\u001b[2m2026-11-05T18:05:19.234Z\u001b[22m  ├ ○ /_not-found                              0 B         106 kB\r\n"
+  },
+  {
+   "t": 15940,
+   "d": "\u001b[2m2026-11-05T18:05:19.380Z\u001b[22m  └ ○ /checkout                            3.14 kB         110 kB\r\n"
+  },
+  {
+   "t": 15960,
+   "d": "\u001b[2m2026-11-05T18:05:19.526Z\u001b[22m  ○  (Static)  prerendered as static content\r\n"
+  },
+  {
+   "t": 16460,
+   "d": "\u001b[2m2026-11-05T18:05:23.176Z\u001b[22m  Build Completed in /vercel/output [24s]\r\n"
+  },
+  {
+   "t": 16760,
+   "d": "\u001b[2m2026-11-05T18:05:25.366Z\u001b[22m  Deploying outputs...\r\n"
+  },
+  {
+   "t": 18460,
+   "d": "\u001b[2m2026-11-05T18:05:37.776Z\u001b[22m  Deployment completed\r\n"
+  },
+  {
+   "t": 18660,
+   "d": "\u001b[2m2026-11-05T18:05:39.236Z\u001b[22m  Creating build cache...\r\n"
+  },
+  {
+   "t": 19560,
+   "d": "\u001b[2m2026-11-05T18:05:45.806Z\u001b[22m  Created build cache: 3.212s\r\n"
+  },
+  {
+   "t": 19660,
+   "d": "\u001b[2m2026-11-05T18:05:46.536Z\u001b[22m  Uploading build cache [41.2 MB]...\r\n"
+  },
+  {
+   "t": 20260,
+   "d": "\r\n\u001b[32m✓\u001b[39m \u001b[1mReady\u001b[22m \u001b[2min 31s\u001b[22m\r\n\r\n"
+  },
+  {
+   "t": 20300,
+   "d": "\r\n\u001b[33m!\u001b[39m Deployment Protection is on for this project (Vercel Authentication). Use \u001b[36m`vercel curl`\u001b[39m to access it.\r\n"
+  }
+ ]
+}

package/dist/cli.js

@@ -0,0 +1,121 @@
+import { readFileSync } from 'node:fs';
+import { runDemo, DEMO_LIST } from './commands/demo.js';
+import { DEFAULT_FLAGS } from './commands/observe.js';
+import { listRuns, runReplay } from './commands/replay.js';
+import { runLive } from './commands/run.js';
+import { runShow } from './commands/show.js';
+import { UsageError } from './core/errors.js';
+import { providers } from './providers/index.js';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const HELP = `unfold — Watch what happens after you hit Enter.
+
+Usage
+  unfold vercel [vercel deploy flags]   Vercel preview deploy:  Prepare → Upload → Build → Preview
+  unfold gcloud [gcloud run deploy flags]
+                                         Cloud Run deploy:       Prepare → Build → Deploy → Live
+  unfold claude "<task>" [claude flags]  Claude Code task:       Start → Explore → Change → Verify → Done
+  unfold codex "<task>" [codex flags]    Codex task:             Start → Explore → Change → Verify → Done
+  unfold show [run]                      Explore a run in the terminal (defaults to the latest)
+  unfold demo [provider] <name>          Play a recorded demo, no account needed:
+                                         ${DEMO_LIST}
+  unfold replay [run]                    Play a saved run again
+  unfold runs                            List saved runs
+
+Unfold options (anywhere on the line)
+  --fix <agent>  If the run fails, start "claude" or "codex" with the fix prompt
+                 (a fix prompt is always saved on failure; this only launches the agent)
+  --web          Also show the flow in a local browser page (off by default)
+  --no-open      With --web: don't open the browser automatically
+  --once         With --web: exit when the run ends instead of keeping the page served
+  --port <n>     With --web: port for the page (default 4317)
+  --no-panel     Don't pin the live flow panel to the bottom of the terminal
+  --speed <n>    Playback speed for demo/replay (default 1)
+
+Examples
+  unfold vercel
+  unfold vercel --fix claude
+  unfold gcloud --source . --region us-central1
+  unfold claude "fix the failing test" --allowedTools Read Edit Bash
+  unfold codex "add a --json flag to the CLI" --sandbox workspace-write
+  unfold show
+  unfold demo build-failure
+  unfold demo claude success
+`;
+export { UsageError };
+/** Pulls Unfold's own flags out of argv; everything else goes to the wrapped CLI. */
+export function parseArgs(argv) {
+    const rest = [];
+    const flags = { ...DEFAULT_FLAGS };
+    let speed = 1;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--web')
+            flags.web = true;
+        else if (a === '--no-open')
+            flags.open = false;
+        else if (a === '--once')
+            flags.once = true;
+        else if (a === '--no-panel')
+            flags.panel = false;
+        else if (a === '--port')
+            flags.port = Number(argv[++i]);
+        else if (a.startsWith('--port='))
+            flags.port = Number(a.slice(7));
+        else if (a === '--fix' || a.startsWith('--fix=')) {
+            const v = a === '--fix' ? argv[++i] : a.slice(6);
+            if (v !== 'claude' && v !== 'codex')
+                throw new UsageError(`--fix expects "claude" or "codex", got "${v ?? ''}"`);
+            flags.fix = v;
+        }
+        else if (a === '--speed')
+            speed = Number(argv[++i]) || 1;
+        else if (a.startsWith('--speed='))
+            speed = Number(a.slice(8)) || 1;
+        else
+            rest.push(a);
+    }
+    return { rest, flags, speed };
+}
+export async function main(argv) {
+    try {
+        return await run(argv);
+    }
+    catch (err) {
+        if (!(err instanceof UsageError))
+            throw err;
+        process.stderr.write(`unfold: ${err.message}\nRun \`unfold --help\` for usage.\n`);
+        return 2;
+    }
+}
+async function run(argv) {
+    const [cmd, ...tail] = argv;
+    if (cmd === '-v' || cmd === '--version' || cmd === 'version') {
+        process.stdout.write(VERSION + '\n');
+        return 0;
+    }
+    if (!cmd || cmd === '-h' || cmd === '--help' || cmd === 'help') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const provider = providers[cmd];
+    if (provider) {
+        // Only strip Unfold flags; the wrapped CLI receives everything else verbatim.
+        const { rest, flags } = parseArgs(tail);
+        return runLive(provider, rest, flags);
+    }
+    const { rest, flags, speed } = parseArgs(tail);
+    switch (cmd) {
+        case 'show':
+            return runShow(rest[0], flags);
+        case 'demo':
+            return runDemo(rest, flags, speed);
+        case 'replay':
+            return runReplay(rest[0], flags, speed);
+        case 'runs':
+            for (const r of listRuns())
+                process.stdout.write(r + '\n');
+            return 0;
+        default:
+            throw new UsageError(`unknown command "${cmd}". Supported: ${[...Object.keys(providers), 'show', 'demo', 'replay', 'runs'].join(', ')}.`);
+    }
+}

package/dist/commands/demo.js

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { providers } from '../providers/index.js';
+import { observe, say } from './observe.js';
+export const DEMOS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'demos');
+/** Demos per provider; the first provider's demos also work without naming it. */
+export const DEMOS = {
+    vercel: ['success', 'build-failure', 'interrupted'],
+    gcloud: ['success', 'deploy-failure'],
+    claude: ['success'],
+    codex: ['checks-failing'],
+};
+export const DEMO_LIST = Object.entries(DEMOS)
+    .flatMap(([p, names]) => names.map((n) => `${p} ${n}`))
+    .join(', ');
+/** Loads `vercel-success.json` from `loadDemo('success')` or `loadDemo('gcloud', 'success')`. */
+export function loadDemo(providerOrName, name) {
+    const file = name ? `${providerOrName}-${name}` : `vercel-${providerOrName}`;
+    return JSON.parse(readFileSync(join(DEMOS_DIR, `${file}.json`), 'utf8'));
+}
+export async function runDemo(args, flags, speed) {
+    const [first = 'success', second] = args;
+    const providerId = DEMOS[first] ? first : 'vercel';
+    const name = DEMOS[first] ? (second ?? DEMOS[first][0]) : first;
+    if (!DEMOS[providerId].includes(name)) {
+        say(`Unknown demo "${args.join(' ')}". Try one of: ${DEMO_LIST}`);
+        return 2;
+    }
+    const t = loadDemo(providerId, name);
+    const provider = providers[t.provider];
+    say(`Demo: ${t.description} Recorded output; no account or network needed.`);
+    return observe({
+        provider,
+        command: t.command,
+        cwd: t.cwd,
+        mode: 'demo',
+        flags,
+        save: true,
+        waitForBrowser: true,
+        run: (session, term) => play(t, session, speed, term),
+    });
+}
+/** Plays a transcript to the terminal and the session. Ctrl+C stops playback. */
+export function play(t, session, speed, term) {
+    const write = (d) => (term ? term.write(d) : process.stdout.write(d));
+    return new Promise((resolve) => {
+        let i = 0;
+        let timer;
+        const start = Date.now();
+        const onSigint = () => {
+            if (timer)
+                clearTimeout(timer);
+            process.off('SIGINT', onSigint);
+            write('^C\r\n');
+            session.write('^C\r\n');
+            resolve({ exitCode: 130, signal: null, interrupted: true });
+        };
+        process.on('SIGINT', onSigint);
+        const step = () => {
+            while (i < t.chunks.length && t.chunks[i].t / speed <= Date.now() - start) {
+                const { d } = t.chunks[i++];
+                write(d);
+                session.write(d);
+            }
+            if (i >= t.chunks.length) {
+                process.off('SIGINT', onSigint);
+                resolve({ exitCode: t.exitCode, signal: t.signal, interrupted: t.interrupted });
+                return;
+            }
+            timer = setTimeout(step, Math.max(0, t.chunks[i].t / speed - (Date.now() - start)));
+        };
+        step();
+    });
+}

package/dist/commands/observe.js

@@ -0,0 +1,137 @@
+import { spawn } from 'node:child_process';
+import { terminalMode, which } from '../core/launch.js';
+import { Redactor } from '../core/redact.js';
+import { startServer } from '../core/server.js';
+import { Session } from '../core/session.js';
+import { RunRecorder, saveFixPrompt } from '../core/store.js';
+import { style } from '../tui/ansi.js';
+import { LivePanel, panelSupported } from '../tui/panel.js';
+import { summary } from '../tui/render.js';
+export const DEFAULT_FLAGS = { web: false, open: true, once: false, panel: true };
+const err = style(!!process.stderr.isTTY && !process.env.NO_COLOR);
+export const say = (msg) => process.stderr.write(`${err.dim('[unfold]')} ${msg}\n`);
+export async function observe(opts) {
+    const session = new Session({
+        provider: opts.provider,
+        command: opts.command,
+        cwd: opts.cwd,
+        mode: opts.mode,
+        // Secret-looking env values are matched in memory only; the environment is never saved.
+        redactor: new Redactor({ env: opts.mode === 'live' ? process.env : {} }),
+        // Only real runs write files; replays and `show --web` reuse what's saved.
+        saveFixPrompt: opts.save ? saveFixPrompt : undefined,
+    });
+    let recorder;
+    if (opts.save) {
+        recorder = new RunRecorder(session.runId);
+        session.subscribe((event) => recorder.write(event));
+    }
+    session.start();
+    if (recorder)
+        session.state.savedTo = recorder.path;
+    let server;
+    if (opts.flags.web) {
+        server = await startServer(session, opts.flags.port);
+        say(`Flow view in your browser: ${server.url}`);
+        if (opts.flags.open)
+            openBrowser(server.url);
+        if (opts.waitForBrowser && opts.flags.open)
+            await server.waitForClient(6000);
+    }
+    // The live flow panel, pinned below the command's own output.
+    const rowsListeners = new Set();
+    const panel = 
+    // The panel needs to control the child's terminal size, which only node-pty allows.
+    opts.flags.panel && panelSupported() && (opts.mode !== 'live' || terminalMode() === 'pty')
+        ? new LivePanel({ title: [opts.command[0].split('/').pop(), ...opts.command.slice(1)].join(' '), onRowsChange: (r) => rowsListeners.forEach((fn) => fn(r)) })
+        : undefined;
+    if (panel) {
+        panel.update(session.state);
+        session.subscribe((_e, state) => panel.update(state));
+        panel.start();
+    }
+    const show = (chunk) => {
+        process.stdout.write(chunk);
+        panel?.afterChildOutput(chunk);
+    };
+    // Structured CLIs (JSON events) are shown as readable lines, not raw output.
+    const formatted = !!opts.provider.createPresenter;
+    if (formatted) {
+        let shown = 0;
+        session.subscribe((e) => {
+            if (e.type !== 'log' || e.line.seq <= shown)
+                return;
+            shown = e.line.seq;
+            show(e.line.text.replace(/\r?\n/g, '\r\n') + '\r\n');
+        });
+    }
+    const term = {
+        write(chunk) {
+            if (!formatted)
+                show(chunk);
+        },
+        rows: () => panel?.childRows ?? (process.stdout.rows || 30),
+        onRowsChange: (fn) => rowsListeners.add(fn),
+    };
+    let exit;
+    try {
+        exit = await opts.run(session, term);
+    }
+    finally {
+        panel?.stop();
+    }
+    session.end(exit.exitCode, exit.signal, exit.interrupted);
+    process.stderr.write(summary(session.state, session.logs, { cols: process.stderr.columns, s: err, webUrl: server?.url }));
+    if (session.state.fix && opts.flags.fix)
+        await startAgent(opts.flags.fix, session.state.fix.prompt, opts);
+    if (server) {
+        if (opts.flags.once) {
+            await new Promise((r) => setTimeout(r, 300));
+        }
+        else {
+            say(err.dim('Still serving the browser view. Press Ctrl+C to exit.'));
+            await new Promise((resolve) => {
+                process.stdin.pause();
+                process.once('SIGINT', () => resolve());
+                process.once('SIGTERM', () => resolve());
+            });
+        }
+        await server.close();
+    }
+    return exit.exitCode ?? (session.state.outcome === 'interrupted' ? 130 : 1);
+}
+/** Hands the terminal to a coding agent, started with the fix prompt, in the project folder. */
+async function startAgent(agent, prompt, opts) {
+    if (opts.mode === 'demo') {
+        say(`--fix is ignored for demos: the demo project isn't on your machine. Use the command above in a real project.`);
+        return;
+    }
+    const bin = which(agent);
+    if (!bin) {
+        say(`Could not find "${agent}" on your PATH, so it wasn't started. The prompt is saved above.`);
+        return;
+    }
+    say(`Starting ${agent === 'claude' ? 'Claude Code' : 'Codex'} with the fix prompt in ${opts.cwd}…\n`);
+    await new Promise((resolve) => {
+        const child = spawn(bin, [prompt], { cwd: opts.cwd, stdio: 'inherit' });
+        // Ctrl+C belongs to the agent while it runs.
+        const ignore = () => { };
+        process.on('SIGINT', ignore);
+        child.on('error', (e) => say(`Could not start ${agent}: ${e.message}`));
+        child.on('close', () => {
+            process.off('SIGINT', ignore);
+            resolve();
+        });
+    });
+}
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => say(`Open ${url} in your browser.`));
+        child.unref();
+    }
+    catch {
+        say(`Open ${url} in your browser.`);
+    }
+}