runwork 0.10.2 → 0.10.3

package/dist/commands/dev.js

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { execFileSync } from 'child_process';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
@@ -9,6 +9,11 @@ import { syncWithRemote } from '../git/sync.js';
 import { ensureGitIdentity } from '../git/identity.js';
 import { requireGit } from '../git/preflight.js';
 import { startLogTailer } from '../logs/tailer.js';
+import { startPreviewUrlPoller } from '../dev/preview-url-poller.js';
+import { buildSessionFile, getSessionState, readSessionFile, removeSessionFile, removeSessionFileIfOwned, writeSessionFile, } from '../dev/session.js';
+import { INTERNAL_DETACHED_CHILD_FLAG, isInternalDetachedChild, runAsDetachedParent, stripInternalChildFlag, } from '../dev/detach.js';
+import { stopSession } from '../dev/stop.js';
+import { formatStartedAgo, getAttachLogPaths, getCurrentPreviewUrl, renderLogLine, resolveAttachTarget, startLogTail, startSessionFileWatch, } from '../dev/attach.js';
 import { populateTypes } from '../types-manager.js';
 import { loadManifest, generateManifest, saveManifest, detectUserEdits } from '../template/manifest.js';
 import { extractZip } from '../utils/zip.js';
@@ -16,9 +21,10 @@ import { removeNestedGitDirs } from '../utils/fs.js';
 import { getDevBanner, getKeyboardHints, getInfoPanel } from '../ui/banner.js';
 import { createStatusLine } from '../ui/status-line.js';
 import { createKeyboardListener } from '../ui/keyboard.js';
-import { bold, dim, green, yellow, cyan } from '../ui/colors.js';
+import { bold, dim, green, yellow, cyan, red } from '../ui/colors.js';
 import { shouldOutputJson, jsonLine } from '../utils/output.js';
 import { buildDevSessionGuide } from '../utils/agent-guidance.js';
