runwork 0.15.1 → 0.16.0

package/dist/commands/dev.js

@@ -1,1011 +0,0 @@
-import { Command, Option } from 'commander';
-import { execFileSync } from '../utils/subprocess.js';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { requireAuth } from '../auth/store.js';
-import { ApiClient } from '../api/client.js';
-import { watchAndAutoCommit, stopAutoCommit } from '../git/auto-commit.js';
-import { syncWithRemote } from '../git/sync.js';
-import { snapshotCriticalFiles, restoreMissingCriticalFiles, commitAndPushRestoredFiles } from '../git/critical-files.js';
-import { ensureGitIdentity } from '../git/identity.js';
-import { ensureGitCredentialHelper } from '../git/credentials.js';
-import { ensureRunworkRemote } from '../git/remote.js';
-import { diagnoseSyncError } from '../git/classify-sync-error.js';
-import { buildStartupSyncSummary } from '../dev/startup-sync.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, buildChildArgs, isInternalDetachedChild, runAsDetachedParent, } 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';
-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, 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);
-        if (skill) {
-            writeFileSync(join(projectDir, 'SKILL.md'), skill, 'utf-8');
-        }
-    }
-    catch {
-        // Best-effort: app may be new with no registries yet
-    }
-}
-function readConfig() {
-    if (!existsSync('.runwork.json')) {
-        console.error('No .runwork.json found. Run `runwork init` first.');
-        process.exit(1);
-    }
-    return JSON.parse(readFileSync('.runwork.json', 'utf-8'));
-}
-export async function execDev(options) {
-    const useJson = options?.json ?? false;
-    const mode = options?.mode ?? 'foreground';
-    // No-sync mode: hold the preview open but never auto-touch the user's
-    // git or working tree. No file watcher, no auto-commit, and no
-    // working-tree-mutating startup (template auto-update / syncWithRemote).
-    // The user drives git manually; `git push` updates the preview.
-    const noSync = options?.noSync ?? false;
-    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).
-    ensureGitIdentity(cwd, creds);
-    // Ensure git can authenticate to the runwork remote before the sync loop
-    // fetches/pushes. Headless auth (get_cli_setup / hand-written credentials)
-    // registers API creds but not the git helper. See
-    // git/credentials.ts:ensureGitCredentialHelper.
-    if (creds?.baseUrl) {
-        await ensureGitCredentialHelper(creds.baseUrl);
-    }
-    // Ensure the `runwork` remote exists and points at the canonical URL. A
-    // manual `git clone <url>` names the remote `origin`, which otherwise makes
-    // the sync loop fail with "'runwork' does not appear to be a git repository".
-    ensureRunworkRemote(cwd, client.getGitRemoteUrl(config.workspaceId, config.appId));
-    // Detect user edits made outside of `runwork dev`. When this fires
-    // for an AI agent, it almost always means the agent edited code
-    // before starting dev -- the wrong order. We surface this loudly so
-    // the agent's tool-result-handling can correct course on the next
-    // task. The recommendation is canonical: start `runwork dev --detach`
-    // first, then edit. See DEV_FIRST_RULE.
-    const oldManifest = await loadManifest(cwd);
-    if (oldManifest) {
-        const userEdits = await detectUserEdits(cwd, oldManifest);
-        if (userEdits.length > 0) {
-            if (useJson) {
-                jsonLine({
-                    event: 'startup',
-                    phase: 'user_edits_detected',
-                    files: userEdits,
-                    timestamp: ts(),
-                    warning: `Detected ${userEdits.length} file(s) edited before \`runwork dev\` was running. These will be batch-synced now. Next time, start \`runwork dev --detach\` BEFORE editing so changes flow incrementally and you can verify each edit against the preview.`,
-                });
-            }
-            else {
-                console.log(`Detected ${userEdits.length} file(s) edited outside dev session:`);
-                for (const file of userEdits) {
-                    console.log(`  ${file}`);
-                }
-                console.log(yellow(`  Next time, start \`runwork dev --detach\` BEFORE editing -- changes will sync incrementally and the preview will validate each one.`));
-            }
-            try {
-                execFileSync('git', ['add', '--', ...userEdits], { stdio: 'pipe' });
-                execFileSync('git', ['commit', '-m', 'sync: user edits'], { stdio: 'pipe' });
-            }
-            catch {
-                // Nothing to commit or git not initialized yet
-            }
-        }
-    }
-    // Download fresh template to ensure latest version. Skipped entirely in
-    // no-sync mode: this block mutates the working tree (`git checkout -- .`),
-    // which would fight the user's manual git workflow.
-    if (!noSync) {
-        if (useJson) {
-            jsonLine({ event: 'startup', phase: 'template_update', timestamp: ts() });
-        }
-        else {
-            console.log(dim('Updating template...'));
-        }
-        try {
-            const zipData = await client.downloadSkeleton();
-            extractZip(zipData, cwd);
-            removeNestedGitDirs(cwd);
-            const newManifest = await generateManifest(cwd);
-            await saveManifest(cwd, newManifest);
-            try {
-                execFileSync('git', ['checkout', '--', '.'], { cwd, stdio: 'pipe' });
-            }
-            catch {
-                // May fail if no commits yet
-            }
-        }
-        catch {
-            if (!useJson)
-                console.warn(yellow('Template update failed. Continuing with current files.'));
-        }
-    }
-    // Populate type definitions
-    await populateTypes(cwd);
-    if (useJson)
-        jsonLine({ event: 'startup', phase: 'types_populated', timestamp: ts() });
-    // Start dev session
-    if (useJson) {
-        jsonLine({ event: 'startup', phase: 'dev_session', timestamp: ts() });
-    }
-    else {
-        console.log(dim('Starting dev session...'));
-    }
-    const session = await client.startDevSession(config.appId);
-    // Fetch SKILL.md (best-effort)
-    await populateSkill(cwd, client, config.appId);
-    if (useJson)
-        jsonLine({ event: 'startup', phase: 'skill_fetched', timestamp: ts() });
-    // Track the startup sync outcome so `session_started` can tell agents
-    // whether the preview reflects their latest edits or is serving stale code
-    // (friction log #2: a happy session_started masked a failed initial sync).
-    let startupSync = buildStartupSyncSummary({ noSync });
-    // Sync. In no-sync mode we never mutate the working tree: instead of
-    // syncWithRemote (rebase/merge/commit/push) we do a best-effort,
-    // read-only `git fetch` so remote-tracking refs stay current and
-    // `runwork info` can still report ahead/behind accurately.
-    if (noSync) {
-        try {
-            execFileSync('git', ['fetch', 'runwork'], { cwd, stdio: 'pipe' });
-        }
-        catch {
-            // Offline, or the `runwork` remote does not exist yet. Non-fatal.
-        }
-        if (useJson) {
-            jsonLine({ event: 'startup', phase: 'fetch', timestamp: ts() });
-        }
-        else {
-            console.log(dim('Fetched remote refs (no-sync mode).'));
-        }
-    }
-    else {
-        if (!useJson)
-            console.log(dim('Syncing...'));
-        const criticalSnapshot = snapshotCriticalFiles(cwd);
-        const syncResult = syncWithRemote(cwd);
-        startupSync = buildStartupSyncSummary({ noSync: false, status: syncResult.status });
-        const restoredCriticalFiles = restoreMissingCriticalFiles(cwd, criticalSnapshot);
-        if (restoredCriticalFiles.length > 0) {
-            const pushed = commitAndPushRestoredFiles(cwd, restoredCriticalFiles);
-            if (useJson) {
-                jsonLine({
-                    event: 'sync_restored_critical_files',
-                    files: restoredCriticalFiles,
-                    pushed,
-                    timestamp: ts(),
-                });
-            }
-            else {
-                console.warn(yellow(`  Sync removed critical file(s); restored: ${restoredCriticalFiles.join(', ')}`));
-                if (!pushed) {
-                    console.warn(dim('  Restoration committed locally but not pushed; will retry on next auto-sync.'));
-                }
-            }
-        }
-        if (useJson) {
-            jsonLine({ event: 'startup', phase: 'sync', status: syncResult.status, pushed: syncResult.pushed, timestamp: ts() });
-            if (syncResult.status === 'sync-failed') {
-                const diag = diagnoseSyncError(syncResult.error);
-                jsonLine({
-                    event: 'error',
-                    phase: 'sync',
-                    timestamp: ts(),
-                    error: {
-                        reason: diag.reason,
-                        message: diag.message,
-                        diagnosis: diag.diagnosis,
-                        suggestions: diag.suggestions,
-                    },
-                });
-                // A stash-pop conflict leaves the working tree in a state the user
-                // must resolve, so we stop. Other sync failures are non-fatal -- the
-                // preview keeps serving the last good state -- so we continue.
-                if (syncResult.error === 'stash-conflict') {
-                    process.exit(1);
-                }
-            }
-        }
-        else {
-            switch (syncResult.status) {
-                case 'skipped':
-                    console.log(dim('  No commits yet. Skipping sync.'));
-                    break;
-                case 'synced':
-                    console.log(green('  Synced with Runwork.'));
-                    break;
-                case 'merged':
-                    console.log(yellow('  Merged with Runwork (histories diverged).'));
-                    break;
-                case 'sync-failed': {
-                    const diag = diagnoseSyncError(syncResult.error);
-                    if (syncResult.error === 'stash-conflict') {
-                        console.error(`${diag.message}. ${diag.diagnosis}`);
-                        for (const s of diag.suggestions)
-                            console.error(dim(`  - ${s}`));
-                        process.exit(1);
-                    }
-                    console.warn(yellow(`Sync failed: ${diag.message}. Continuing...`));
-                    console.warn(dim(`  ${diag.diagnosis}`));
-                    for (const s of diag.suggestions)
-                        console.warn(dim(`  - ${s}`));
-                    break;
-                }
-            }
-            if (!syncResult.pushed && syncResult.status !== 'skipped' && syncResult.status !== 'sync-failed') {
-                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,
-        noSync,
-        // Persist the startup sync outcome so the detached parent can relay
-        // stale-code warnings -- not just the child's own log (friction log #2).
-        startupSync,
-    }));
-    // Emit session_started (JSON) or show banner (human). We always emit
-    // session_started -- it's the rendezvous signal `runwork dev --detach`
-    // polls for -- but carry the startup sync outcome so agents don't mistake a
-    // stale preview for one reflecting their latest edits. `staleCode: true`
-    // means the initial sync failed and the preview is serving the last good
-    // state, not the current working tree.
-    if (useJson) {
-        jsonLine({
-            event: 'session_started',
-            previewUrl: currentPreviewUrl,
-            appName: config.appName,
-            syncStatus: startupSync.syncStatus,
-            syncFailed: startupSync.syncFailed,
-            staleCode: startupSync.staleCode,
-            timestamp: ts(),
-            guide: buildDevSessionGuide(),
-        });
-    }
-    else {
-        console.log(getDevBanner({ appName: config.appName, previewUrl: currentPreviewUrl, workspaceName: config.workspaceName }));
-        if (startupSync.syncFailed) {
-            console.log(yellow('  Warning: initial sync failed. The preview shows the last deployed code, NOT your latest changes.'));
-        }
-        console.log(getKeyboardHints());
-        console.log('');
-        console.log(dim('  ─────────────────────────────────────────────'));
-        console.log('');
-    }
-    // Status line and keyboard only in human mode
-    const statusLine = useJson ? null : createStatusLine(process.stdout);
-    let syncedCount = 0;
-    let logFilter = 'all';
-    function updateStatus() {
-        if (!statusLine)
-            return;
-        const filterLabel = logFilter === 'all' ? 'All' : logFilter === 'events' ? 'Events' : 'Runtime';
-        const sep = '\x1b[90m\u2502\x1b[39m';
-        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();
-        process.exit(0);
-    };
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
-    if (keyboard) {
-        keyboard.start((action) => {
-            switch (action) {
-                case 'o':
-                case 'p':
-                    import('open').then(m => m.default(currentPreviewUrl));
-                    break;
-                case 'a':
-                    logFilter = 'all';
-                    console.log(dim('  Showing all logs.'));
-                    updateStatus();
-                    break;
-                case 'e':
-                    logFilter = 'events';
-                    console.log(dim('  Showing events only.'));
-                    updateStatus();
-                    break;
-                case 'r':
-                    logFilter = 'runtime';
-                    console.log(dim('  Showing runtime logs only.'));
-                    updateStatus();
-                    break;
-                case 'i':
-                    console.log(getInfoPanel({
-                        appName: config.appName,
-                        previewUrl: currentPreviewUrl,
-                        workspaceName: config.workspaceName,
-                        directory: cwd,
-                    }));
-                    break;
-                case 'quit':
-                    cleanup();
-                    break;
-            }
-        });
-    }
-    // Start file watcher. In no-sync mode we never watch the working tree:
-    // no fast-sync to the sandbox, no git auto-commit. The user drives git
-    // manually and `git push` is what updates the preview. We print a loud
-    // notice so it is unmistakable that edits are not flowing automatically.
-    if (noSync) {
-        if (useJson) {
-            jsonLine({ event: 'startup', phase: 'no_sync_mode', timestamp: ts() });
-        }
-        else {
-            console.log('');
-            console.log(yellow('  Auto-sync is OFF (--no-sync).'));
-            console.log(dim('  The preview reflects pushed commits. Run `git push` to update it;'));
-            console.log(dim('  uncommitted or unpushed changes are not shown.'));
-            console.log('');
-        }
-    }
-    else {
-        await watchAndAutoCommit(process.cwd(), client, config.appId, {
-            onFastSync: useJson
-                ? (count) => { jsonLine({ event: 'files_synced', count, target: 'preview', timestamp: ts() }); }
-                : (count) => { syncedCount += count; updateStatus(); },
-            onGitPush: useJson
-                ? (count) => { jsonLine({ event: 'files_pushed', count, target: 'git', timestamp: ts() }); }
-                : (count) => { syncedCount += count; updateStatus(); },
-        });
-    }
-    // Start log tailing (unless --no-logs)
-    if (options?.logs !== false) {
-        logTailer = startLogTailer({
-            appId: config.appId,
-            client,
-            projectDir: cwd,
-            toTerminal: !options?.logsOnlyFile,
-            toFile: true,
-            getFilter: () => logFilter,
-            useJson,
-        });
-    }
-    // Keep alive
-    await new Promise(() => { });
-}
-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')
-    .option('--no-sync', 'Hold the preview open without auto-syncing files or git; you push manually to update the preview')
-    // 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);
-    const noSync = options.sync === false;
-    // 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,
-        noSync,
-    });
-});
-/**
- * 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...'));
-    }
-    // `buildChildArgs` reproduces our invocation as args for the child
-    // (which is spawned with the same `process.execPath`), with two
-    // platform-aware tweaks: it skips Bun's auto-injected virtual-FS path
-    // on Windows (which the child runtime re-injects on its own), and it
-    // ensures exactly one copy of the internal-child marker.
-    const childArgs = buildChildArgs(process.argv);
-    const outcome = await runAsDetachedParent({
-        appDir: cwd,
-        expectedAppId: config.appId,
-        childArgs,
-    });
-    switch (outcome.result) {
-        case 'started': {
-            const f = outcome.file;
-            // Relay the child's startup sync outcome so a detached caller learns the
-            // preview may be serving stale code (the child only logs it otherwise).
-            const syncFailed = f.startupSync?.syncFailed ?? false;
-            if (opts.json) {
-                jsonLine({
-                    event: 'session_started',
-                    previewUrl: f.previewUrl,
-                    pid: f.pid,
-                    sessionId: f.sessionId,
-                    mode: f.mode,
-                    syncStatus: f.startupSync?.syncStatus,
-                    syncFailed,
-                    staleCode: f.startupSync?.staleCode ?? false,
-                    timestamp: ts(),
-                    guide: buildDevSessionGuide(),
-                });
-            }
-            else {
-                console.log('');
-                console.log(`Dev session running in background (PID ${f.pid}).`);
-                console.log(`  Preview: ${green(f.previewUrl)}`);
-                if (syncFailed) {
-                    console.log(yellow('  Warning: initial sync failed. The preview shows the last deployed code, NOT your latest changes.'));
-                }
-                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);