runwork 0.10.2 → 0.10.3

package/dist/dev/attach.js

@@ -0,0 +1,269 @@
+/**
+ * `runwork dev attach` -- read-only join on a running dev session.
+ *
+ * Attach is the handover affordance: an agent starts `runwork dev --detach`,
+ * a human (or another agent) later runs `runwork dev attach` to see the
+ * URL and the live log feed without disturbing the running session.
+ *
+ * Hard rule: attach NEVER kills the session except in response to an
+ * explicit `s` keypress (or `runwork dev stop` in another terminal).
+ * Ctrl+C and `q` exit attach but leave the session running. This is the
+ * inverted cleanup contract from foreground `runwork dev`, so we keep
+ * the keyboard switch local to this module rather than reusing dev.ts's
+ * dispatcher.
+ */
+import * as fs from 'fs';
+import { getSessionPaths, getSessionState, readSessionFile, removeSessionFile, } from './session.js';
+const identityColors = {
+    dim: (s) => s,
+    green: (s) => s,
+    yellow: (s) => s,
+    red: (s) => s,
+    cyan: (s) => s,
+};
+/**
+ * Turn one raw log-file line into a rendered `RenderedEvent`. The line
+ * may be NDJSON (the format the detached child writes) or plain text.
+ *
+ *   - Known NDJSON `event` types get a friendly one-line summary.
+ *   - Unknown JSON shapes pass through as compact JSON with dim styling.
+ *   - Non-JSON text passes through verbatim, with stderr lines reddened.
+ *
+ * Pure function: no I/O, no globals, no color env. Tests pass identity
+ * color fns to assert exact output without ANSI noise.
+ */
+export function renderLogLine(line, source, colors = identityColors) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { text: line, level: 'info' };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return {
+            text: source === 'stderr' ? colors.red(line) : line,
+            level: source === 'stderr' ? 'error' : 'info',
+        };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { text: colors.dim(JSON.stringify(parsed)), level: 'info' };
+    }
+    const ev = parsed.event;
+    if (typeof ev !== 'string') {
+        return { text: colors.dim(JSON.stringify(parsed)), level: 'info' };
+    }
+    const obj = parsed;
+    switch (ev) {
+        case 'session_started': {
+            const url = typeof obj.previewUrl === 'string' ? obj.previewUrl : '';
+            return {
+                text: colors.green('Dev session started') + (url ? ' ' + colors.dim(`(preview ${url})`) : ''),
+                level: 'info',
+            };
+        }
+        case 'preview_url_changed': {
+            const next = typeof obj.previewUrl === 'string' ? obj.previewUrl : '?';
+            const prev = typeof obj.previousUrl === 'string' ? obj.previousUrl : '?';
+            return {
+                text: colors.yellow('Preview URL changed') + ' ' + colors.dim(`${prev} -> ${next}`),
+                level: 'warn',
+            };
+        }
+        case 'files_synced': {
+            const count = typeof obj.count === 'number' ? obj.count : 0;
+            const target = typeof obj.target === 'string' ? obj.target : 'preview';
+            return { text: colors.cyan(`Synced ${count} file(s) -> ${target}`), level: 'info' };
+        }
+        case 'files_pushed': {
+            const count = typeof obj.count === 'number' ? obj.count : 0;
+            return { text: colors.cyan(`Pushed ${count} file(s) -> git`), level: 'info' };
+        }
+        case 'startup': {
+            const phase = typeof obj.phase === 'string' ? obj.phase : '';
+            return { text: colors.dim(`[startup] ${phase}`), level: 'info' };
+        }
+        case 'sync_restored_critical_files': {
+            const files = Array.isArray(obj.files) ? obj.files.filter((f) => typeof f === 'string').join(', ') : '';
+            return { text: colors.yellow(`Restored critical files: ${files}`), level: 'warn' };
+        }
+        case 'error': {
+            const errObj = obj.error;
+            const msg = typeof errObj?.message === 'string' ? errObj.message : 'unknown error';
+            const phase = typeof obj.phase === 'string' ? obj.phase : 'unknown';
+            const diag = typeof errObj?.diagnosis === 'string' ? `\n  ${colors.dim(errObj.diagnosis)}` : '';
+            return { text: colors.red(`ERROR (${phase}): ${msg}${diag}`), level: 'error' };
+        }
+        default:
+            return { text: colors.dim(JSON.stringify(parsed)), level: 'info' };
+    }
+}
+/**
+ * Poll-based tail of stdout/stderr log files. Cross-platform by design
+ * (no `fs.watch`, no native deps, identical behavior on macOS/Linux/
+ * Windows). Reads the last `initialLines` lines on start to give the
+ * attaching user immediate context, then watches for appends.
+ */
+export function startLogTail(stdoutPath, stderrPath, opts) {
+    const intervalMs = opts.intervalMs ?? 500;
+    const initialLines = opts.initialLines ?? 50;
+    let stopped = false;
+    const offsets = { stdout: 0, stderr: 0 };
+    const paths = { stdout: stdoutPath, stderr: stderrPath };
+    // Initial replay: last N lines from each file (most recent at the bottom).
+    for (const source of ['stdout', 'stderr']) {
+        const p = paths[source];
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            const stat = fs.statSync(p);
+            const buf = fs.readFileSync(p, 'utf-8');
+            const lines = buf.split('\n');
+            // Strip the trailing empty entry from a final `\n`.
+            const cleaned = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+            const tail = cleaned.slice(-initialLines);
+            for (const line of tail) {
+                opts.onLine(line, source);
+            }
+            offsets[source] = stat.size;
+        }
+        catch (err) {
+            opts.onError?.(err);
+        }
+    }
+    const tickOne = (source) => {
+        const p = paths[source];
+        if (!fs.existsSync(p))
+            return;
+        let stat;
+        try {
+            stat = fs.statSync(p);
+        }
+        catch (err) {
+            opts.onError?.(err);
+            return;
+        }
+        if (stat.size < offsets[source]) {
+            // Truncation: a new dev session started and re-opened the log file
+            // in 'w' mode. Tell the caller; they decide whether to exit or
+            // reset offsets and continue.
+            opts.onTruncated?.();
+            offsets[source] = 0;
+            return;
+        }
+        if (stat.size === offsets[source])
+            return;
+        try {
+            const fd = fs.openSync(p, 'r');
+            try {
+                const length = stat.size - offsets[source];
+                const buf = Buffer.alloc(length);
+                fs.readSync(fd, buf, 0, length, offsets[source]);
+                offsets[source] = stat.size;
+                const text = buf.toString('utf-8');
+                const lines = text.split('\n');
+                const cleaned = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+                for (const line of cleaned) {
+                    opts.onLine(line, source);
+                }
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch (err) {
+            opts.onError?.(err);
+        }
+    };
+    const handle = setInterval(() => {
+        if (stopped)
+            return;
+        tickOne('stdout');
+        tickOne('stderr');
+    }, intervalMs);
+    return {
+        stop: () => {
+            stopped = true;
+            clearInterval(handle);
+        },
+    };
+}
+/**
+ * Format a "started X ago" string for human display. Pure function, no
+ * locale handling -- this is a developer tool, not a UI.
+ */
+export function formatStartedAgo(startedAt, now = Date.now()) {
+    const sec = Math.max(0, Math.round((now - startedAt) / 1000));
+    if (sec < 60)
+        return `${sec}s ago`;
+    if (sec < 3600)
+        return `${Math.floor(sec / 60)}m ago`;
+    return `${Math.floor(sec / 3600)}h ago`;
+}
+export function startSessionFileWatch(appDir, initial, opts) {
+    const intervalMs = opts.intervalMs ?? 2_000;
+    let stopped = false;
+    let lastUrl = initial.previewUrl;
+    const lastPid = initial.pid;
+    const handle = setInterval(() => {
+        if (stopped)
+            return;
+        const file = readSessionFile(appDir);
+        if (!file) {
+            // The file disappeared. Either the session ended cleanly (its
+            // cleanup handler removed it) or someone called `dev stop`. Either
+            // way, the session this attach was tracking is gone.
+            opts.onSessionGone?.();
+            return;
+        }
+        if (file.appId !== opts.expectedAppId || file.pid !== lastPid) {
+            // A different session took over (e.g., user did `dev --restart`
+            // somewhere). Treat the original session as gone -- attach was
+            // following a specific PID, not the whole app.
+            opts.onSessionGone?.();
+            return;
+        }
+        if (file.previewUrl && file.previewUrl !== lastUrl) {
+            const prev = lastUrl;
+            lastUrl = file.previewUrl;
+            opts.onUrlChanged?.(file.previewUrl, prev);
+        }
+    }, intervalMs);
+    return {
+        stop: () => {
+            stopped = true;
+            clearInterval(handle);
+        },
+    };
+}
+/**
+ * Resolve what attach can/should do based on the session file alone.
+ * Pure logic; the caller decides what to render and whether to keep
+ * running. Split out so the resolution can be unit-tested separately
+ * from the long-running tail loop.
+ */
+export function resolveAttachTarget(appDir, expectedAppId) {
+    const state = getSessionState(appDir, expectedAppId);
+    if (state.state === 'none')
+        return { result: 'no-session' };
+    if (state.state === 'stale') {
+        removeSessionFile(appDir);
+        return { result: 'stale-cleaned', reason: state.reason };
+    }
+    return { result: 'attached', file: state.file };
+}
+/**
+ * Helper exposed for the orchestrator: returns the current preview URL
+ * the user should "open" if they press `o`. We re-read the session file
+ * each time so URL rotations are honored without plumbing watchers
+ * through the keyboard handler.
+ */
+export function getCurrentPreviewUrl(appDir, fallback) {
+    const file = readSessionFile(appDir);
+    return file?.previewUrl || fallback;
+}
+/** Convenience: the log file paths for the given app dir. */
+export function getAttachLogPaths(appDir) {
+    const paths = getSessionPaths(appDir);
+    return { stdout: paths.stdoutLog, stderr: paths.stderrLog };
+}

package/dist/dev/detach.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `runwork dev --detach` orchestration.
+ *
+ * The detach contract:
+ *
+ *   1. Parent spawns the child via `process.execPath` with the same args
+ *      plus `--internal-detached-child`. Child stdout/stderr are routed to
+ *      log files in `.runwork/`. Parent calls `child.unref()` and exits as
+ *      soon as the rendezvous signal arrives.
+ *
+ *   2. Child runs the same `runwork dev` code path as foreground, but in
+ *      "detached" mode: no TUI, no keypress listener, JSON event stream
+ *      to stdout (which is the log file).
+ *
+ *   3. Rendezvous channel is the session file, NOT a pipe. The child
+ *      writes `.runwork/dev-session.json` once it has a `previewUrl`. The
+ *      parent polls. When the parent observes a file whose `pid` matches
+ *      the spawned child AND `previewUrl` is non-empty, parent prints +
+ *      emits the URL and exits 0.
+ *
+ *   4. On timeout, parent attempts a single kill of the child, removes
+ *      any partial session file, and exits 1 with a structured error.
+ *
+ * The file-as-IPC choice is intentional: pipes don't survive parent exit,
+ * and Node IPC has historical Bun-on-Windows quirks. The session file is
+ * already our durable lifecycle truth; reusing it for the handshake is
+ * free.
+ */
+import { type SessionDeps, type SessionFile } from './session.js';
+/**
+ * Internal flag passed to the child. Hidden from `--help`. The child uses
+ * its presence to skip the parent-spawn branch and run the actual dev
+ * work in detached mode.
+ */
+export declare const INTERNAL_DETACHED_CHILD_FLAG = "--internal-detached-child";
+export type PollOutcome = {
+    result: 'ready';
+    file: SessionFile;
+} | {
+    result: 'timeout';
+} | {
+    result: 'wrong-pid';
+    file: SessionFile;
+} | {
+    result: 'child-exited';
+};
+export interface PollDeps extends SessionDeps {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll the session file until either:
+ *   - a file appears whose pid matches `expectedPid` AND has a non-empty
+ *     `previewUrl` -> `ready`
+ *   - the timeout elapses -> `timeout`
+ *
+ * If a file appears with a different pid (some other process won a write
+ * race), we treat it as the user's intent being satisfied and return
+ * `wrong-pid` so the caller can decide how to handle it -- usually that's
+ * "another `runwork dev` invocation already had a session running, fine."
+ *
+ * The function does not validate `bootTime` or `appId` -- those are the
+ * caller's job once they know which file matters. We only care about the
+ * shape of the file and the pid match here.
+ */
+export declare function pollForSession(appDir: string, expectedPid: number, expectedAppId: string, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    deps?: PollDeps;
+    /**
+     * Optional: probe whether the spawned child is still running. If
+     * provided and it ever returns false, polling aborts immediately
+     * with `child-exited`. Lets the caller distinguish "child died
+     * before writing the file" (fast fail, ~one tick) from "child is
+     * just slow" (wait for timeout). Without this hook the parent
+     * would hang for the full timeout on a fast-failing child.
+     */
+    isChildAlive?: () => boolean;
+}): Promise<PollOutcome>;
+/**
+ * Open the stdout/stderr log files in truncating mode and return their
+ * descriptors. We truncate (not append) so each new dev session starts
+ * fresh -- log rotation across sessions is out of scope.
+ *
+ * The descriptors must be closed by the caller after `spawn` so the
+ * parent process doesn't keep them open (which would prevent the child
+ * from being the sole owner).
+ */
+export declare function openLogFds(appDir: string): {
+    stdoutFd: number;
+    stderrFd: number;
+};
+export interface SpawnedChildHandle {
+    pid: number;
+    kill: (signal?: NodeJS.Signals) => boolean;
+    /**
+     * Returns false once the child has exited. Lets `pollForSession`
+     * abort early instead of waiting the full timeout when the child
+     * fails fast (missing auth, sync conflict, sandbox-boot error).
+     */
+    isAlive: () => boolean;
+}
+export interface DetachParentOptions {
+    appDir: string;
+    expectedAppId: string;
+    childArgs: string[];
+    intervalMs?: number;
+    timeoutMs?: number;
+    /**
+     * Optional spawn override for tests. Real callers pass nothing and get
+     * the cross-platform spawn defined below.
+     */
+    spawn?: (args: string[]) => SpawnedChildHandle;
+    pollDeps?: PollDeps;
+}
+export type DetachParentOutcome = {
+    result: 'started';
+    file: SessionFile;
+} | {
+    result: 'wrong-pid';
+    file: SessionFile;
+    ourPid: number;
+} | {
+    result: 'timeout';
+    ourPid: number;
+    childLogTail?: string;
+} | {
+    result: 'child-exited';
+    ourPid: number;
+    childLogTail?: string;
+} | {
+    result: 'spawn-failed';
+    error: unknown;
+};
+/**
+ * The parent half of `runwork dev --detach`. Returns a structured outcome
+ * the caller can translate into stdout text and an exit code.
+ *
+ * IMPORTANT: this function does NOT print anything. It only orchestrates.
+ * The caller (in `dev.ts`) decides how to render the outcome -- human
+ * banner vs. JSON event vs. error stream.
+ */
+export declare function runAsDetachedParent(opts: DetachParentOptions): Promise<DetachParentOutcome>;
+/**
+ * Cross-platform detached self-spawn. Uses `process.execPath` so we never
+ * depend on PATH lookup -- a known failure mode for Bun standalone on
+ * Windows. The child gets the user-supplied args plus the internal child
+ * marker.
+ */
+export declare function defaultSpawnDetachedChild(childArgs: string[]): SpawnedChildHandle;
+/**
+ * Detect whether the current `runwork dev` invocation is the detached
+ * child. Used by `dev.ts` to pick between the parent-spawn branch and
+ * the actual dev work.
+ */
+export declare function isInternalDetachedChild(argv?: readonly string[]): boolean;
+/**
+ * Strip the internal marker from a list of args. Used when constructing
+ * the child's args from the parent's own args -- the parent already has
+ * the marker, the child needs it, but we want to avoid duplicates if for
+ * any reason the parent was itself launched with the marker (e.g., a
+ * misconfigured wrapper).
+ */
+export declare function stripInternalChildFlag(args: readonly string[]): string[];

package/dist/dev/detach.js

@@ -0,0 +1,247 @@
+/**
+ * `runwork dev --detach` orchestration.
+ *
+ * The detach contract:
+ *
+ *   1. Parent spawns the child via `process.execPath` with the same args
+ *      plus `--internal-detached-child`. Child stdout/stderr are routed to
+ *      log files in `.runwork/`. Parent calls `child.unref()` and exits as
+ *      soon as the rendezvous signal arrives.
+ *
+ *   2. Child runs the same `runwork dev` code path as foreground, but in
+ *      "detached" mode: no TUI, no keypress listener, JSON event stream
+ *      to stdout (which is the log file).
+ *
+ *   3. Rendezvous channel is the session file, NOT a pipe. The child
+ *      writes `.runwork/dev-session.json` once it has a `previewUrl`. The
+ *      parent polls. When the parent observes a file whose `pid` matches
+ *      the spawned child AND `previewUrl` is non-empty, parent prints +
+ *      emits the URL and exits 0.
+ *
+ *   4. On timeout, parent attempts a single kill of the child, removes
+ *      any partial session file, and exits 1 with a structured error.
+ *
+ * The file-as-IPC choice is intentional: pipes don't survive parent exit,
+ * and Node IPC has historical Bun-on-Windows quirks. The session file is
+ * already our durable lifecycle truth; reusing it for the handshake is
+ * free.
+ */
+import * as fs from 'fs';
+import * as child_process from 'child_process';
+import { getSessionPaths, readSessionFile, removeSessionFileIfOwned, } from './session.js';
+/**
+ * Internal flag passed to the child. Hidden from `--help`. The child uses
+ * its presence to skip the parent-spawn branch and run the actual dev
+ * work in detached mode.
+ */
+export const INTERNAL_DETACHED_CHILD_FLAG = '--internal-detached-child';
+const realPollDeps = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+};
+function resolvePollDeps(deps) {
+    if (!deps)
+        return realPollDeps;
+    return {
+        now: deps.now ?? realPollDeps.now,
+        sleep: deps.sleep ?? realPollDeps.sleep,
+    };
+}
+/**
+ * Poll the session file until either:
+ *   - a file appears whose pid matches `expectedPid` AND has a non-empty
+ *     `previewUrl` -> `ready`
+ *   - the timeout elapses -> `timeout`
+ *
+ * If a file appears with a different pid (some other process won a write
+ * race), we treat it as the user's intent being satisfied and return
+ * `wrong-pid` so the caller can decide how to handle it -- usually that's
+ * "another `runwork dev` invocation already had a session running, fine."
+ *
+ * The function does not validate `bootTime` or `appId` -- those are the
+ * caller's job once they know which file matters. We only care about the
+ * shape of the file and the pid match here.
+ */
+export async function pollForSession(appDir, expectedPid, expectedAppId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 250;
+    const timeoutMs = opts.timeoutMs ?? 90_000;
+    const d = resolvePollDeps(opts.deps);
+    const deadline = d.now() + timeoutMs;
+    while (d.now() < deadline) {
+        if (opts.isChildAlive && !opts.isChildAlive()) {
+            return { result: 'child-exited' };
+        }
+        const file = readSessionFile(appDir);
+        if (file && file.previewUrl && file.appId === expectedAppId) {
+            if (file.pid === expectedPid) {
+                return { result: 'ready', file };
+            }
+            // Another process wrote a session file before our child did. The
+            // user's intent ("have a dev session running") is satisfied. Caller
+            // decides whether to log this and exit success or kill our child.
+            return { result: 'wrong-pid', file };
+        }
+        await d.sleep(intervalMs);
+    }
+    // One last child-alive probe before declaring timeout: a child that
+    // exited just before the deadline would otherwise be reported as
+    // "timeout" instead of "child-exited", losing diagnostic information.
+    if (opts.isChildAlive && !opts.isChildAlive()) {
+        return { result: 'child-exited' };
+    }
+    return { result: 'timeout' };
+}
+/**
+ * Open the stdout/stderr log files in truncating mode and return their
+ * descriptors. We truncate (not append) so each new dev session starts
+ * fresh -- log rotation across sessions is out of scope.
+ *
+ * The descriptors must be closed by the caller after `spawn` so the
+ * parent process doesn't keep them open (which would prevent the child
+ * from being the sole owner).
+ */
+export function openLogFds(appDir) {
+    const paths = getSessionPaths(appDir);
+    fs.mkdirSync(paths.dir, { recursive: true });
+    const stdoutFd = fs.openSync(paths.stdoutLog, 'w');
+    const stderrFd = fs.openSync(paths.stderrLog, 'w');
+    return { stdoutFd, stderrFd };
+}
+/**
+ * The parent half of `runwork dev --detach`. Returns a structured outcome
+ * the caller can translate into stdout text and an exit code.
+ *
+ * IMPORTANT: this function does NOT print anything. It only orchestrates.
+ * The caller (in `dev.ts`) decides how to render the outcome -- human
+ * banner vs. JSON event vs. error stream.
+ */
+export async function runAsDetachedParent(opts) {
+    let child;
+    try {
+        child = (opts.spawn ?? defaultSpawnDetachedChild)(opts.childArgs);
+    }
+    catch (err) {
+        return { result: 'spawn-failed', error: err };
+    }
+    if (!child.pid) {
+        return { result: 'spawn-failed', error: new Error('Spawned child has no PID') };
+    }
+    const outcome = await pollForSession(opts.appDir, child.pid, opts.expectedAppId, {
+        intervalMs: opts.intervalMs,
+        timeoutMs: opts.timeoutMs,
+        deps: opts.pollDeps,
+        isChildAlive: child.isAlive,
+    });
+    if (outcome.result === 'ready') {
+        return { result: 'started', file: outcome.file };
+    }
+    if (outcome.result === 'wrong-pid') {
+        // Another process wrote a session file with a different PID before
+        // our child did. Our child is still happily running its own dev
+        // setup -- left alone, it will eventually overwrite the winner's
+        // session file with its own PID, defeating the duplicate-session
+        // guard. SIGTERM our child so the winner remains the unique owner.
+        // Best-effort: if the kill fails (race, EPERM), we still surface
+        // wrong-pid -- the user/agent will see two sessions briefly and
+        // can resolve via `runwork dev stop`.
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* best-effort */ }
+        return { result: 'wrong-pid', file: outcome.file, ourPid: child.pid };
+    }
+    // For both timeout and child-exited, kill the child (no-op if already
+    // gone), clean up any partial session file we own, and surface the
+    // stderr tail for diagnostics.
+    try {
+        child.kill('SIGTERM');
+    }
+    catch { /* best-effort */ }
+    // Only remove the session file if it's ours -- a wrong-pid race could
+    // have replaced it with the winner's file between our last probe and
+    // here. removeSessionFileIfOwned guards against that.
+    try {
+        removeSessionFileIfOwned(opts.appDir, child.pid);
+    }
+    catch { /* best-effort */ }
+    const childLogTail = readChildStderrTail(opts.appDir);
+    if (outcome.result === 'child-exited') {
+        return { result: 'child-exited', ourPid: child.pid, childLogTail };
+    }
+    return { result: 'timeout', ourPid: child.pid, childLogTail };
+}
+function readChildStderrTail(appDir) {
+    try {
+        const paths = getSessionPaths(appDir);
+        if (!fs.existsSync(paths.stderrLog))
+            return undefined;
+        const raw = fs.readFileSync(paths.stderrLog, 'utf-8');
+        return raw.slice(-2000); // last ~2KB of stderr
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Cross-platform detached self-spawn. Uses `process.execPath` so we never
+ * depend on PATH lookup -- a known failure mode for Bun standalone on
+ * Windows. The child gets the user-supplied args plus the internal child
+ * marker.
+ */
+export function defaultSpawnDetachedChild(childArgs) {
+    const cwd = process.cwd();
+    const { stdoutFd, stderrFd } = openLogFds(cwd);
+    try {
+        const proc = child_process.spawn(process.execPath, childArgs, {
+            cwd,
+            env: process.env,
+            detached: true,
+            stdio: ['ignore', stdoutFd, stderrFd],
+            windowsHide: true,
+        });
+        if (proc.pid !== undefined) {
+            proc.unref();
+        }
+        // Track exit via the 'exit' event. We can't depend on `proc.exitCode`
+        // alone because that's null until the process actually exits.
+        let exited = proc.exitCode !== null || proc.signalCode !== null;
+        proc.on('exit', () => { exited = true; });
+        proc.on('error', () => { exited = true; });
+        return {
+            pid: proc.pid ?? 0,
+            kill: (signal) => proc.kill(signal),
+            isAlive: () => !exited,
+        };
+    }
+    finally {
+        // The child has dup'd these descriptors; the parent should close its
+        // copies so it isn't holding onto the log files. Failure here is
+        // non-fatal -- the FDs will be reaped on parent exit anyway.
+        try {
+            fs.closeSync(stdoutFd);
+        }
+        catch { /* ignore */ }
+        try {
+            fs.closeSync(stderrFd);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Detect whether the current `runwork dev` invocation is the detached
+ * child. Used by `dev.ts` to pick between the parent-spawn branch and
+ * the actual dev work.
+ */
+export function isInternalDetachedChild(argv = process.argv) {
+    return argv.includes(INTERNAL_DETACHED_CHILD_FLAG);
+}
+/**
+ * Strip the internal marker from a list of args. Used when constructing
+ * the child's args from the parent's own args -- the parent already has
+ * the marker, the child needs it, but we want to avoid duplicates if for
+ * any reason the parent was itself launched with the marker (e.g., a
+ * misconfigured wrapper).
+ */
+export function stripInternalChildFlag(args) {
+    return args.filter((a) => a !== INTERNAL_DETACHED_CHILD_FLAG);
+}