runwork 0.10.2 → 0.10.4

package/dist/dev/session.js

@@ -0,0 +1,252 @@
+/**
+ * Per-app `runwork dev` session lifecycle primitives.
+ *
+ * The session file at `<app-dir>/.runwork/dev-session.json` is the durable
+ * truth about whether a dev session is running for the current app, on the
+ * current machine. Every dev-related command reads from it, writes to it,
+ * or treats it as the IPC channel during detach.
+ *
+ * This module is intentionally pure: it does not start, stop, or signal
+ * processes. It only reads/writes the file and reports whether what it
+ * finds is alive, stale, or absent. Callers (dev.ts, dev stop, etc.) act
+ * on that information.
+ *
+ * See `docs/plans/2026-05-06-runwork-dev-lifecycle-design.md` for the full
+ * lifecycle contract.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+export const SESSION_FILE_SCHEMA_VERSION = 1;
+/**
+ * Tolerance (ms) when comparing the stored bootTime to the currently
+ * computed one. NTP corrections can shift `Date.now()` by a few seconds
+ * relative to `os.uptime()`. A reboot is always orders of magnitude
+ * larger than this tolerance.
+ */
+export const BOOT_TIME_TOLERANCE_MS = 60_000;
+const realDeps = {
+    bootTime: currentBootTime,
+    pidAlive: isPidAlive,
+};
+/**
+ * Resolve a `SessionDeps` against the real defaults, ignoring any
+ * `undefined` values in the caller-supplied object. Spreading
+ * `{ ...realDeps, ...deps }` directly would let `{ bootTime: undefined }`
+ * overwrite the real default with `undefined`, which then crashes when we
+ * try to call it. This helper keeps the defaults intact.
+ */
+function resolveDeps(deps) {
+    if (!deps)
+        return realDeps;
+    return {
+        bootTime: deps.bootTime ?? realDeps.bootTime,
+        pidAlive: deps.pidAlive ?? realDeps.pidAlive,
+    };
+}
+export function getSessionPaths(appDir) {
+    const dir = path.join(appDir, '.runwork');
+    return {
+        dir,
+        file: path.join(dir, 'dev-session.json'),
+        tmpFile: path.join(dir, 'dev-session.json.tmp'),
+        stdoutLog: path.join(dir, 'dev-stdout.log'),
+        stderrLog: path.join(dir, 'dev-stderr.log'),
+    };
+}
+/**
+ * System boot timestamp in ms. Computed purely from Node's `os.uptime()`
+ * (monotonic seconds since boot, available on every platform Node runs
+ * on) and the wall clock. No spawning, no native modules.
+ *
+ * Drift between `Date.now()` and `os.uptime()` from NTP corrections is
+ * absorbed by `BOOT_TIME_TOLERANCE_MS` at the comparison site.
+ */
+export function currentBootTime() {
+    return Date.now() - os.uptime() * 1000;
+}
+export function isBootTimeStale(stored, deps = {}) {
+    const d = resolveDeps(deps);
+    return Math.abs(d.bootTime() - stored) > BOOT_TIME_TOLERANCE_MS;
+}
+/**
+ * Cross-platform PID liveness probe.
+ *
+ *   - Unix: `process.kill(pid, 0)` is signal-zero, a permissions+existence
+ *     probe. ESRCH for dead, EPERM for "alive but not ours."
+ *   - Windows: Node maps signal 0 to `OpenProcess(PROCESS_QUERY_LIMITED_-`
+ *     `INFORMATION)`. Returns success iff the PID exists and the caller
+ *     has rights, throws otherwise.
+ *
+ * On any error we return `false`. EPERM in particular ("alive but
+ * unprivileged") means the PID belongs to someone else now, so it's not
+ * our session even if it's a real process. The bootTime guard catches the
+ * rare "PID got reused after a reboot, we still own it" case.
+ */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate that a parsed value matches `SessionFile`. Catches schema drift,
+ * truncated writes, and tampered files. Anything other than a perfect match
+ * is reported as `malformed` -- we don't try to repair partial files.
+ */
+function validateSessionFile(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const r = raw;
+    return (typeof r.version === 'number' &&
+        typeof r.pid === 'number' &&
+        typeof r.sessionId === 'string' &&
+        typeof r.appId === 'string' &&
+        typeof r.previewUrl === 'string' &&
+        typeof r.startedAt === 'number' &&
+        typeof r.bootTime === 'number' &&
+        typeof r.cliVersion === 'string' &&
+        (r.mode === 'foreground' || r.mode === 'detached'));
+}
+/**
+ * Read and parse the session file. Returns `null` for a missing file or
+ * any IO/parse error. The caller decides what "missing" vs "malformed"
+ * means -- use `getSessionState()` for that distinction.
+ */
+export function readSessionFile(appDir) {
+    const { file } = getSessionPaths(appDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!validateSessionFile(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * Write the session file atomically. Writes to `<file>.tmp` first then
+ * renames into place. POSIX `rename()` and Windows `MoveFileEx` are both
+ * atomic on the same volume, which a sibling temp file always is.
+ *
+ * Creates `.runwork/` if it doesn't exist. The directory is gitignored at
+ * the project-template level.
+ */
+export function writeSessionFile(appDir, data) {
+    const paths = getSessionPaths(appDir);
+    fs.mkdirSync(paths.dir, { recursive: true });
+    // We hold the JSON in memory before writing, so a serialization error
+    // never leaves a half-written tmp file on disk.
+    const json = JSON.stringify(data, null, 2);
+    fs.writeFileSync(paths.tmpFile, json, { encoding: 'utf-8' });
+    fs.renameSync(paths.tmpFile, paths.file);
+}
+/**
+ * Conditional removal: only deletes the session file when its `pid`
+ * field matches the caller's. Use this from per-process cleanup paths
+ * where another process (e.g., the winner of a startup race) may have
+ * overwritten the file with a different owner. Returns `true` when we
+ * actually removed it.
+ *
+ * `removeSessionFile` is the unconditional primitive; this is the
+ * "be-a-good-citizen" wrapper for in-process cleanup handlers.
+ */
+export function removeSessionFileIfOwned(appDir, pid) {
+    const file = readSessionFile(appDir);
+    if (!file)
+        return false;
+    if (file.pid !== pid)
+        return false;
+    removeSessionFile(appDir);
+    return true;
+}
+/**
+ * Idempotent removal. Missing file is not an error. We also clear any
+ * leftover temp file from a crashed mid-write -- those aren't load-bearing
+ * but they're noise and they confuse `ls -la .runwork/`.
+ */
+export function removeSessionFile(appDir) {
+    const { file, tmpFile } = getSessionPaths(appDir);
+    for (const p of [file, tmpFile]) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            // ENOENT is the happy path; any other error is also intentionally
+            // swallowed -- removal is best-effort cleanup, not a load-bearing
+            // step. The next `runwork dev` will detect a stale file via the
+            // PID/bootTime checks regardless.
+        }
+    }
+}
+/**
+ * Determine the live state of the session file in the given app directory.
+ *
+ * Checks are ordered cheap-to-expensive. The `pidAlive` syscall is last
+ * so a malformed or wrong-version file short-circuits before we touch
+ * the OS at all.
+ *
+ *   1. File missing                    -> `none`
+ *   2. File malformed / truncated      -> `stale: malformed`
+ *   3. Schema version mismatch         -> `stale: version-mismatch`
+ *   4. App ID mismatch                 -> `stale: app-id-mismatch`
+ *   5. Boot time outside tolerance     -> `stale: boot-time-mismatch`
+ *   6. PID not alive                   -> `stale: pid-dead`
+ *   7. Otherwise                       -> `alive`
+ */
+export function getSessionState(appDir, expectedAppId, deps = {}) {
+    const { file: filePath } = getSessionPaths(appDir);
+    if (!fs.existsSync(filePath))
+        return { state: 'none' };
+    const file = readSessionFile(appDir);
+    if (!file)
+        return { state: 'stale', reason: 'malformed' };
+    if (file.version !== SESSION_FILE_SCHEMA_VERSION) {
+        return { state: 'stale', reason: 'version-mismatch', file };
+    }
+    if (file.appId !== expectedAppId) {
+        return { state: 'stale', reason: 'app-id-mismatch', file };
+    }
+    if (isBootTimeStale(file.bootTime, deps)) {
+        return { state: 'stale', reason: 'boot-time-mismatch', file };
+    }
+    const d = resolveDeps(deps);
+    if (!d.pidAlive(file.pid)) {
+        return { state: 'stale', reason: 'pid-dead', file };
+    }
+    return { state: 'alive', file };
+}
+/**
+ * Convenience constructor for a fresh session file. Fills in version,
+ * startedAt, and bootTime from the runtime; everything else is supplied
+ * by the caller. Test code can pass a `deps.bootTime` override to inject
+ * a deterministic value.
+ */
+export function buildSessionFile(input) {
+    const d = resolveDeps(input.deps);
+    return {
+        version: SESSION_FILE_SCHEMA_VERSION,
+        pid: input.pid,
+        sessionId: input.sessionId,
+        appId: input.appId,
+        previewUrl: input.previewUrl,
+        startedAt: input.startedAt ?? Date.now(),
+        bootTime: d.bootTime(),
+        cliVersion: input.cliVersion,
+        mode: input.mode,
+    };
+}

package/dist/dev/stop.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stop a running dev session, identified by the on-disk session file.
+ *
+ * Termination is platform-aware but the design does NOT depend on the
+ * child's cleanup handler running. We always remove the session file
+ * ourselves at the end so the next `runwork dev` invocation sees a clean
+ * slate even on Windows (no SIGTERM equivalent) or on a kill-9'd Unix
+ * process.
+ */
+import { type SessionDeps, type SessionStaleReason } from './session.js';
+export type StopOutcome = {
+    result: 'no-session';
+} | {
+    result: 'stale-cleaned';
+    reason: SessionStaleReason;
+    pid?: number;
+} | {
+    result: 'stopped';
+    pid: number;
+    gracefully: boolean;
+} | {
+    result: 'kill-failed';
+    pid: number;
+    error: unknown;
+};
+export interface StopDeps extends SessionDeps {
+    killProcess?: (pid: number, signal?: NodeJS.Signals | 0) => void;
+    sleep?: (ms: number) => Promise<void>;
+    platform?: NodeJS.Platform;
+    /**
+     * Maximum total time to wait for the SIGTERM'd child to exit gracefully
+     * before falling back to SIGKILL. Unix-only; ignored on Windows.
+     */
+    graceTimeoutMs?: number;
+    /** Polling interval while waiting for the process to die. */
+    pollIntervalMs?: number;
+}
+/**
+ * Stop a dev session that may or may not exist for the given app dir.
+ *
+ *   - `state: 'none'`  -> exit-code-0 no-op, no session to stop.
+ *   - `state: 'stale'` -> remove the file, no kill needed (the PID is
+ *     either dead, mismatched, or a different app altogether).
+ *   - `state: 'alive'` -> Unix: SIGTERM, wait up to graceTimeoutMs,
+ *     SIGKILL fallback. Windows: TerminateProcess (signal-less kill);
+ *     Node has no graceful-shutdown signal that survives the cross-process
+ *     boundary on Windows.
+ *
+ * In every "found a file" path the file is removed before returning, so
+ * the next `runwork dev` sees a clean slate regardless of how things went.
+ */
+export declare function stopSession(appDir: string, expectedAppId: string, deps?: StopDeps): Promise<StopOutcome>;

package/dist/dev/stop.js

@@ -0,0 +1,101 @@
+/**
+ * Stop a running dev session, identified by the on-disk session file.
+ *
+ * Termination is platform-aware but the design does NOT depend on the
+ * child's cleanup handler running. We always remove the session file
+ * ourselves at the end so the next `runwork dev` invocation sees a clean
+ * slate even on Windows (no SIGTERM equivalent) or on a kill-9'd Unix
+ * process.
+ */
+import { getSessionPaths, getSessionState, isPidAlive as defaultIsPidAlive, removeSessionFile, } from './session.js';
+import * as fs from 'fs';
+const defaultStopDeps = {
+    killProcess: (pid, signal) => {
+        process.kill(pid, signal);
+    },
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    platform: process.platform,
+    graceTimeoutMs: 5_000,
+    pollIntervalMs: 100,
+};
+/**
+ * Stop a dev session that may or may not exist for the given app dir.
+ *
+ *   - `state: 'none'`  -> exit-code-0 no-op, no session to stop.
+ *   - `state: 'stale'` -> remove the file, no kill needed (the PID is
+ *     either dead, mismatched, or a different app altogether).
+ *   - `state: 'alive'` -> Unix: SIGTERM, wait up to graceTimeoutMs,
+ *     SIGKILL fallback. Windows: TerminateProcess (signal-less kill);
+ *     Node has no graceful-shutdown signal that survives the cross-process
+ *     boundary on Windows.
+ *
+ * In every "found a file" path the file is removed before returning, so
+ * the next `runwork dev` sees a clean slate regardless of how things went.
+ */
+export async function stopSession(appDir, expectedAppId, deps = {}) {
+    const d = { ...defaultStopDeps, ...deps };
+    // StopDeps extends SessionDeps, so we can pass `deps` straight through
+    // to getSessionState. Constructing a separate `{ bootTime, pidAlive }`
+    // object would smuggle in `undefined` values when the caller didn't
+    // override them, which then overwrite the real defaults in getSessionState's
+    // own spread. Forwarding the object as-is keeps the defaults intact.
+    const state = getSessionState(appDir, expectedAppId, deps);
+    if (state.state === 'none') {
+        return { result: 'no-session' };
+    }
+    if (state.state === 'stale') {
+        removeSessionFile(appDir);
+        return { result: 'stale-cleaned', reason: state.reason, pid: state.file?.pid };
+    }
+    const { file } = state;
+    const pid = file.pid;
+    // Unix: SIGTERM, wait, SIGKILL fallback.
+    // Windows: signal-less kill (== TerminateProcess via Node).
+    const isWindows = d.platform === 'win32';
+    const livenessProbe = deps.pidAlive ?? defaultIsPidAlive;
+    try {
+        if (isWindows) {
+            d.killProcess(pid);
+        }
+        else {
+            d.killProcess(pid, 'SIGTERM');
+        }
+    }
+    catch (err) {
+        // Even if the kill failed (PID died between state-read and kill, or
+        // permission denied), we still want to remove the file so the user
+        // isn't stuck. Surface the error as a warning-grade outcome, but
+        // clean up.
+        removeSessionFile(appDir);
+        return { result: 'kill-failed', pid, error: err };
+    }
+    let gracefully = false;
+    if (!isWindows) {
+        const deadline = Date.now() + d.graceTimeoutMs;
+        while (Date.now() < deadline) {
+            if (!livenessProbe(pid)) {
+                gracefully = true;
+                break;
+            }
+            // The child cleans up its own session file on SIGTERM, so the file
+            // disappearing is also an acceptable "we're done" signal.
+            if (!fs.existsSync(getSessionPaths(appDir).file)) {
+                gracefully = true;
+                break;
+            }
+            await d.sleep(d.pollIntervalMs);
+        }
+        if (!gracefully) {
+            try {
+                d.killProcess(pid, 'SIGKILL');
+            }
+            catch {
+                // Already dead, race-condition'd, or no permission. Either way,
+                // we proceed to remove the file -- the goal is "this session is
+                // gone from this machine's perspective."
+            }
+        }
+    }
+    removeSessionFile(appDir);
+    return { result: 'stopped', pid, gracefully };
+}

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.10.2";
+export declare const VERSION = "0.10.4";

package/dist/generated/version.js

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

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/ui/__tests__/keyboard.test.js

@@ -27,4 +27,8 @@ describe('parseKeypress', () => {
     it('detects "i" for info', () => {
         expect(parseKeypress(Buffer.from('i'))).toBe('i');
     });
+    it('detects "s" for stop (used by `runwork dev attach`)', () => {
+        expect(parseKeypress(Buffer.from('s'))).toBe('s');
+        expect(parseKeypress(Buffer.from('S'))).toBe('s');
+    });
 });

package/dist/ui/keyboard.d.ts

@@ -1,4 +1,4 @@
-export type KeyAction = 'o' | 'p' | 'a' | 'e' | 'r' | 'i' | 'quit' | null;
+export type KeyAction = 'o' | 'p' | 'a' | 'e' | 'r' | 'i' | 's' | 'quit' | null;
 /** Parse a raw stdin buffer into a named action. */
 export declare function parseKeypress(data: Buffer): KeyAction;
 export interface KeyboardListener {

package/dist/ui/keyboard.js

@@ -12,6 +12,10 @@ export function parseKeypress(data) {
             case 'e': return 'e';
             case 'r': return 'r';
             case 'i': return 'i';
+            // 's' is consumed by `runwork dev attach` to stop the attached
+            // session. Other commands ignore it. We parse it centrally so the
+            // raw keypress doesn't leak through as a `null` action.
+            case 's': return 's';
             case 'q': return 'quit';
             default: return null;
         }

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;

package/dist/utils/subprocess.js

@@ -0,0 +1,27 @@
+/**
+ * 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';
+// We re-export with the *exact* `typeof` signature of the originals so
+// caller-side overload narrowing (encoding -> string vs Buffer return
+// type) keeps working. The implementation forwards through the original
+// after merging in `windowsHide: true` as a default.
+export const execFileSync = ((file, args, options) => {
+    return cpExecFileSync(file, args, { windowsHide: true, ...(options ?? {}) });
+});
+export const spawn = ((command, args, options) => {
+    return cpSpawn(command, args ?? [], { windowsHide: true, ...(options ?? {}) });
+});

package/dist/utils/which.js

@@ -1,4 +1,4 @@
-import { execFileSync } from 'child_process';
+import { execFileSync } from './subprocess.js';
 import { platform } from 'os';
 /**
  * Cross-platform binary detection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runwork",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "CLI for Runwork: develop, preview, and deploy Runwork apps from your local machine.",
   "license": "UNLICENSED",
   "author": "Runwork <info@runwork.ai> (https://www.runwork.ai)",