runwork 0.10.2 → 0.10.3

package/dist/dev/preview-url-poller.d.ts

@@ -0,0 +1,35 @@
+import type { ApiClient } from '../api/client.js';
+export interface PreviewUrlPollerOptions {
+    client: ApiClient;
+    appId: string;
+    initialUrl: string;
+    /**
+     * Polling interval in ms. Defaults to 15s -- low enough to catch a
+     * sandbox URL rotation within one keypress's worth of attention, high
+     * enough that an idle dev session isn't generating noticeable API load.
+     */
+    intervalMs?: number;
+    onChange: (next: string, prev: string) => void;
+    onError?: (err: unknown) => void;
+}
+export interface PreviewUrlPoller {
+    getCurrent(): string;
+    stop(): void;
+}
+/**
+ * Periodically refreshes the preview URL from `GET /api/dev/status` so the
+ * `runwork dev` UI stays in agreement with `runwork info` even when the
+ * sandbox tunnel rotates mid-session.
+ *
+ * Two intentional behaviours:
+ *
+ *   1. Empty server responses are NOT propagated. The DO clears its
+ *      preview-URL cache to "" while a sandbox is being replaced; flipping
+ *      the status line to empty and back would just be flicker. We keep
+ *      the last known good URL until the server reports a real new one.
+ *
+ *   2. Overlapping ticks are skipped. If a fetch takes longer than the
+ *      interval (slow network, sandbox spin-up), we don't pile up requests
+ *      -- the next tick simply no-ops until the in-flight one resolves.
+ */
+export declare function startPreviewUrlPoller(opts: PreviewUrlPollerOptions): PreviewUrlPoller;

package/dist/dev/preview-url-poller.js

@@ -0,0 +1,50 @@
+/**
+ * Periodically refreshes the preview URL from `GET /api/dev/status` so the
+ * `runwork dev` UI stays in agreement with `runwork info` even when the
+ * sandbox tunnel rotates mid-session.
+ *
+ * Two intentional behaviours:
+ *
+ *   1. Empty server responses are NOT propagated. The DO clears its
+ *      preview-URL cache to "" while a sandbox is being replaced; flipping
+ *      the status line to empty and back would just be flicker. We keep
+ *      the last known good URL until the server reports a real new one.
+ *
+ *   2. Overlapping ticks are skipped. If a fetch takes longer than the
+ *      interval (slow network, sandbox spin-up), we don't pile up requests
+ *      -- the next tick simply no-ops until the in-flight one resolves.
+ */
+export function startPreviewUrlPoller(opts) {
+    let current = opts.initialUrl;
+    const interval = opts.intervalMs ?? 15000;
+    let stopped = false;
+    let inFlight = false;
+    const tick = async () => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        try {
+            const status = await opts.client.getDevStatus(opts.appId);
+            const next = status.previewUrl ?? '';
+            if (next && next !== current) {
+                const prev = current;
+                current = next;
+                opts.onChange(next, prev);
+            }
+        }
+        catch (err) {
+            opts.onError?.(err);
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    const handle = setInterval(() => { void tick(); }, interval);
+    return {
+        getCurrent: () => current,
+        stop: () => {
+            stopped = true;
+            clearInterval(handle);
+        },
+    };
+}

package/dist/dev/session.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+export declare 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 declare const BOOT_TIME_TOLERANCE_MS = 60000;
+export type SessionMode = 'foreground' | 'detached';
+export interface SessionFile {
+    version: number;
+    pid: number;
+    sessionId: string;
+    appId: string;
+    previewUrl: string;
+    startedAt: number;
+    bootTime: number;
+    cliVersion: string;
+    mode: SessionMode;
+}
+export type SessionStaleReason = 'malformed' | 'version-mismatch' | 'app-id-mismatch' | 'boot-time-mismatch' | 'pid-dead';
+export type SessionState = {
+    state: 'none';
+} | {
+    state: 'alive';
+    file: SessionFile;
+} | {
+    state: 'stale';
+    reason: SessionStaleReason;
+    file?: SessionFile;
+};
+export interface SessionPaths {
+    /** `<app-dir>/.runwork` */
+    dir: string;
+    /** `<app-dir>/.runwork/dev-session.json` */
+    file: string;
+    /** `<app-dir>/.runwork/dev-session.json.tmp` -- staging path for atomic writes */
+    tmpFile: string;
+    /** `<app-dir>/.runwork/dev-stdout.log` -- detached child's stdout sink */
+    stdoutLog: string;
+    /** `<app-dir>/.runwork/dev-stderr.log` -- detached child's stderr sink */
+    stderrLog: string;
+}
+/**
+ * Inject-able dependencies for testing. The defaults call into real OS
+ * primitives. Tests pass overrides to simulate dead PIDs, reboots, or
+ * arbitrary clocks without monkey-patching `process` or `os`.
+ */
+export interface SessionDeps {
+    bootTime?: () => number;
+    pidAlive?: (pid: number) => boolean;
+}
+export declare function getSessionPaths(appDir: string): SessionPaths;
+/**
+ * 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 declare function currentBootTime(): number;
+export declare function isBootTimeStale(stored: number, deps?: SessionDeps): boolean;
+/**
+ * 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 declare function isPidAlive(pid: number): boolean;
+/**
+ * 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 declare function readSessionFile(appDir: string): SessionFile | null;
+/**
+ * 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 declare function writeSessionFile(appDir: string, data: SessionFile): void;
+/**
+ * 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 declare function removeSessionFileIfOwned(appDir: string, pid: number): boolean;
+/**
+ * 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 declare function removeSessionFile(appDir: string): void;
+/**
+ * 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 declare function getSessionState(appDir: string, expectedAppId: string, deps?: SessionDeps): SessionState;
+/**
+ * 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 declare function buildSessionFile(input: {
+    pid: number;
+    sessionId: string;
+    appId: string;
+    previewUrl: string;
+    cliVersion: string;
+    mode: SessionMode;
+    startedAt?: number;
+    deps?: SessionDeps;
+}): SessionFile;

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.3";

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.3";

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 {