+import { VERSION } from '../generated/version.js';
 async function populateSkill(projectDir, client, appId) {
     try {
         const { skill } = await client.getAppSkill(appId);
@@ -99,12 +105,61 @@ function commitAndPushRestoredFiles(cwd, files) {
 }
 export async function execDev(options) {
     const useJson = options?.json ?? false;
+    const mode = options?.mode ?? 'foreground';
     requireGit('dev');
     const config = readConfig();
     const creds = requireAuth();
     const client = new ApiClient(creds);
     const cwd = process.cwd();
     const ts = () => new Date().toISOString();
+    // --restart: stop any pre-existing session before starting a new one.
+    // We do this BEFORE the "already running" check so the user's intent
+    // is respected even when a healthy session is already in place.
+    if (options?.restart) {
+        const stopOutcome = await stopSession(cwd, config.appId);
+        if (!useJson && stopOutcome.result === 'stopped') {
+            console.log(dim(`Stopped previous dev session (PID ${stopOutcome.pid}).`));
+        }
+        if (useJson && (stopOutcome.result === 'stopped' || stopOutcome.result === 'stale-cleaned')) {
+            jsonLine({
+                event: 'session_stopped',
+                pid: 'pid' in stopOutcome ? stopOutcome.pid : undefined,
+                timestamp: ts(),
+            });
+        }
+    }
+    // Idempotency check: read the session file before doing any work. If a
+    // live session is already running for this app on this machine, exit
+    // success with a structured event so the caller (human or agent) knows
+    // the URL and can move on. Stale files are cleaned up silently.
+    const existing = getSessionState(cwd, config.appId);
+    if (existing.state === 'alive') {
+        const f = existing.file;
+        if (useJson) {
+            jsonLine({
+                event: 'already_running',
+                previewUrl: f.previewUrl,
+                pid: f.pid,
+                sessionId: f.sessionId,
+                mode: f.mode,
+                timestamp: ts(),
+            });
+        }
+        else {
+            console.log(`Dev session already running (PID ${f.pid}, mode: ${f.mode}).`);
+            console.log(`  Preview: ${green(f.previewUrl || '(starting up)')}`);
+            console.log(dim(`  Follow logs:  runwork dev attach`));
+            console.log(dim(`  Stop:         runwork dev stop`));
+            console.log(dim(`  Start fresh:  runwork dev --restart`));
+        }
+        return;
+    }
+    if (existing.state === 'stale') {
+        removeSessionFile(cwd);
+        if (!useJson) {
+            console.log(dim(`Cleaned up dead session from a previous run (reason: ${existing.reason}).`));
+        }
+    }
     // Seed a local git identity so the very first commit cannot fail on a
     // fresh machine where `git config --global user.email/.name` has never
     // been set (extremely common on Windows after a clean install).
@@ -257,12 +312,30 @@ export async function execDev(options) {
             console.warn(yellow('Push failed. Continuing with current state...'));
         }
     }
+    // The session POST returns a snapshot of the preview URL at boot time.
+    // Sandboxes can rotate that URL mid-session (instance replacement,
+    // tunnel restart), so we treat this as the *initial* value and refresh
+    // it via `getDevStatus` -- the same source `runwork info` reads from.
+    // That keeps `dev` and `info` in agreement.
+    let currentPreviewUrl = session.previewUrl;
+    // Write the session file as soon as we have the URL. This is the
+    // rendezvous moment for `runwork dev --detach` -- the parent is polling
+    // `.runwork/dev-session.json` and exits 0 when this file appears with a
+    // non-empty previewUrl matching the child's PID.
+    writeSessionFile(cwd, buildSessionFile({
+        pid: process.pid,
+        sessionId: session.sessionId,
+        appId: config.appId,
+        previewUrl: currentPreviewUrl,
+        cliVersion: VERSION,
+        mode,
+    }));
     // Emit session_started (JSON) or show banner (human)
     if (useJson) {
-        jsonLine({ event: 'session_started', previewUrl: session.previewUrl, appName: config.appName, timestamp: ts(), guide: buildDevSessionGuide() });
+        jsonLine({ event: 'session_started', previewUrl: currentPreviewUrl, appName: config.appName, timestamp: ts(), guide: buildDevSessionGuide() });
     }
     else {
-        console.log(getDevBanner({ appName: config.appName, previewUrl: session.previewUrl, workspaceName: config.workspaceName }));
+        console.log(getDevBanner({ appName: config.appName, previewUrl: currentPreviewUrl, workspaceName: config.workspaceName }));
         console.log(getKeyboardHints());
         console.log('');
         console.log(dim('  ─────────────────────────────────────────────'));
@@ -277,16 +350,58 @@ export async function execDev(options) {
             return;
         const filterLabel = logFilter === 'all' ? 'All' : logFilter === 'events' ? 'Events' : 'Runtime';
         const sep = '\x1b[90m\u2502\x1b[39m';
-        statusLine.update(`${bold(config.appName)} ${sep} ${green(session.previewUrl)} ${sep} ${cyan(`${syncedCount} synced`)} ${sep} ${filterLabel} ${sep} \x1b[90mo\x1b[39m:open \x1b[90mi\x1b[39m:info \x1b[90ma/e/r\x1b[39m:filter \x1b[90mq\x1b[39m:quit`);
+        statusLine.update(`${bold(config.appName)} ${sep} ${green(currentPreviewUrl)} ${sep} ${cyan(`${syncedCount} synced`)} ${sep} ${filterLabel} ${sep} \x1b[90mo\x1b[39m:open \x1b[90mi\x1b[39m:info \x1b[90ma/e/r\x1b[39m:filter \x1b[90mq\x1b[39m:quit`);
     }
     if (statusLine)
         updateStatus();
+    const previewUrlPoller = startPreviewUrlPoller({
+        client,
+        appId: config.appId,
+        initialUrl: currentPreviewUrl,
+        onChange: (next, prev) => {
+            currentPreviewUrl = next;
+            // Persist the rotated URL into the session file so `runwork info`,
+            // detached parent processes, and other observers see the same
+            // preview URL we're showing in the status line.
+            const current = readSessionFile(cwd);
+            if (current && current.pid === process.pid) {
+                writeSessionFile(cwd, { ...current, previewUrl: next });
+            }
+            if (useJson) {
+                jsonLine({
+                    event: 'preview_url_changed',
+                    previewUrl: next,
+                    previousUrl: prev,
+                    appName: config.appName,
+                    timestamp: ts(),
+                });
+            }
+            else {
+                console.log(dim(`Preview URL changed: ${next}`));
+                updateStatus();
+            }
+        },
+    });
     let logTailer;
     const keyboard = useJson ? null : createKeyboardListener();
     const cleanup = async () => {
+        // Remove the session file FIRST. If a Windows console-close-event
+        // truncates our cleanup window, or if we crash later in this handler,
+        // at least the file is gone -- the next `runwork dev` will see a
+        // clean slate. Stale-detection on next-startup is the primary recovery
+        // path; this is just polish for the graceful-exit case.
+        //
+        // Use the PID-guarded variant: if a startup race ended with another
+        // process owning the session file, we must NOT delete it -- that
+        // would leave the winner's session orphaned.
+        try {
+            removeSessionFileIfOwned(cwd, process.pid);
+        }
+        catch { /* best-effort */ }
         if (!useJson)
             console.log('\nStopping...');
         logTailer?.stop();
+        previewUrlPoller.stop();
         await stopAutoCommit();
         statusLine?.destroy();
         keyboard?.stop();
@@ -299,7 +414,7 @@ export async function execDev(options) {
             switch (action) {
                 case 'o':
                 case 'p':
-                    import('open').then(m => m.default(session.previewUrl));
+                    import('open').then(m => m.default(currentPreviewUrl));
                     break;
                 case 'a':
                     logFilter = 'all';
@@ -319,7 +434,7 @@ export async function execDev(options) {
                 case 'i':
                     console.log(getInfoPanel({
                         appName: config.appName,
-                        previewUrl: session.previewUrl,
+                        previewUrl: currentPreviewUrl,
                         workspaceName: config.workspaceName,
                         directory: cwd,
                     }));
@@ -358,7 +473,505 @@ export const devCommand = new Command('dev')
     .description('Start local development with live sync, preview sandbox, and file watching')
     .option('--no-logs', 'Disable automatic log tailing')
     .option('--logs-only-file', 'Write logs to file only, not terminal')
+    .option('--detach', 'Start the dev session in the background and exit. Logs go to .runwork/dev-{stdout,stderr}.log')
+    .option('--restart', 'Stop any existing dev session first, then start a fresh one')
+    // Hidden internal flag passed by `runwork dev --detach` when it spawns
+    // its detached child. Not for end users -- registered here only so
+    // commander does not throw "unknown option" when the child receives it.
+    .addOption(new Option(INTERNAL_DETACHED_CHILD_FLAG).hideHelp())
     .action(async (options, command) => {
     const globalJson = shouldOutputJson(command.optsWithGlobals().json);
-    await execDev({ ...options, json: globalJson });
+    // The internal child marker is parsed manually because we want it
+    // hidden from --help and from commander's option list. Its presence
+    // means: "this process is the detached child of a `--detach` parent;
+    // skip the parent-spawn branch and run the actual dev work."
+    const isChild = isInternalDetachedChild(process.argv);
+    if (options.detach && !isChild) {
+        await runDevDetachParent({
+            json: globalJson,
+            restart: options.restart,
+        });
+        return;
+    }
+    await execDev({
+        ...options,
+        json: globalJson,
+        mode: isChild ? 'detached' : 'foreground',
+        restart: options.restart,
+    });
+});
+/**
+ * Parent half of `runwork dev --detach`. Reads the app config to know
+ * which appId we're spawning a child for, dispatches to the detach
+ * orchestrator in `src/dev/detach.ts`, and renders the outcome.
+ *
+ * The parent does not do any of the dev work itself -- it is a thin
+ * observer that exists only long enough to confirm the child has a
+ * preview URL. See `docs/plans/2026-05-06-runwork-dev-lifecycle-design.md`
+ * for the full handshake contract.
+ */
+async function runDevDetachParent(opts) {
+    const config = readConfig();
+    const cwd = process.cwd();
+    const ts = () => new Date().toISOString();
+    // --restart: stop the existing session before spawning a child.
+    if (opts.restart) {
+        const stopOutcome = await stopSession(cwd, config.appId);
+        if (!opts.json && stopOutcome.result === 'stopped') {
+            console.log(dim(`Stopped previous dev session (PID ${stopOutcome.pid}).`));
+        }
+    }
+    // Idempotency: if a live session is already running on this machine,
+    // don't spawn a second child -- just report it.
+    const existing = getSessionState(cwd, config.appId);
+    if (existing.state === 'alive') {
+        const f = existing.file;
+        if (opts.json) {
+            jsonLine({
+                event: 'already_running',
+                previewUrl: f.previewUrl,
+                pid: f.pid,
+                sessionId: f.sessionId,
+                mode: f.mode,
+                timestamp: ts(),
+            });
+        }
+        else {
+            console.log(`Dev session already running (PID ${f.pid}, mode: ${f.mode}).`);
+            console.log(`  Preview: ${green(f.previewUrl || '(starting up)')}`);
+            console.log(dim(`  Follow logs: runwork dev attach`));
+        }
+        return;
+    }
+    if (existing.state === 'stale') {
+        removeSessionFile(cwd);
+    }
+    if (opts.json) {
+        jsonLine({ event: 'starting', mode: 'detached', timestamp: ts() });
+    }
+    else {
+        console.log(dim('Starting dev session in background...'));
+    }
+    // Construct the child's args from our own process.argv. We strip the
+    // marker (so the parent can't accidentally fall into the child path
+    // itself if invoked through a wrapper) and then add it back exactly
+    // once.
+    //
+    // process.argv[0] is the executable, which we replace with
+    // `process.execPath` at spawn time. We forward everything from argv[1]
+    // onwards. This works for both Node (`node script.js dev --detach` ->
+    // ["script.js", "dev", "--detach"]) and Bun-standalone binaries
+    // (`runwork dev --detach` -> ["dev", "--detach"]) because in both cases
+    // re-spawning with execPath + argv.slice(1) reproduces the same
+    // invocation.
+    const userArgs = stripInternalChildFlag(process.argv.slice(1));
+    const childArgs = [...userArgs, INTERNAL_DETACHED_CHILD_FLAG];
+    const outcome = await runAsDetachedParent({
+        appDir: cwd,
+        expectedAppId: config.appId,
+        childArgs,
+    });
+    switch (outcome.result) {
+        case 'started': {
+            const f = outcome.file;
+            if (opts.json) {
+                jsonLine({
+                    event: 'session_started',
+                    previewUrl: f.previewUrl,
+                    pid: f.pid,
+                    sessionId: f.sessionId,
+                    mode: f.mode,
+                    timestamp: ts(),
+                    guide: buildDevSessionGuide(),
+                });
+            }
+            else {
+                console.log('');
+                console.log(`Dev session running in background (PID ${f.pid}).`);
+                console.log(`  Preview: ${green(f.previewUrl)}`);
+                console.log(dim(`  Stop with: runwork dev stop`));
+                console.log(dim(`  Logs:      tail -f .runwork/dev-stdout.log`));
+                console.log('');
+            }
+            return;
+        }
+        case 'wrong-pid': {
+            // Race: another process won the session-file write. Treat as
+            // "already running" -- the user's intent is satisfied. Our spawned
+            // child will detect the same file at its own startup probe and
+            // exit cleanly without doing duplicate work.
+            const f = outcome.file;
+            if (opts.json) {
+                jsonLine({
+                    event: 'already_running',
+                    previewUrl: f.previewUrl,
+                    pid: f.pid,
+                    sessionId: f.sessionId,
+                    mode: f.mode,
+                    timestamp: ts(),
+                });
+            }
+            else {
+                console.log(`Another dev session already running (PID ${f.pid}).`);
+                console.log(`  Preview: ${green(f.previewUrl)}`);
+            }
+            return;
+        }
+        case 'child-exited': {
+            const message = `Detached dev session exited before becoming ready.`;
+            if (opts.json) {
+                jsonLine({
+                    event: 'error',
+                    phase: 'detach-child-exited',
+                    timestamp: ts(),
+                    error: {
+                        message,
+                        diagnosis: 'The detached child process exited (typically due to missing auth, missing git, network failure, or a sync conflict) before it could publish a preview URL.',
+                        suggestions: [
+                            'Inspect the child stderr at .runwork/dev-stderr.log',
+                            'Run `runwork doctor` to verify auth and connectivity',
+                            'Try `runwork dev` (foreground) to see the failure inline',
+                        ],
+                        childLogTail: outcome.childLogTail,
+                    },
+                });
+            }
+            else {
+                console.error(yellow(message));
+                console.error(dim('  Inspect .runwork/dev-stderr.log or run `runwork dev` to see what failed.'));
+                if (outcome.childLogTail) {
+                    console.error(dim('  Tail of child stderr:'));
+                    for (const line of outcome.childLogTail.split('\n').slice(-10)) {
+                        if (line)
+                            console.error(dim(`    ${line}`));
+                    }
+                }
+            }
+            process.exit(1);
+            return;
+        }
+        case 'timeout': {
+            const message = `Detached dev session did not become ready within 90s.`;
+            if (opts.json) {
+                jsonLine({
+                    event: 'error',
+                    phase: 'detach',
+                    timestamp: ts(),
+                    error: {
+                        message,
+                        diagnosis: 'The detached child process was spawned but never wrote a session file with a preview URL. The sandbox boot may have failed.',
+                        suggestions: [
+                            'Inspect the child stderr at .runwork/dev-stderr.log',
+                            'Run `runwork doctor` to verify auth and connectivity',
+                            'Try `runwork dev` (foreground) to see the failure inline',
+                        ],
+                        childLogTail: outcome.childLogTail,
+                    },
+                });
+            }
+            else {
+                console.error(yellow(message));
+                console.error(dim('  Inspect .runwork/dev-stderr.log or run `runwork dev` to see what failed.'));
+                if (outcome.childLogTail) {
+                    console.error(dim('  Tail of child stderr:'));
+                    for (const line of outcome.childLogTail.split('\n').slice(-10)) {
+                        if (line)
+                            console.error(dim(`    ${line}`));
+                    }
+                }
+            }
+            process.exit(1);
+            return;
+        }
+        case 'spawn-failed': {
+            const message = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+            if (opts.json) {
+                jsonLine({
+                    event: 'error',
+                    phase: 'detach-spawn',
+                    timestamp: ts(),
+                    error: {
+                        message: `Failed to spawn detached child: ${message}`,
+                        diagnosis: 'The CLI could not fork itself into a background process.',
+                        suggestions: ['Run `runwork dev` (foreground) instead'],
+                    },
+                });
+            }
+            else {
+                console.error(yellow(`Failed to start detached dev session: ${message}`));
+                console.error(dim('  Run `runwork dev` (foreground) instead.'));
+            }
+            process.exit(1);
+            return;
+        }
+    }
+}
+/**
+ * `runwork dev stop` -- subcommand of `dev`. Tears down a running
+ * session by reading the local session file. Idempotent.
+ */
+const devStopCommand = new Command('stop')
+    .description('Stop the dev session running for this app')
+    .action(async (_opts, command) => {
+    const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    const config = readConfig();
+    const cwd = process.cwd();
+    const ts = () => new Date().toISOString();
+    const outcome = await stopSession(cwd, config.appId);
+    switch (outcome.result) {
+        case 'no-session':
+            if (useJson) {
+                jsonLine({ event: 'session_stopped', result: 'no-session', timestamp: ts() });
+            }
+            else {
+                console.log('No dev session running here.');
+            }
+            return;
+        case 'stale-cleaned':
+            if (useJson) {
+                jsonLine({
+                    event: 'session_stopped',
+                    result: 'stale-cleaned',
+                    reason: outcome.reason,
+                    pid: outcome.pid,
+                    timestamp: ts(),
+                });
+            }
+            else {
+                console.log(`Cleaned up stale session file (reason: ${outcome.reason}).`);
+            }
+            return;
+        case 'stopped':
+            if (useJson) {
+                jsonLine({
+                    event: 'session_stopped',
+                    result: 'stopped',
+                    pid: outcome.pid,
+                    gracefully: outcome.gracefully,
+                    timestamp: ts(),
+                });
+            }
+            else {
+                const how = outcome.gracefully ? 'gracefully' : 'forcefully';
+                console.log(`Stopped dev session ${how} (PID ${outcome.pid}).`);
+            }
+            return;
+        case 'kill-failed': {
+            const msg = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+            if (useJson) {
+                jsonLine({
+                    event: 'error',
+                    phase: 'dev-stop',
+                    timestamp: ts(),
+                    error: {
+                        message: `Failed to stop PID ${outcome.pid}: ${msg}`,
+                        diagnosis: 'The session file was removed but the process could not be killed by this CLI invocation.',
+                        suggestions: [
+                            `Manually kill the process: kill ${outcome.pid}`,
+                            'Verify with: ps -p ' + outcome.pid,
+                        ],
+                    },
+                });
+            }
+            else {
+                console.error(yellow(`Could not kill PID ${outcome.pid}: ${msg}`));
+                console.error(dim('  The session file has been removed; the process may need to be killed manually.'));
+            }
+            process.exit(1);
+            return;
+        }
+    }
+});
+devCommand.addCommand(devStopCommand);
+/**
+ * `runwork dev attach` -- read-only join on a running dev session.
+ *
+ * The keyboard glue here is intentionally a near-copy of the foreground
+ * dev path's switch (we considered factoring it out and decided the
+ * inverted cleanup semantics would force a config-heavy abstraction --
+ * see the conversation in `docs/plans/2026-05-06-runwork-dev-lifecycle-design.md`).
+ *
+ * The hard rule: nothing this command does, EXCEPT the explicit `s`
+ * keypress, ever stops the attached session. Ctrl+C and `q` exit the
+ * attach UI but leave the dev session running.
+ */
+const devAttachCommand = new Command('attach')
+    .description('Attach to a running dev session for this app: tail logs, see the preview URL, control via keys')
+    .option('--initial-lines <n>', 'How many trailing log lines to replay on connect (default 50)', (v) => parseInt(v, 10), 50)
+    .action(async (options, command) => {
+    const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    const config = readConfig();
+    const cwd = process.cwd();
+    const ts = () => new Date().toISOString();
+    const target = resolveAttachTarget(cwd, config.appId);
+    if (target.result === 'no-session') {
+        if (useJson) {
+            jsonLine({ event: 'attach_no_session', timestamp: ts() });
+        }
+        else {
+            console.log('No dev session running here.');
+            console.log(dim('  Start one with `runwork dev` or `runwork dev --detach`.'));
+        }
+        return;
+    }
+    if (target.result === 'stale-cleaned') {
+        if (useJson) {
+            jsonLine({ event: 'attach_stale_cleaned', reason: target.reason, timestamp: ts() });
+        }
+        else {
+            console.log(`Found a stale session file (reason: ${target.reason}); cleaned up.`);
+            console.log(dim('  Nothing to attach to. Start a new session with `runwork dev`.'));
+        }
+        return;
+    }
+    const file = target.file;
+    if (useJson) {
+        jsonLine({
+            event: 'attach_started',
+            pid: file.pid,
+            sessionId: file.sessionId,
+            previewUrl: file.previewUrl,
+            mode: file.mode,
+            startedAt: file.startedAt,
+            timestamp: ts(),
+        });
+    }
+    else {
+        console.log('');
+        console.log(`Attached to dev session ${dim(`(PID ${file.pid}, mode: ${file.mode}, ${formatStartedAgo(file.startedAt)})`)}`);
+        console.log(`  Preview: ${green(file.previewUrl || '(starting up)')}`);
+        console.log(dim(`  Logs:    .runwork/dev-stdout.log, dev-stderr.log`));
+        console.log('');
+        console.log(dim('  o:open   i:info   s:stop   q:detach (Ctrl+C also detaches; session keeps running)'));
+        console.log('');
+    }
+    const colors = { dim, green, yellow, red, cyan };
+    const paths = getAttachLogPaths(cwd);
+    let stopping = false;
+    // Status line: only in human + TTY mode. The same caveats apply as
+    // foreground dev: createStatusLine returns a no-op when stdout
+    // is not a TTY.
+    const statusLine = useJson ? null : createStatusLine(process.stdout);
+    let displayedUrl = file.previewUrl;
+    function updateStatus() {
+        if (!statusLine)
+            return;
+        const sep = '\x1b[90m│\x1b[39m';
+        statusLine.update(`${bold(config.appName)} ${sep} ${green(displayedUrl || '(starting up)')} ${sep} ${cyan('attached')} ${sep} ${dim(`PID ${file.pid}`)} ${sep} \x1b[90mo\x1b[39m:open \x1b[90mi\x1b[39m:info \x1b[90ms\x1b[39m:stop \x1b[90mq\x1b[39m:detach`);
+    }
+    if (statusLine)
+        updateStatus();
+    const tail = startLogTail(paths.stdout, paths.stderr, {
+        initialLines: options.initialLines ?? 50,
+        onLine: (line, source) => {
+            if (useJson) {
+                // Pass-through: agents consuming attach in JSON mode see the
+                // raw NDJSON log lines plus a wrapper noting the source.
+                jsonLine({ event: 'log', source, line, timestamp: ts() });
+                return;
+            }
+            const rendered = renderLogLine(line, source, colors);
+            console.log(rendered.text);
+        },
+        onTruncated: () => {
+            // The detached child reopens log files in 'w' mode at session
+            // start, but a restart of the SAME PID shouldn't happen --
+            // restart kills the old PID, spawns a new one. So a truncation
+            // we observe is most likely "another process restarted the
+            // session." We surface it and let the session-file watch decide
+            // whether to fully exit (which it will when it sees the PID
+            // change).
+            if (!useJson)
+                console.log(yellow('  (log file was truncated -- session may have restarted)'));
+        },
+    });
+    const sessionWatch = startSessionFileWatch(cwd, file, {
+        expectedAppId: config.appId,
+        onUrlChanged: (next, prev) => {
+            displayedUrl = next;
+            if (useJson) {
+                jsonLine({ event: 'preview_url_changed', previewUrl: next, previousUrl: prev, timestamp: ts() });
+            }
+            else {
+                console.log(dim(`  Preview URL changed: ${next}`));
+                updateStatus();
+            }
+        },
+        onSessionGone: () => {
+            if (stopping)
+                return;
+            if (useJson) {
+                jsonLine({ event: 'attach_session_ended', pid: file.pid, timestamp: ts() });
+            }
+            else {
+                console.log('');
+                console.log(yellow('Session ended. Detaching.'));
+            }
+            cleanupAttach('session-ended');
+        },
+    });
+    const keyboard = useJson ? null : createKeyboardListener();
+    function cleanupAttach(reason) {
+        if (stopping)
+            return;
+        stopping = true;
+        tail.stop();
+        sessionWatch.stop();
+        statusLine?.destroy();
+        keyboard?.stop();
+        // We never call removeSessionFile here -- attach does not own the
+        // session. The only path that ends a session is `s` -> stopSession,
+        // which removes the file itself.
+        void reason;
+        process.exit(0);
+    }
+    process.on('SIGINT', () => cleanupAttach('user'));
+    process.on('SIGTERM', () => cleanupAttach('user'));
+    if (keyboard) {
+        keyboard.start(async (action) => {
+            switch (action) {
+                case 'o':
+                case 'p': {
+                    const url = getCurrentPreviewUrl(cwd, displayedUrl);
+                    if (url)
+                        import('open').then((m) => m.default(url));
+                    break;
+                }
+                case 'i':
+                    console.log(getInfoPanel({
+                        appName: config.appName,
+                        previewUrl: getCurrentPreviewUrl(cwd, displayedUrl),
+                        workspaceName: config.workspaceName,
+                        directory: cwd,
+                    }));
+                    break;
+                case 's': {
+                    console.log(dim('Stopping dev session...'));
+                    const outcome = await stopSession(cwd, config.appId);
+                    if (outcome.result === 'stopped') {
+                        console.log(`Stopped dev session (PID ${outcome.pid}).`);
+                    }
+                    else if (outcome.result === 'kill-failed') {
+                        console.error(yellow(`Could not kill PID ${outcome.pid}.`));
+                    }
+                    cleanupAttach('stop');
+                    break;
+                }
+                case 'quit':
+                    cleanupAttach('user');
+                    break;
+                // 'a' / 'e' / 'r' are no-ops in attach -- log filtering is a
+                // foreground-dev-only feature. The keys are still parsed
+                // centrally so they don't surface as null actions.
+                case 'a':
+                case 'e':
+                case 'r':
+                case null:
+                    break;
+            }
+        });
+    }
+    // Block until cleanup runs.
+    await new Promise(() => { });
 });
+devCommand.addCommand(devAttachCommand);