runwork 0.13.3 → 0.14.0

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 = () => {

package/dist/commands/mcp-entries.d.ts

@@ -0,0 +1,13 @@
+import type { McpServerConfig } from '../types.js';
+import type { McpServerEntry } from '../agents/types.js';
+/**
+ * Build local-agent MCP entries for external (third-party) servers added to the
+ * workspace. Auth handling by `authType`:
+ * - 'header': inject the user's resolved per-server headers (decrypted server-side).
+ * - 'oauth': emit no auth header so the local agent runs its own browser flow.
+ * - 'none'/unset: no auth header.
+ *
+ * Critically, external entries never receive the Runwork platform API key. That key
+ * belongs only on the Runwork workspace-tools entry, which is added separately.
+ */
+export declare function buildExternalMcpEntries(mcpServers: McpServerConfig[], resolvedCredentials: Record<string, Record<string, string>>): McpServerEntry[];

package/dist/commands/mcp-entries.js

@@ -0,0 +1,26 @@
+import { RUNWORK_MCP_PREFIX } from '../agents/types.js';
+/**
+ * Build local-agent MCP entries for external (third-party) servers added to the
+ * workspace. Auth handling by `authType`:
+ * - 'header': inject the user's resolved per-server headers (decrypted server-side).
+ * - 'oauth': emit no auth header so the local agent runs its own browser flow.
+ * - 'none'/unset: no auth header.
+ *
+ * Critically, external entries never receive the Runwork platform API key. That key
+ * belongs only on the Runwork workspace-tools entry, which is added separately.
+ */
+export function buildExternalMcpEntries(mcpServers, resolvedCredentials) {
+    return mcpServers
+        .filter(s => s.enabled)
+        .map(s => {
+        const resolved = s.authType === 'header' ? resolvedCredentials[s.id] : undefined;
+        const headers = resolved && Object.keys(resolved).length > 0 ? resolved : undefined;
+        return {
+            name: `${RUNWORK_MCP_PREFIX}${s.name}`,
+            url: s.url,
+            transport: s.transport,
+            ...(headers ? { headers } : {}),
+            description: `Runwork MCP server: ${s.name}. Provides tools for interacting with this workspace resource.`,
+        };
+    });
+}

package/dist/commands/sync.js

@@ -7,6 +7,7 @@ import { ApiClient } from '../api/client.js';
 import { getAdapterBySlug, detectAgents } from '../agents/detect.js';
 import { CodexAdapter } from '../agents/codex.js';
 import { RUNWORK_MCP_PREFIX, RUNWORK_WORKSPACE_MCP_NAME } from '../agents/types.js';
+import { buildExternalMcpEntries } from './mcp-entries.js';
 import { RUNWORK_AGENT_DEFAULTS, AGENT_DEFAULTS_SCHEMA_VERSION } from '../agents/default-config.js';
 import { resolveAgentDefaults } from '../agents/defaults-merge.js';
 import { collectTelemetryEvents, printTelemetryVerbose, summarizeTelemetryForDryRun, } from './sync-telemetry.js';
@@ -135,7 +136,7 @@ export async function syncFromState(state, statePath, credentials, opts) {
     }
     console.log('  Fetching workspace data...');
     // Fetch latest data (includeContent=true gets all skill content in one request)
-    const [allSkills, mcpServers, externalSkills, registries, connectedIntegrations] = await Promise.all([
+    const [allSkills, mcpServers, externalSkills, registries, connectedIntegrations, resolvedMcpCredentials] = await Promise.all([
         client.listWorkspaceSkills(state.workspaceId, true),
         client.listMcpServers(state.workspaceId),
         client.listExternalSkills(state.workspaceId),
@@ -143,6 +144,9 @@ export async function syncFromState(state, statePath, credentials, opts) {
         client.listConnectedIntegrations(state.workspaceId)
             .then(list => list.map(i => i.canonicalId ?? i.integrationId))
             .catch(() => []),
+        // Decrypted auth headers for header-auth servers, scoped to this user.
+        // Tolerate older backends that lack the endpoint.
+        client.resolveMcpCredentials(state.workspaceId).catch(() => ({})),
     ]);
     const appCount = allSkills.filter(s => s.type === 'app').length;
     const parts = [];
@@ -167,15 +171,7 @@ export async function syncFromState(state, statePath, credentials, opts) {
     }
     // Build MCP entries (pull-only)
     const baseUrl = credentials.baseUrl || 'https://runwork.ai';
-    const mcpEntries = mcpServers
-        .filter(s => s.enabled)
-        .map(s => ({
-        name: `${RUNWORK_MCP_PREFIX}${s.name}`,
-        url: s.url,
-        transport: s.transport,
-        headers: { Authorization: `Bearer ${credentials.apiKey}` },
-        description: `Runwork MCP server: ${s.name}. Provides tools for interacting with this workspace resource.`,
-    }));
+    const mcpEntries = buildExternalMcpEntries(mcpServers, resolvedMcpCredentials);
     mcpEntries.push({
         name: RUNWORK_WORKSPACE_MCP_NAME,
         url: `${baseUrl}/api/workspaces/${state.workspaceId}/mcp`,

package/dist/dev/__tests__/session.test.js

@@ -343,5 +343,65 @@ describe('session lifecycle primitives', () => {
             });
             expect(file.startedAt).toBe(12345);
         });
+        it('defaults noSync to false when omitted', () => {
+            const file = buildSessionFile({
+                pid: 1,
+                sessionId: 's',
+                appId: 'a',
+                previewUrl: '',
+                cliVersion: '0.0.0',
+                mode: 'foreground',
+                deps: { bootTime: () => 0 },
+            });
+            expect(file.noSync).toBe(false);
+        });
+        it('sets noSync when provided', () => {
+            const file = buildSessionFile({
+                pid: 1,
+                sessionId: 's',
+                appId: 'a',
+                previewUrl: '',
+                cliVersion: '0.0.0',
+                mode: 'foreground',
+                noSync: true,
+                deps: { bootTime: () => 0 },
+            });
+            expect(file.noSync).toBe(true);
+        });
+    });
+    describe('noSync field back-compat', () => {
+        it('round-trips noSync through write/read', () => {
+            const file = buildSessionFile({
+                pid: process.pid,
+                sessionId: 's',
+                appId: 'a',
+                previewUrl: 'https://x',
+                cliVersion: '0.0.0',
+                mode: 'detached',
+                noSync: true,
+                deps: { bootTime: () => 0 },
+            });
+            writeSessionFile(appDir, file);
+            expect(readSessionFile(appDir)?.noSync).toBe(true);
+        });
+        it('validates a v1-style file that lacks noSync and reads it back falsy', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            // v1 file shape: every required field present, no noSync key at all.
+            const v1 = makeValidSessionFile();
+            // makeValidSessionFile does not add noSync, so this is already v1-shaped.
+            expect('noSync' in v1).toBe(false);
+            fs.writeFileSync(file, JSON.stringify(v1), 'utf-8');
+            const read = readSessionFile(appDir);
+            expect(read).not.toBeNull();
+            expect(read?.noSync).toBeFalsy();
+        });
+        it('rejects a file whose noSync field is the wrong type', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            const bad = { ...makeValidSessionFile(), noSync: 'yes' };
+            fs.writeFileSync(file, JSON.stringify(bad), 'utf-8');
+            expect(readSessionFile(appDir)).toBeNull();
+        });
     });
 });

