runwork 0.13.3 → 0.13.4

package/bundled-types/core-workflow-instance.d.ts

@@ -9,6 +9,12 @@ import { DurableObject } from 'cloudflare:workers';
 import type { NativeWorkflowInstance, NativeWorkflowConfig } from './core-workflow-types';
 import type { StepOptions, WaitEventOptions } from './core-workflows';
 import { type Env } from './core-utils';
+export declare class WorkflowPausedError extends Error {
+    reason: 'sleep' | 'waitEvent';
+    resumeAt?: number | undefined;
+    constructor(reason: 'sleep' | 'waitEvent', resumeAt?: number | undefined);
+}
+export declare function isWorkflowControlSignal(error: unknown): boolean;
 /**
  * WorkflowInstance Durable Object
  *

package/bundled-types/workflows.d.ts

@@ -12,3 +12,4 @@ export { DEFAULT_WORKFLOW_CONFIG } from './core-workflow-types';
 export { WORKFLOW_INFRA_MODE } from './core-workflow-config';
 export { WorkflowInstanceDO } from './core-workflow-instance';
 export { WorkflowCoordinator } from './core-workflow-coordinator';
+export { WorkflowPausedError, isWorkflowControlSignal } from './core-workflow-instance';

package/dist/commands/deploy.js

@@ -1,13 +1,20 @@
 import { Command } from 'commander';
-import { execFileSync } from '../utils/subprocess.js';
 import { readFileSync, existsSync } from 'fs';
 import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
 import { buildDeployGuide, buildErrorResponse } from '../utils/agent-guidance.js';
+import { requireGit } from '../git/preflight.js';
+import { ensureGitIdentity } from '../git/identity.js';
+import { commitWorkingTree } from '../git/auto-commit.js';
+import { syncWithRemote, hasCommits } from '../git/sync.js';
+import { snapshotCriticalFiles, restoreMissingCriticalFiles, commitAndPushRestoredFiles } from '../git/critical-files.js';
+import { evaluateDeployGuard } from '../git/deploy-guard.js';
+import { promptConfirm } from '../utils/prompt.js';
 export const deployCommand = new Command('deploy')
     .description('Deploy the current app to production')
-    .action(async (_opts, command) => {
+    .option('-y, --yes', 'Skip the confirmation prompt when the working tree differs from the preview')
+    .action(async (opts, command) => {
     const useJson = shouldOutputJson(command.optsWithGlobals().json);
     if (!existsSync('.runwork.json')) {
         if (useJson) {
@@ -17,36 +24,93 @@ export const deployCommand = new Command('deploy')
         console.error('No .runwork.json found. Run `runwork init` first.');
         process.exit(1);
     }
+    requireGit('deploy');
     const config = JSON.parse(readFileSync('.runwork.json', 'utf-8'));
     const creds = requireAuth();
     const client = new ApiClient(creds);
-    // Sync: pull + push (skip if no commits yet)
-    let repoHasCommits = false;
+    const cwd = process.cwd();
+    // Deploy guard: the preview reflects the last *pushed* commit. If the
+    // working tree is dirty or ahead of `runwork/main` and no auto-syncing
+    // dev session is keeping the preview in lockstep, `runwork deploy` will
+    // commit and ship code the user never saw in the preview. Warn first.
+    // Runs BEFORE the commit/sync/deploy steps below, which are unchanged.
+    const guard = evaluateDeployGuard(cwd, config.appId);
+    let deployGuardWarning;
+    if (guard.warn) {
+        deployGuardWarning = 'You have uncommitted or unpushed changes. `runwork deploy` will commit and deploy them, but they are not reflected in the preview.';
+        if (useJson) {
+            // Agents must never be blocked: the warning rides along in the
+            // final success response below so we proceed without prompting.
+        }
+        else if (opts.yes || !process.stdin.isTTY) {
+            // Non-interactive (no TTY) or explicit --yes: warn and proceed.
+            console.warn(deployGuardWarning);
+        }
+        else {
+            console.warn(deployGuardWarning);
+            const proceed = await promptConfirm('Deploy these changes anyway?');
+            if (!proceed) {
+                console.log('Deploy cancelled.');
+                process.exit(0);
+            }
+        }
+    }
+    // Deploy must work even when no `runwork dev` session is (or ever was)
+    // running. Reuse the exact sync path dev uses: commit any pending
+    // working-tree changes, then fetch -> rebase (fallback merge) -> push.
+    // `ensureGitIdentity` seeds a local identity so the commit cannot fail
+    // on a fresh machine where git user.email/.name were never configured.
+    ensureGitIdentity(cwd, creds);
+    if (!useJson)
+        console.log('Syncing...');
     try {
-        execFileSync('git', ['rev-parse', 'HEAD'], { stdio: 'pipe' });
-        repoHasCommits = true;
+        commitWorkingTree(cwd, `deploy: ${new Date().toISOString().replace('T', ' ').slice(0, 19)}`);
     }
     catch {
-        // No commits yet
+        // No commit created (clean tree) or git not initialized yet. The
+        // sync/push step below surfaces the actionable failure.
+    }
+    if (!hasCommits(cwd)) {
+        if (useJson) {
+            jsonOut(buildErrorResponse('deploy', 'Nothing to deploy', 'No commits exist and the working tree has no changes to commit, so there is nothing to sync or deploy.', ['Make changes to your app first', 'Run runwork dev to develop and verify changes', 'Then run runwork deploy']));
+            process.exit(1);
+        }
+        console.error('Nothing to deploy. Make changes first, then run `runwork deploy`.');
+        process.exit(1);
     }
-    if (repoHasCommits) {
-        if (!useJson)
-            console.log('Syncing...');
-        try {
-            execFileSync('git', ['pull', '--rebase', 'runwork', 'main'], { stdio: useJson ? 'pipe' : 'inherit' });
+    // Protect critical files across the sync exactly as `runwork dev` does:
+    // syncWithRemote may merge with `-X theirs` (remote wins) to reconcile
+    // diverged histories, which can delete `.runwork.json`/`blueprint.json`/
+    // `.gitignore` if the remote tip lacks them. Snapshot before, restore after.
+    const criticalSnapshot = snapshotCriticalFiles(cwd);
+    const syncResult = syncWithRemote(cwd);
+    const restoredCriticalFiles = restoreMissingCriticalFiles(cwd, criticalSnapshot);
+    if (restoredCriticalFiles.length > 0) {
+        const pushed = commitAndPushRestoredFiles(cwd, restoredCriticalFiles);
+        if (!useJson) {
+            console.warn(`Sync removed critical file(s); restored: ${restoredCriticalFiles.join(', ')}`);
+            if (!pushed)
+                console.warn('Restoration committed locally but not pushed; will retry on next sync.');
         }
-        catch {
-            if (!useJson)
-                console.warn('Pull failed. Continuing...');
+    }
+    if (syncResult.status === 'sync-failed') {
+        const reason = syncResult.error && syncResult.error !== 'stash-conflict'
+            ? syncResult.error
+            : 'Local history could not be reconciled with the remote.';
+        if (useJson) {
+            jsonOut(buildErrorResponse('deploy', 'Sync failed before deployment', reason, ['Run git fetch runwork && git rebase runwork/main and resolve any conflicts', 'Or run runwork dev to sync interactively', 'Then retry runwork deploy']));
+            process.exit(1);
         }
-        execFileSync('git', ['push', 'runwork', 'main'], { stdio: useJson ? 'pipe' : 'inherit' });
+        console.error(`Sync failed: ${reason}`);
+        console.error('Resolve conflicts (git status), or run `runwork dev`, then retry `runwork deploy`.');
+        process.exit(1);
     }
-    else {
+    if (!syncResult.pushed) {
         if (useJson) {
-            jsonOut(buildErrorResponse('deploy', 'Sync failed before deployment', 'Files could not be synced to the remote.', ['Run runwork dev first to ensure files sync correctly', 'Check your network connection', 'Retry runwork deploy']));
+            jsonOut(buildErrorResponse('deploy', 'Failed to push before deployment', 'Local commits were synced but could not be pushed to the remote.', ['Check your network connection', 'Run runwork dev to retry syncing', 'Then retry runwork deploy']));
             process.exit(1);
         }
-        console.error('No commits to deploy. Commit your changes first.');
+        console.error('Push failed. Check your connection and retry `runwork deploy`.');
         process.exit(1);
     }
     // Trigger deploy
@@ -65,19 +129,34 @@ export const deployCommand = new Command('deploy')
         console.error(`Deploy failed: ${message}`);
         process.exit(1);
     }
+    // The server returns a deployment URL only when a deploy actually
+    // happened. An empty/missing URL means the deploy was a no-op or did
+    // not produce a live deployment, so we must not report success.
+    const deploymentUrl = result.deploymentUrl?.trim() ?? '';
+    const deployed = deploymentUrl.length > 0;
+    if (!deployed) {
+        if (useJson) {
+            jsonOut(buildErrorResponse('deploy', 'Deployment did not produce a URL', 'The deploy API returned no deployment URL. The deploy may have been a no-op (no changes) or failed server-side.', ['Confirm your changes were committed and pushed (the sync step above succeeded)', 'Run runwork info to check the deployed state', 'Run runwork logs --production to inspect server-side errors', 'Retry runwork deploy']));
+            process.exit(1);
+        }
+        console.error('Deploy did not return a URL. The deploy may have been a no-op or failed server-side.');
+        console.error('Run `runwork info` to check state, or `runwork logs --production` to inspect errors.');
+        process.exit(1);
+    }
     if (useJson) {
         const response = {
             success: true,
             command: 'deploy',
             result: {
-                deployed: true,
-                url: result.deploymentUrl,
+                deployed,
+                url: deploymentUrl,
                 appName: config.appName,
             },
             guide: buildDeployGuide(),
+            ...(deployGuardWarning ? { warning: deployGuardWarning } : {}),
         };
         jsonOut(response);
         return;
     }
-    console.log(`Deployed: ${result.deploymentUrl}`);
+    console.log(`Deployed: ${deploymentUrl}`);
 });

package/dist/commands/dev.d.ts

@@ -6,5 +6,6 @@ export declare function execDev(options?: {
     json?: boolean;
     mode?: SessionMode;
     restart?: boolean;
+    noSync?: boolean;
 }): Promise<void>;
 export declare const devCommand: Command;

package/dist/commands/dev.js

@@ -6,6 +6,7 @@ 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 { requireGit } from '../git/preflight.js';
 import { startLogTailer } from '../logs/tailer.js';
@@ -43,69 +44,14 @@ function readConfig() {
     }
     return JSON.parse(readFileSync('.runwork.json', 'utf-8'));
 }
-// Files the CLI cannot function without and which the user did not author.
-// `.runwork.json` is the local app identity; `blueprint.json` is the app's
-// canonical feature definition; `.gitignore` keeps caches out of git. If a
-// sync from the remote silently removes any of these (which has happened
-// when a server-side agent commits with a stale index — see
-// worker/agents/git/git.ts), restoring from a pre-sync snapshot keeps the
-// project usable and unblocks `runwork deploy`.
-const CRITICAL_FILES = ['.runwork.json', 'blueprint.json', '.gitignore'];
-function snapshotCriticalFiles(cwd) {
-    const snapshots = [];
-    for (const rel of CRITICAL_FILES) {
-        const abs = join(cwd, rel);
-        if (!existsSync(abs))
-            continue;
-        try {
-            snapshots.push({ path: rel, contents: readFileSync(abs, 'utf-8') });
-        }
-        catch {
-            // Best-effort: skip unreadable files.
-        }
-    }
-    return snapshots;
-}
-function restoreMissingCriticalFiles(cwd, snapshots) {
-    const restored = [];
-    for (const snap of snapshots) {
-        const abs = join(cwd, snap.path);
-        if (existsSync(abs))
-            continue;
-        try {
-            writeFileSync(abs, snap.contents, 'utf-8');
-            restored.push(snap.path);
-        }
-        catch {
-            // Best-effort: skip files we cannot write back.
-        }
-    }
-    return restored;
-}
-function commitAndPushRestoredFiles(cwd, files) {
-    if (files.length === 0)
-        return false;
-    try {
-        execFileSync('git', ['add', '--', ...files], { cwd, stdio: 'pipe' });
-        execFileSync('git', ['commit', '-m', 'chore: restore critical files removed by sync'], { cwd, stdio: 'pipe' });
-    }
-    catch {
-        return false;
-    }
-    try {
-        // `HEAD:main` so the push works regardless of local branch name.
-        execFileSync('git', ['push', 'runwork', 'HEAD:main'], { cwd, stdio: 'pipe' });
-        return true;
-    }
-    catch {
-        // Push failures are non-fatal: the local copy is restored, and the
-        // restoration commit will be pushed with the next auto-sync cycle.
-        return false;
-    }
-}
 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();
@@ -199,30 +145,34 @@ export async function execDev(options) {
             }
         }
     }
-    // Download fresh template to ensure latest version
-    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);
+    // 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 {
-            execFileSync('git', ['checkout', '--', '.'], { cwd, stdio: 'pipe' });
+            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 {
-            // May fail if no commits yet
+            if (!useJson)
+                console.warn(yellow('Template update failed. Continuing with current files.'));
         }
     }
-    catch {
-        if (!useJson)
-            console.warn(yellow('Template update failed. Continuing with current files.'));
-    }
     // Populate type definitions
     await populateTypes(cwd);
     if (useJson)
@@ -239,89 +189,108 @@ export async function execDev(options) {
     await populateSkill(cwd, client, config.appId);
     if (useJson)
         jsonLine({ event: 'startup', phase: 'skill_fetched', timestamp: ts() });
-    // Sync
-    if (!useJson)
-        console.log(dim('Syncing...'));
-    const criticalSnapshot = snapshotCriticalFiles(cwd);
-    const syncResult = syncWithRemote(cwd);
-    const restoredCriticalFiles = restoreMissingCriticalFiles(cwd, criticalSnapshot);
-    if (restoredCriticalFiles.length > 0) {
-        const pushed = commitAndPushRestoredFiles(cwd, restoredCriticalFiles);
+    // 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: 'sync_restored_critical_files',
-                files: restoredCriticalFiles,
-                pushed,
-                timestamp: ts(),
-            });
+            jsonLine({ event: 'startup', phase: 'fetch', 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.'));
-            }
+            console.log(dim('Fetched remote refs (no-sync mode).'));
         }
     }
-    if (useJson) {
-        jsonLine({ event: 'startup', phase: 'sync', status: syncResult.status, pushed: syncResult.pushed, timestamp: ts() });
-        if (syncResult.status === 'sync-failed') {
-            if (syncResult.error === 'stash-conflict') {
+    else {
+        if (!useJson)
+            console.log(dim('Syncing...'));
+        const criticalSnapshot = snapshotCriticalFiles(cwd);
+        const syncResult = syncWithRemote(cwd);
+        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') {
+                if (syncResult.error === 'stash-conflict') {
+                    jsonLine({
+                        event: 'error',
+                        phase: 'sync',
+                        timestamp: ts(),
+                        error: {
+                            message: 'Merge conflicts detected after stash pop',
+                            diagnosis: 'Local changes could not be automatically merged with the remote state. The stash pop resulted in conflicts that require manual resolution.',
+                            suggestions: [
+                                'Resolve the merge conflicts in the affected files',
+                                'Run git add on resolved files, then git commit',
+                                'Run runwork dev again after resolving conflicts',
+                            ],
+                        },
+                    });
+                    process.exit(1);
+                }
                 jsonLine({
                     event: 'error',
                     phase: 'sync',
                     timestamp: ts(),
                     error: {
-                        message: 'Merge conflicts detected after stash pop',
-                        diagnosis: 'Local changes could not be automatically merged with the remote state. The stash pop resulted in conflicts that require manual resolution.',
+                        message: syncResult.error ?? 'File sync failed',
+                        diagnosis: 'Could not sync files to the sandbox. This usually means the sandbox session expired or the network connection was interrupted.',
                         suggestions: [
-                            'Resolve the merge conflicts in the affected files',
-                            'Run git add on resolved files, then git commit',
-                            'Run runwork dev again after resolving conflicts',
+                            'Run runwork dev again to start a fresh session',
+                            'Check your network connection',
+                            'Run runwork doctor to diagnose environment issues',
                         ],
                     },
                 });
-                process.exit(1);
             }
-            jsonLine({
-                event: 'error',
-                phase: 'sync',
-                timestamp: ts(),
-                error: {
-                    message: syncResult.error ?? 'File sync failed',
-                    diagnosis: 'Could not sync files to the sandbox. This usually means the sandbox session expired or the network connection was interrupted.',
-                    suggestions: [
-                        'Run runwork dev again to start a fresh session',
-                        'Check your network connection',
-                        'Run runwork doctor to diagnose environment issues',
-                    ],
-                },
-            });
         }
-    }
-    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':
-                if (syncResult.error === 'stash-conflict') {
-                    console.error('Merge conflicts detected after stash pop. Resolve conflicts and restart.');
-                    process.exit(1);
-                }
-                console.warn(yellow(`Sync failed. Continuing...`));
-                if (syncResult.error) {
-                    console.warn(dim(`  ${syncResult.error}`));
-                }
-                break;
-        }
-        if (!syncResult.pushed && syncResult.status !== 'skipped' && syncResult.status !== 'sync-failed') {
-            console.warn(yellow('Push failed. Continuing with current state...'));
+        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':
+                    if (syncResult.error === 'stash-conflict') {
+                        console.error('Merge conflicts detected after stash pop. Resolve conflicts and restart.');
+                        process.exit(1);
+                    }
+                    console.warn(yellow(`Sync failed. Continuing...`));
+                    if (syncResult.error) {
+                        console.warn(dim(`  ${syncResult.error}`));
+                    }
+                    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.
@@ -341,6 +310,7 @@ export async function execDev(options) {
         previewUrl: currentPreviewUrl,
         cliVersion: VERSION,
         mode,
+        noSync,
     }));
     // Emit session_started (JSON) or show banner (human)
     if (useJson) {
@@ -457,15 +427,32 @@ export async function execDev(options) {
             }
         });
     }
-    // Start file watcher
-    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 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({
@@ -487,12 +474,14 @@ export const devCommand = new Command('dev')
     .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;
@@ -510,6 +499,7 @@ export const devCommand = new Command('dev')
         json: globalJson,
         mode: isChild ? 'detached' : 'foreground',
         restart: options.restart,
+        noSync,
     });
 });
 /**

package/dist/commands/logs.js

@@ -21,13 +21,20 @@ export const logsCommand = new Command('logs')
     .option('--production', 'Show production runtime logs')
     .option('--events', 'Show app activity/events')
     .option('--all', 'Show both runtime logs and events')
-    .option('--follow', 'Poll for new logs every 3s')
+    .option('--follow', 'Poll for new logs every 3s (TTY only; ignored when piped or with --json)')
+    .option('--once', 'Fetch once and exit, even if --follow is set (forced in non-TTY/agent contexts)')
     .option('--limit <n>', 'Number of log entries to show', '25')
     .option('--level <level>', 'Filter by log level (production only)')
     .option('--search <text>', 'Search log content (production only)')
     .option('--type <type>', 'Filter by event type (events only)')
     .action(async (opts, command) => {
     const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    // Follow mode blocks forever (until SIGINT/SIGTERM), which deadlocks
+    // non-interactive callers: piped shells, CI, and AI agents never send
+    // those signals and hang waiting for the command to exit. Only follow
+    // when explicitly requested AND stdout is an interactive TTY AND we are
+    // not emitting JSON. `--once` forces single-shot even on a TTY.
+    const shouldFollow = Boolean(opts.follow) && !opts.once && !useJson && Boolean(process.stdout.isTTY);
     const config = readConfig();
     const creds = requireAuth();
     const client = new ApiClient(creds);
@@ -79,7 +86,7 @@ export const logsCommand = new Command('logs')
                 // Preview logs (default)
                 try {
                     const { stdout, stderr } = await client.getPreviewLogs(appId);
-                    if (opts.follow && !isFirstPoll) {
+                    if (shouldFollow && !isFirstPoll) {
                         // Incremental mode: only print new content since last poll
                         // Reset detection: if buffer was truncated (sandbox restart), reset cursor
                         if (stdout && stdout.length < lastStdoutLength) {
@@ -198,7 +205,7 @@ export const logsCommand = new Command('logs')
         isFirstPoll = false;
     };
     await fetchAndPrint();
-    if (opts.follow) {
+    if (shouldFollow) {
         let stopped = false;
         let timer;
         const scheduleNext = () => {