runwork 0.10.3 → 0.11.0

package/dist/commands/sync.js

@@ -7,6 +7,8 @@ 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 { 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';
 import { generateIntroSkill, generateInstructionHint, buildAppSkillDescription } from '../agents/intro-skill.js';
 import { computeSyncPlan } from '../sync/change-detect.js';
@@ -346,85 +348,170 @@ export async function syncFromState(state, statePath, credentials, opts) {
             }
         }
     }
-    // Pull and apply team instructions from onboarding config (non-fatal)
+    // Pull team config from server. A failure here must not stop the
+    // unified user-scope write below, which applies network and minimum-permission
+    // floors regardless of whether team config was fetched.
     let teamInstructionsApplied = false;
     let agentConfigsApplied = 0;
+    let teamInstructions;
+    let agentConfigs;
     try {
         const onboardingConfig = await client.getOnboardingConfig(state.workspaceId);
-        const teamInstructions = onboardingConfig?.config?.teamInstructions;
-        const agentConfigs = onboardingConfig?.config?.agentConfigs;
-        // Write team instructions and/or per-agent extra instructions.
-        // Either or both may be present independently.
+        teamInstructions = onboardingConfig?.config?.teamInstructions ?? undefined;
+        agentConfigs = onboardingConfig?.config?.agentConfigs ?? undefined;
+    }
+    catch {
+        // Team config pull is non-fatal — proceed with no team-managed overrides.
+    }
+    // Write team instructions and/or per-agent extra instructions.
+    for (const adapter of adapters) {
+        if (!adapter.writeTeamInstructions)
+            continue;
+        const agentExtra = agentConfigs?.[adapter.slug]?.extraInstructions;
+        const parts = [teamInstructions, agentExtra].filter(Boolean);
+        if (parts.length === 0)
+            continue;
+        const fullInstructions = parts.join('\n\n');
+        for (const scope of scopes) {
+            try {
+                await adapter.writeTeamInstructions(fullInstructions, scope);
+                teamInstructionsApplied = true;
+                console.log(`  [${adapter.name}] Updated team instructions (${scope})`);
+            }
+            catch {
+                // Best-effort per adapter/scope
+            }
+        }
+    }
+    // Apply per-agent project-scope config (team overrides only).
+    // User scope is handled below in the unified defaults+network+minimum block.
+    if (agentConfigs) {
         for (const adapter of adapters) {
-            if (!adapter.writeTeamInstructions)
+            const agentConfig = agentConfigs[adapter.slug];
+            if (!agentConfig || !adapter.writeAgentConfig)
                 continue;
-            const agentExtra = agentConfigs?.[adapter.slug]?.extraInstructions;
-            const parts = [teamInstructions, agentExtra].filter(Boolean);
-            if (parts.length === 0)
+            const { extraInstructions: _, ...configWithoutInstructions } = agentConfig;
+            if (Object.keys(configWithoutInstructions).length === 0)
                 continue;
-            const fullInstructions = parts.join('\n\n');
             for (const scope of scopes) {
+                if (scope === 'user')
+                    continue; // handled in unified block below
                 try {
-                    await adapter.writeTeamInstructions(fullInstructions, scope);
-                    teamInstructionsApplied = true;
-                    console.log(`  [${adapter.name}] Updated team instructions (${scope})`);
+                    await adapter.writeAgentConfig(configWithoutInstructions, scope);
+                    agentConfigsApplied++;
+                    const configKeys = Object.keys(configWithoutInstructions).join(', ');
+                    console.log(`  [${adapter.name}] Updated agent config: ${configKeys} (${scope})`);
                 }
                 catch {
                     // Best-effort per adapter/scope
                 }
             }
         }
-        // Apply per-agent config overrides (model preferences, permissions)
-        if (agentConfigs) {
-            for (const adapter of adapters) {
-                const agentConfig = agentConfigs[adapter.slug];
-                if (!agentConfig || !adapter.writeAgentConfig)
-                    continue;
-                // Only apply model/permission config (extraInstructions already handled above)
-                const { extraInstructions: _, ...configWithoutInstructions } = agentConfig;
-                if (Object.keys(configWithoutInstructions).length === 0)
-                    continue;
-                for (const scope of scopes) {
-                    try {
-                        await adapter.writeAgentConfig(configWithoutInstructions, scope);
-                        agentConfigsApplied++;
-                        const configKeys = Object.keys(configWithoutInstructions).join(', ');
-                        console.log(`  [${adapter.name}] Updated agent config: ${configKeys} (${scope})`);
+    }
+    // Unified user-scope write: merge baked defaults with team config, network
+    // allowlist, and minimum permissions into a single writeAgentConfig call
+    // per adapter. The merge layer tracks injected defaults in state.agentDefaults
+    // so user-removed entries become sticky opt-outs.
+    if (scopes.includes('user')) {
+        const networkDomains = ['runwork.ai', '*.runwork.ai'];
+        try {
+            const baseHost = new URL(baseUrl).hostname;
+            if (baseHost !== 'runwork.ai' && !baseHost.endsWith('.runwork.ai')) {
+                networkDomains.push(baseHost, `*.${baseHost}`);
+            }
+        }
+        catch { /* use defaults */ }
+        // Order arrays list each agent's valid values from most restrictive to most
+        // permissive. The floor logic upgrades anything strictly below `minimum`,
+        // including unknown values (-1 < minimumIdx). That makes it critical to
+        // include the agent's most-permissive option in `order` — otherwise a user
+        // who explicitly set, say, `sandbox_mode = "danger-full-access"` gets
+        // silently downgraded to `workspace-write`.
+        const minimumPermissions = [
+            { field: 'approval_policy', order: ['untrusted', 'on-request', 'on-failure', 'never'], minimum: 'on-request' },
+            { field: 'sandbox_mode', order: ['read-only', 'workspace-write', 'danger-full-access'], minimum: 'workspace-write' },
+        ];
+        // agentDefaults lifecycle: full `runwork uninstall` deletes ~/.runwork
+        // (state and all per-agent defaults state with it). Re-running `runwork
+        // setup` overwrites setup.json without agentDefaults so every remaining
+        // tool bootstraps fresh on the next sync. refreshConfiguredAgents only
+        // adds slugs (never removes), so we don't need orphan-entry pruning here.
+        if (!state.agentDefaults)
+            state.agentDefaults = {};
+        for (const adapter of adapters) {
+            if (!adapter.writeAgentConfig)
+                continue;
+            const slug = adapter.slug;
+            const baked = RUNWORK_AGENT_DEFAULTS[slug];
+            const agentState = state.agentDefaults[slug];
+            const team = agentConfigs?.[slug];
+            // onDisk = undefined signals "removal detection is not possible" — used for
+            // markerless adapters (Cursor) and for any adapter without readManagedBlock.
+            // The resolver treats undefined differently from an empty array: it skips
+            // opt-out fabrication entirely and trusts the baseline mechanism in the
+            // adapter to preserve user edits via subtraction.
+            let onDisk;
+            if (baked && adapter.readManagedBlock) {
+                try {
+                    onDisk = await adapter.readManagedBlock('user');
+                }
+                catch {
+                    onDisk = undefined;
+                }
+            }
+            const resolved = resolveAgentDefaults({
+                baked,
+                state: agentState,
+                onDisk,
+                team: team?.permissionRules,
+            });
+            const mergedConfig = {
+                modelPreference: team?.modelPreference,
+                permissionRules: (resolved.managedAllow.length || resolved.managedDeny.length || team?.permissionRules?.defaultMode)
+                    ? {
+                        ...(resolved.managedAllow.length ? { allow: resolved.managedAllow } : {}),
+                        ...(resolved.managedDeny.length ? { deny: resolved.managedDeny } : {}),
+                        ...(team?.permissionRules?.defaultMode ? { defaultMode: team.permissionRules.defaultMode } : {}),
                     }
-                    catch {
-                        // Best-effort per adapter/scope
+                    : undefined,
+                networkAllowlist: networkDomains,
+                minimumPermissions,
+            };
+            try {
+                const baseline = agentState?.lastInjected;
+                await adapter.writeAgentConfig(mergedConfig, 'user', baseline);
+                if (baked) {
+                    const nextState = {
+                        lastInjected: {
+                            allow: resolved.applicableAllow,
+                            deny: resolved.applicableDeny,
+                        },
+                        userOptOuts: {
+                            allow: resolved.newOptOutsAllow,
+                            deny: resolved.newOptOutsDeny,
+                        },
+                    };
+                    state.agentDefaults[slug] = nextState;
+                    // Diagnostic log line (per "invisible / sync log only" policy)
+                    if (resolved.bootstrapped) {
+                        console.log(`  [${adapter.name}] Bootstrapped default-rule tracking (defaults apply on next sync)`);
+                    }
+                    else if (resolved.applicableAllow.length || resolved.applicableDeny.length || resolved.removalsThisSync.allow || resolved.removalsThisSync.deny) {
+                        const totalRemovals = resolved.removalsThisSync.allow + resolved.removalsThisSync.deny;
+                        const removalNote = totalRemovals > 0
+                            ? ` (${totalRemovals} new opt-out${totalRemovals > 1 ? 's' : ''} honored)`
+                            : '';
+                        console.log(`  [${adapter.name}] Applied defaults: ${resolved.applicableAllow.length} allow, ${resolved.applicableDeny.length} deny${removalNote}`);
                     }
                 }
+                if (team)
+                    agentConfigsApplied++;
+            }
+            catch {
+                // Best-effort per adapter
             }
         }
-    }
-    catch {
-        // Team config pull is non-fatal
-    }
-    // Ensure sandbox network access for agents that run in sandboxed environments (e.g. Cursor)
-    const networkDomains = ['runwork.ai', '*.runwork.ai'];
-    try {
-        const baseHost = new URL(baseUrl).hostname;
-        if (baseHost !== 'runwork.ai' && !baseHost.endsWith('.runwork.ai')) {
-            networkDomains.push(baseHost, `*.${baseHost}`);
-        }
-    }
-    catch { /* use defaults */ }
-    for (const adapter of adapters) {
-        if (!adapter.writeAgentConfig)
-            continue;
-        try {
-            await adapter.writeAgentConfig({
-                networkAllowlist: networkDomains,
-                minimumPermissions: [
-                    { field: 'approval_policy', order: ['always', 'untrusted', 'on-request', 'never'], minimum: 'on-request' },
-                    { field: 'sandbox_mode', order: ['full', 'read-only', 'workspace-write', 'off'], minimum: 'workspace-write' },
-                ],
-            }, 'user');
-        }
-        catch {
-            // Best-effort
-        }
+        state.agentDefaultsVersion = AGENT_DEFAULTS_SCHEMA_VERSION;
     }
     // Register ~/.runwork as a project in the Codex desktop app (best-effort).
     // Only attempts when Codex adapter is configured and the desktop app is closed.

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

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { pollForSession, runAsDetachedParent, isInternalDetachedChild, stripInternalChildFlag, INTERNAL_DETACHED_CHILD_FLAG, } from '../detach.js';
+import { buildChildArgs, pollForSession, runAsDetachedParent, isInternalDetachedChild, looksLikeBunStandaloneArtifact, stripInternalChildFlag, INTERNAL_DETACHED_CHILD_FLAG, } from '../detach.js';
 import { buildSessionFile, getSessionPaths, writeSessionFile, } from '../session.js';
 function createTmpAppDir() {
     return fs.mkdtempSync(path.join(os.tmpdir(), 'runwork-detach-test-'));
@@ -32,6 +32,82 @@ describe('isInternalDetachedChild() / stripInternalChildFlag()', () => {
         expect(stripInternalChildFlag(['dev', '--detach'])).toEqual(['dev', '--detach']);
     });
 });
+describe('looksLikeBunStandaloneArtifact()', () => {
+    it('detects Bun-on-Windows virtual-FS paths (forward slashes)', () => {
+        expect(looksLikeBunStandaloneArtifact('B:/~BUN/root/runwork-windows-x64.exe')).toBe(true);
+        expect(looksLikeBunStandaloneArtifact('C:/~BUN/root/foo.exe')).toBe(true);
+    });
+    it('detects Bun-on-Windows virtual-FS paths (backslashes)', () => {
+        expect(looksLikeBunStandaloneArtifact('B:\\~BUN\\root\\runwork.exe')).toBe(true);
+    });
+    it('detects bunfs prefix on POSIX (defensive)', () => {
+        expect(looksLikeBunStandaloneArtifact('/$bunfs/root/runwork')).toBe(true);
+    });
+    it('does not flag normal paths or arguments', () => {
+        expect(looksLikeBunStandaloneArtifact('dev')).toBe(false);
+        expect(looksLikeBunStandaloneArtifact('--detach')).toBe(false);
+        expect(looksLikeBunStandaloneArtifact('/usr/local/bin/runwork')).toBe(false);
+        expect(looksLikeBunStandaloneArtifact('C:/Users/Oytun/.runwork/bin/runwork.exe')).toBe(false);
+        expect(looksLikeBunStandaloneArtifact('node')).toBe(false);
+    });
+});
+describe('buildChildArgs()', () => {
+    it('Node script invocation: forwards script path + user args, appends marker', () => {
+        // node /path/to/dist/index.js dev --detach
+        const argv = ['node', '/path/to/dist/index.js', 'dev', '--detach'];
+        expect(buildChildArgs(argv)).toEqual([
+            '/path/to/dist/index.js', 'dev', '--detach', INTERNAL_DETACHED_CHILD_FLAG,
+        ]);
+    });
+    it('Bun standalone macOS/Linux: forwards user args directly', () => {
+        // /usr/local/bin/runwork dev --detach
+        const argv = ['/usr/local/bin/runwork', 'dev', '--detach'];
+        expect(buildChildArgs(argv)).toEqual([
+            'dev', '--detach', INTERNAL_DETACHED_CHILD_FLAG,
+        ]);
+    });
+    it('Bun standalone Windows: drops the virtual-FS argv[1] before forwarding', () => {
+        // The exact failure from the field. Bun-on-Windows injects argv[1]
+        // = "B:/~BUN/root/runwork-windows-x64.exe". We must NOT forward it
+        // -- the child Bun runtime will inject its own.
+        const argv = [
+            'C:\\Users\\Oytun\\.runwork\\bin\\runwork.exe',
+            'B:/~BUN/root/runwork-windows-x64.exe',
+            'dev',
+            '--detach',
+        ];
+        expect(buildChildArgs(argv)).toEqual([
+            'dev', '--detach', INTERNAL_DETACHED_CHILD_FLAG,
+        ]);
+    });
+    it('strips an existing internal-child flag and re-adds exactly one', () => {
+        const argv = [
+            '/usr/local/bin/runwork',
+            'dev',
+            '--detach',
+            INTERNAL_DETACHED_CHILD_FLAG,
+            INTERNAL_DETACHED_CHILD_FLAG,
+        ];
+        const out = buildChildArgs(argv);
+        expect(out.filter((a) => a === INTERNAL_DETACHED_CHILD_FLAG)).toHaveLength(1);
+    });
+    it('preserves the order of user args and only mutates argv[0..1]', () => {
+        const argv = [
+            'C:\\bin\\runwork.exe',
+            'B:/~BUN/root/runwork-windows-x64.exe',
+            'dev',
+            '--restart',
+            '--detach',
+            '--json',
+        ];
+        expect(buildChildArgs(argv)).toEqual([
+            'dev', '--restart', '--detach', '--json', INTERNAL_DETACHED_CHILD_FLAG,
+        ]);
+    });
+    it('handles an empty argv tail (just the binary)', () => {
+        expect(buildChildArgs(['runwork'])).toEqual([INTERNAL_DETACHED_CHILD_FLAG]);
+    });
+});
 describe('pollForSession()', () => {
     let appDir;
     beforeEach(() => {

package/dist/dev/detach.d.ts

@@ -162,3 +162,26 @@ export declare function isInternalDetachedChild(argv?: readonly string[]): boole
  * misconfigured wrapper).
  */
 export declare function stripInternalChildFlag(args: readonly string[]): string[];
+/**
+ * Detect a Bun standalone virtual-filesystem path. Bun's compile mode
+ * on Windows injects the in-bundle script path as `process.argv[1]`
+ * (e.g., `B:/~BUN/root/runwork-windows-x64.exe`). When we self-spawn,
+ * the child Bun runtime re-injects an equivalent entry on its own --
+ * forwarding ours causes a duplicate that downstream parsers (commander
+ * here) misread as a stray positional command. macOS and Linux Bun
+ * standalone do NOT inject this entry, but the prefix is documented in
+ * Bun source as `/$bunfs/` if it ever appears, so we detect that too
+ * defensively.
+ */
+export declare function looksLikeBunStandaloneArtifact(p: string): boolean;
+/**
+ * Construct the args we should forward to the spawned child so it
+ * re-runs the same `runwork dev` invocation as the parent. Drops
+ * elements that the child runtime will re-inject on its own (notably
+ * the Bun-on-Windows virtual-FS path) and drops any pre-existing copy
+ * of the internal-child marker before we re-add exactly one.
+ *
+ * Pure function for testability -- accepts the parent's argv and returns
+ * what to hand to `spawn`. Real callers pass `process.argv`.
+ */
+export declare function buildChildArgs(parentArgv: readonly string[]): string[];

package/dist/dev/detach.js

@@ -245,3 +245,48 @@ export function isInternalDetachedChild(argv = process.argv) {
 export function stripInternalChildFlag(args) {
     return args.filter((a) => a !== INTERNAL_DETACHED_CHILD_FLAG);
 }
+/**
+ * Detect a Bun standalone virtual-filesystem path. Bun's compile mode
+ * on Windows injects the in-bundle script path as `process.argv[1]`
+ * (e.g., `B:/~BUN/root/runwork-windows-x64.exe`). When we self-spawn,
+ * the child Bun runtime re-injects an equivalent entry on its own --
+ * forwarding ours causes a duplicate that downstream parsers (commander
+ * here) misread as a stray positional command. macOS and Linux Bun
+ * standalone do NOT inject this entry, but the prefix is documented in
+ * Bun source as `/$bunfs/` if it ever appears, so we detect that too
+ * defensively.
+ */
+export function looksLikeBunStandaloneArtifact(p) {
+    // Windows: drive-letter paths under \~BUN\, e.g. "B:/~BUN/root/..." or "B:\~BUN\root\..."
+    if (/^[a-z]:[/\\]~BUN[/\\]/i.test(p))
+        return true;
+    // Linux/macOS bunfs prefix (documented; not currently emitted in user-visible argv).
+    if (p.startsWith('/$bunfs/'))
+        return true;
+    return false;
+}
+/**
+ * Construct the args we should forward to the spawned child so it
+ * re-runs the same `runwork dev` invocation as the parent. Drops
+ * elements that the child runtime will re-inject on its own (notably
+ * the Bun-on-Windows virtual-FS path) and drops any pre-existing copy
+ * of the internal-child marker before we re-add exactly one.
+ *
+ * Pure function for testability -- accepts the parent's argv and returns
+ * what to hand to `spawn`. Real callers pass `process.argv`.
+ */
+export function buildChildArgs(parentArgv) {
+    // argv[0] is always the binary; the child gets it back via spawn's
+    // execPath argument. We start scanning from argv[1].
+    const rest = [];
+    for (let i = 1; i < parentArgv.length; i++) {
+        if (i === 1 && looksLikeBunStandaloneArtifact(parentArgv[i])) {
+            // Skip Bun-on-Windows's auto-injected virtual-FS path; the child
+            // runtime injects its own equivalent entry. Forwarding ours would
+            // duplicate it in the child's argv.
+            continue;
+        }
+        rest.push(parentArgv[i]);
+    }
+    return [...stripInternalChildFlag(rest), INTERNAL_DETACHED_CHILD_FLAG];
+}

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.10.3";
+export declare const VERSION = "0.11.0";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/embed-types.ts -- do not edit
-export const VERSION = "0.10.3";
+export const VERSION = "0.11.0";

package/dist/git/__tests__/credentials.test.js

@@ -60,7 +60,7 @@ describe('git/credentials', () => {
                 '--global',
                 '--unset',
                 'credential.https://runwork.ai.helper',
-            ], { stdio: 'pipe' });
+            ], { stdio: 'pipe', windowsHide: true });
         });
         it('ignores errors silently', async () => {
             mockExecFileSync.mockImplementation(() => {

package/dist/git/auto-commit.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 import { readFileSync } from 'fs';
 import { watch } from 'chokidar';
 import { join, relative } from 'path';

package/dist/git/credentials.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 import { getCredentials } from '../auth/store.js';
 /**
  * Build the value we hand to `git config credential.<origin>.helper`.

package/dist/git/identity.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 /**
  * Default identity used when we cannot derive anything better from the
  * authenticated credentials. Local-scoped, never written to global config,

package/dist/git/preflight.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 import { existsSync } from 'fs';
 import { win32 as winPath } from 'path';
 import { homedir } from 'os';

package/dist/git/sync.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 import { unlinkSync } from 'fs';
 import { join } from 'path';
 export function hasCommits(cwd) {

package/dist/health/checks.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 import { existsSync, readFileSync } from 'fs';
 import { join, sep } from 'path';
 import { homedir, platform as osPlatform, arch as osArch } from 'os';

package/dist/template/manifest.js

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { execFileSync } from 'child_process';
+import { execFileSync } from '../utils/subprocess.js';
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
 import { join, relative } from 'path';
 import { buildIgnoreSets } from '../utils/ignore-matcher.js';

package/dist/types.d.ts

@@ -121,6 +121,25 @@ export interface McpServerConfig {
     lastConnectedAt?: number;
     toolCount?: number;
 }
+/**
+ * Per-agent state tracking baked-in default permission rules that the CLI
+ * injects automatically during sync, with sticky opt-out semantics.
+ *
+ * lastInjected: what we wrote on the previous sync (used to detect when the
+ *   user removed an entry from the agent's config file).
+ * userOptOuts: ever-accumulating set of entries the user has removed at least
+ *   once. Never re-injected until the tool is removed entirely.
+ */
+export interface AgentDefaultsState {
+    lastInjected: {
+        allow?: string[];
+        deny?: string[];
+    };
+    userOptOuts: {
+        allow?: string[];
+        deny?: string[];
+    };
+}
 export interface SetupState {
     workspaceId: string;
     workspaceName: string;
@@ -147,6 +166,10 @@ export interface SetupState {
      * on every cycle while still catching newly-installed agents within a day.
      */
     lastDetectedAt?: string;
+    /** Schema version for agentDefaults; absence means bootstrap on next sync. */
+    agentDefaultsVersion?: number;
+    /** Per-agent slug => default rule state. Absence of an entry means bootstrap. */
+    agentDefaults?: Record<string, AgentDefaultsState>;
 }
 export interface WorkflowInfo {
     name: string;

package/dist/ui/banner.js

@@ -10,9 +10,9 @@ function prettyPath(dir) {
     return dir;
 }
 export const SUPPORTED_AGENTS = [
+    { id: 'codex', name: 'OpenAI Codex', command: 'cd {dir} && codex' },
     { id: 'claude-code', name: 'Claude Code', command: 'cd {dir} && claude' },
     { id: 'cursor', name: 'Cursor', command: 'cursor {dir}' },
-    { id: 'codex', name: 'OpenAI Codex', command: 'cd {dir} && codex' },
     { id: 'claude-desktop', name: 'Claude Desktop', command: 'Open Claude Desktop and add {dir} as a project folder' },
     { id: 'antigravity', name: 'Antigravity', command: 'cd {dir} && antigravity' },
 ];

package/dist/utils/agent-guidance.d.ts

@@ -24,6 +24,19 @@ export interface AgentResponse<T> {
 }
 /** Map of key template files and what they're for. */
 export declare const APP_STRUCTURE: Record<string, string>;
+/**
+ * The single most important workflow rule for AI agents working on a
+ * Runwork app. Repeated across multiple guides because it's the
+ * difference between a working dev cycle and a frustrating one.
+ *
+ * Rationale -- agents that don't follow this end up:
+ *   1. Editing files locally with no preview to verify against.
+ *   2. Hitting a single bulk-sync at dev startup that masks which
+ *      change broke what (instead of incremental per-change syncs).
+ *   3. Risking sync conflicts when the local state has diverged from
+ *      the remote in a way the auto-sync can't reconcile.
+ */
+export declare const DEV_FIRST_RULE = "CRITICAL: Always start `runwork dev --detach` BEFORE editing any code in this app. Dev establishes the live sync pipeline -- without it, changes do not flow to the preview, and the dev startup will batch-sync everything at once instead of giving you per-change feedback. To check whether dev is already running for this app, run `runwork info --json` and inspect `localDevSession.state` (alive / stale / none). If alive, just edit. If none or stale, run `runwork dev --detach --json` first, capture the preview URL from the `session_started` event, then proceed with edits.";
 export declare function buildInitGuide(appName: string, dir: string): AgentGuide;
 export declare function buildCloneGuide(appName: string, dir: string): AgentGuide;
 export declare function buildDevSessionGuide(): AgentGuide;

package/dist/utils/agent-guidance.js

@@ -18,7 +18,21 @@ export const APP_STRUCTURE = {
     'blueprint.json': 'App feature registry. Update after adding entities, workflows, agents, etc.',
     'CLAUDE.md': 'Complete framework documentation. Read this before editing anything.',
 };
+/**
+ * The single most important workflow rule for AI agents working on a
+ * Runwork app. Repeated across multiple guides because it's the
+ * difference between a working dev cycle and a frustrating one.
+ *
+ * Rationale -- agents that don't follow this end up:
+ *   1. Editing files locally with no preview to verify against.
+ *   2. Hitting a single bulk-sync at dev startup that masks which
+ *      change broke what (instead of incremental per-change syncs).
+ *   3. Risking sync conflicts when the local state has diverged from
+ *      the remote in a way the auto-sync can't reconcile.
+ */
+export const DEV_FIRST_RULE = 'CRITICAL: Always start `runwork dev --detach` BEFORE editing any code in this app. Dev establishes the live sync pipeline -- without it, changes do not flow to the preview, and the dev startup will batch-sync everything at once instead of giving you per-change feedback. To check whether dev is already running for this app, run `runwork info --json` and inspect `localDevSession.state` (alive / stale / none). If alive, just edit. If none or stale, run `runwork dev --detach --json` first, capture the preview URL from the `session_started` event, then proceed with edits.';
 const COMMON_TIPS = [
+    DEV_FIRST_RULE,
     'Read CLAUDE.md in the app directory first -- it has complete framework documentation with code examples.',
     'You do NOT need to run git commands manually. runwork dev handles file syncing automatically. (git itself must be installed on the system -- see dependencies.)',
     'Do NOT install external AI SDKs (openai, @anthropic-ai/sdk). Use @runworkai/framework/ai instead.',
@@ -39,8 +53,8 @@ export function buildInitGuide(appName, dir) {
         structure: APP_STRUCTURE,
         nextSteps: [
             `cd ${dir}`,
-            'runwork dev  # start development server -- watches for file changes and syncs automatically',
-            'Edit files for your needs (see structure above)',
+            'runwork dev --detach --json  # FIRST: start the dev sandbox in the background; capture the preview URL from the session_started event',
+            'THEN edit files for your needs (see structure above) -- changes auto-sync to the preview',
             'runwork deploy  # deploy to production when ready',
         ],
         tips: COMMON_TIPS,
@@ -53,9 +67,9 @@ export function buildCloneGuide(appName, dir) {
         structure: APP_STRUCTURE,
         nextSteps: [
             `cd ${dir}`,
-            'runwork dev  # start development server',
+            'runwork dev --detach --json  # FIRST: start dev in the background, capture the preview URL',
             'Review existing files to understand what is already built',
-            'Edit files for your needs',
+            'THEN edit files for your needs -- changes auto-sync to the preview',
             'runwork deploy  # deploy to production when ready',
         ],
         tips: [SYSTEM_DEPENDENCIES_NOTE, ...COMMON_TIPS],
@@ -89,17 +103,18 @@ export function buildDeployGuide() {
 }
 export function buildInfoGuide() {
     return {
-        context: 'This shows the current state of the app: what is deployed, what integrations are connected, and what resources (entities, workflows, agents, etc.) are registered.',
+        context: 'This shows the current state of the app: what is deployed, what integrations are connected, and what resources (entities, workflows, agents, etc.) are registered. The `localDevSession` field tells you whether a dev session is already running on this machine -- check it BEFORE starting a new one.',
         nextSteps: [
-            'runwork dev  # start development server if not already running',
+            'If localDevSession.state == "alive": dev is already running. Use the URL in localDevSession.previewUrl and proceed with edits.',
+            'If localDevSession.state == "none" or "stale": run `runwork dev --detach --json` BEFORE editing any code. Capture the preview URL from the session_started event.',
             'runwork deploy  # deploy to production when ready',
         ],
         tips: [
+            DEV_FIRST_RULE,
             'Entities listed here are the data models available via Entity CRUD methods.',
             'Workflows listed here can be triggered via their registered endpoints or schedules.',
             'Agents listed here need frontend pages (conversational) or triggers (task) to be accessible.',
             'Integrations with connected status are ready to use. Others need setup in workspace settings.',
-            'If preview is not active, run runwork dev to start a development session.',
         ],
     };
 }

package/dist/utils/subprocess.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thin wrappers around `child_process.execFileSync` and `spawn` that
+ * default `windowsHide: true`. On Windows, every console-subsystem
+ * subprocess we spawn (git, where.exe, registry queries) creates its
+ * own console window unless this flag is set. With our hot paths --
+ * auto-commit's git invocations, manifest's `git ls-files`, the sync
+ * loop's git rebase / fetch / push -- a missing flag visibly flashes a
+ * console window every few seconds, which Codex Desktop users see as
+ * "empty terminals keep popping up."
+ *
+ * Use these as drop-in replacements for the `child_process` exports.
+ * Existing options the caller passes still win (so you can opt back to
+ * `windowsHide: false` if you genuinely need the window, e.g. for
+ * interactive prompts -- though we don't have any of those in our
+ * subprocess paths today).
+ */
+import { execFileSync as cpExecFileSync, spawn as cpSpawn } from 'child_process';
+export declare const execFileSync: typeof cpExecFileSync;
+export declare const spawn: typeof cpSpawn;