package/dist/dev/session.d.ts

@@ -33,6 +33,13 @@ export interface SessionFile {
     bootTime: number;
     cliVersion: string;
     mode: SessionMode;
+    /**
+     * Whether this session runs in no-sync mode (no file watcher, no
+     * auto-commit, no working-tree-mutating startup). Optional for
+     * back-compat with v1 session files that predate the field; absent is
+     * treated as `false`.
+     */
+    noSync?: boolean;
 }
 export type SessionStaleReason = 'malformed' | 'version-mismatch' | 'app-id-mismatch' | 'boot-time-mismatch' | 'pid-dead';
 export type SessionState = {
@@ -153,6 +160,7 @@ export declare function buildSessionFile(input: {
     previewUrl: string;
     cliVersion: string;
     mode: SessionMode;
+    noSync?: boolean;
     startedAt?: number;
     deps?: SessionDeps;
 }): SessionFile;

package/dist/dev/session.js

@@ -111,7 +111,9 @@ function validateSessionFile(raw) {
         typeof r.startedAt === 'number' &&
         typeof r.bootTime === 'number' &&
         typeof r.cliVersion === 'string' &&
-        (r.mode === 'foreground' || r.mode === 'detached'));
+        (r.mode === 'foreground' || r.mode === 'detached') &&
+        // Optional for back-compat: v1 files lack the field. Accept absent or boolean.
+        (r.noSync === undefined || typeof r.noSync === 'boolean'));
 }
 /**
  * Read and parse the session file. Returns `null` for a missing file or
@@ -248,5 +250,6 @@ export function buildSessionFile(input) {
         bootTime: d.bootTime(),
         cliVersion: input.cliVersion,
         mode: input.mode,
+        noSync: input.noSync ?? false,
     };
 }