runwork 0.10.2 → 0.10.3

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

@@ -0,0 +1,347 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { SESSION_FILE_SCHEMA_VERSION, BOOT_TIME_TOLERANCE_MS, buildSessionFile, currentBootTime, getSessionPaths, getSessionState, isBootTimeStale, isPidAlive, readSessionFile, removeSessionFile, removeSessionFileIfOwned, writeSessionFile, } from '../session.js';
+function createTmpAppDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'runwork-session-test-'));
+}
+function makeValidSessionFile(overrides = {}) {
+    return {
+        version: SESSION_FILE_SCHEMA_VERSION,
+        pid: process.pid,
+        sessionId: 'sess_test_abc',
+        appId: 'test-app',
+        previewUrl: 'https://test.preview.runwork.dev',
+        startedAt: 1_700_000_000_000,
+        bootTime: 1_600_000_000_000,
+        cliVersion: '0.10.2',
+        mode: 'foreground',
+        ...overrides,
+    };
+}
+describe('session lifecycle primitives', () => {
+    let appDir;
+    beforeEach(() => {
+        appDir = createTmpAppDir();
+    });
+    afterEach(() => {
+        if (fs.existsSync(appDir)) {
+            fs.rmSync(appDir, { recursive: true, force: true });
+        }
+    });
+    describe('getSessionPaths()', () => {
+        it('returns the four expected paths under <appDir>/.runwork', () => {
+            const paths = getSessionPaths(appDir);
+            expect(paths.dir).toBe(path.join(appDir, '.runwork'));
+            expect(paths.file).toBe(path.join(appDir, '.runwork', 'dev-session.json'));
+            expect(paths.tmpFile).toBe(path.join(appDir, '.runwork', 'dev-session.json.tmp'));
+            expect(paths.stdoutLog).toBe(path.join(appDir, '.runwork', 'dev-stdout.log'));
+            expect(paths.stderrLog).toBe(path.join(appDir, '.runwork', 'dev-stderr.log'));
+        });
+    });
+    describe('currentBootTime() / isBootTimeStale()', () => {
+        it('currentBootTime is finite and within a few seconds of Date.now() - os.uptime()*1000', () => {
+            const expected = Date.now() - os.uptime() * 1000;
+            const got = currentBootTime();
+            expect(Number.isFinite(got)).toBe(true);
+            expect(Math.abs(got - expected)).toBeLessThan(2_000);
+        });
+        it('returns false (not stale) when stored matches current exactly', () => {
+            expect(isBootTimeStale(currentBootTime())).toBe(false);
+        });
+        it('returns false (not stale) for drift just under the tolerance', () => {
+            const now = 1_000_000_000_000;
+            const stored = now - (BOOT_TIME_TOLERANCE_MS - 1);
+            expect(isBootTimeStale(stored, { bootTime: () => now })).toBe(false);
+        });
+        it('returns true (stale) for drift just over the tolerance', () => {
+            const now = 1_000_000_000_000;
+            const stored = now - (BOOT_TIME_TOLERANCE_MS + 1);
+            expect(isBootTimeStale(stored, { bootTime: () => now })).toBe(true);
+        });
+        it('detects a reboot (large boot-time delta)', () => {
+            const before = 1_000_000_000_000;
+            const afterReboot = before + 24 * 60 * 60 * 1000; // 24 hours later
+            expect(isBootTimeStale(before, { bootTime: () => afterReboot })).toBe(true);
+        });
+    });
+    describe('isPidAlive()', () => {
+        it('returns true for the currently running process', () => {
+            expect(isPidAlive(process.pid)).toBe(true);
+        });
+        it('returns false for PID 0', () => {
+            expect(isPidAlive(0)).toBe(false);
+        });
+        it('returns false for negative PIDs', () => {
+            expect(isPidAlive(-1)).toBe(false);
+            expect(isPidAlive(-99999)).toBe(false);
+        });
+        it('returns false for non-integer PIDs', () => {
+            expect(isPidAlive(1.5)).toBe(false);
+            expect(isPidAlive(NaN)).toBe(false);
+        });
+        it('returns false for an almost-certainly-dead high PID', () => {
+            // 32-bit max-ish PID on platforms that support it. Vanishingly
+            // unlikely to be assigned during test runtime.
+            expect(isPidAlive(2_147_483_640)).toBe(false);
+        });
+    });
+    describe('readSessionFile()', () => {
+        it('returns null when the file does not exist', () => {
+            expect(readSessionFile(appDir)).toBeNull();
+        });
+        it('returns null when the file is not valid JSON', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, 'not-json{{{', 'utf-8');
+            expect(readSessionFile(appDir)).toBeNull();
+        });
+        it('returns null when required fields are missing', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, JSON.stringify({ version: 1, pid: 123 }), 'utf-8');
+            expect(readSessionFile(appDir)).toBeNull();
+        });
+        it('returns null when a field has the wrong type', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            const bad = { ...makeValidSessionFile(), pid: 'not-a-number' };
+            fs.writeFileSync(file, JSON.stringify(bad), 'utf-8');
+            expect(readSessionFile(appDir)).toBeNull();
+        });
+        it('returns null when mode is not one of the allowed strings', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            const bad = { ...makeValidSessionFile(), mode: 'something-else' };
+            fs.writeFileSync(file, JSON.stringify(bad), 'utf-8');
+            expect(readSessionFile(appDir)).toBeNull();
+        });
+        it('returns the parsed file when valid', () => {
+            const valid = makeValidSessionFile();
+            writeSessionFile(appDir, valid);
+            expect(readSessionFile(appDir)).toEqual(valid);
+        });
+    });
+    describe('writeSessionFile()', () => {
+        it('creates the .runwork directory if it does not exist', () => {
+            const { dir } = getSessionPaths(appDir);
+            expect(fs.existsSync(dir)).toBe(false);
+            writeSessionFile(appDir, makeValidSessionFile());
+            expect(fs.existsSync(dir)).toBe(true);
+        });
+        it('produces a file readable by readSessionFile', () => {
+            const file = makeValidSessionFile({ previewUrl: 'https://abc.example' });
+            writeSessionFile(appDir, file);
+            expect(readSessionFile(appDir)).toEqual(file);
+        });
+        it('does not leave a .tmp file behind on a successful write', () => {
+            writeSessionFile(appDir, makeValidSessionFile());
+            const { tmpFile } = getSessionPaths(appDir);
+            expect(fs.existsSync(tmpFile)).toBe(false);
+        });
+        it('overwrites the previous file on subsequent writes', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ previewUrl: 'https://first' }));
+            writeSessionFile(appDir, makeValidSessionFile({ previewUrl: 'https://second' }));
+            expect(readSessionFile(appDir)?.previewUrl).toBe('https://second');
+        });
+    });
+    describe('removeSessionFile()', () => {
+        it('removes the session file', () => {
+            writeSessionFile(appDir, makeValidSessionFile());
+            const { file } = getSessionPaths(appDir);
+            expect(fs.existsSync(file)).toBe(true);
+            removeSessionFile(appDir);
+            expect(fs.existsSync(file)).toBe(false);
+        });
+        it('is idempotent (no error when the file is missing)', () => {
+            expect(() => removeSessionFile(appDir)).not.toThrow();
+            expect(() => removeSessionFile(appDir)).not.toThrow();
+        });
+        it('also removes a leftover .tmp file from a crashed mid-write', () => {
+            const { dir, tmpFile } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(tmpFile, '{}', 'utf-8');
+            removeSessionFile(appDir);
+            expect(fs.existsSync(tmpFile)).toBe(false);
+        });
+    });
+    describe('removeSessionFileIfOwned()', () => {
+        it('removes the file when the pid matches', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ pid: 12345 }));
+            expect(removeSessionFileIfOwned(appDir, 12345)).toBe(true);
+            expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+        });
+        it('does NOT remove the file when the pid mismatches (another process took over)', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ pid: 99999 }));
+            expect(removeSessionFileIfOwned(appDir, 12345)).toBe(false);
+            expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(true);
+        });
+        it('returns false (no-op) when the file is missing', () => {
+            expect(removeSessionFileIfOwned(appDir, 12345)).toBe(false);
+        });
+        it('returns false when the file is malformed (treats as not-ours)', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, '{ broken', 'utf-8');
+            expect(removeSessionFileIfOwned(appDir, 12345)).toBe(false);
+            // We don't touch malformed files -- the next `runwork dev` will
+            // detect-and-clean via getSessionState, which is the right place
+            // for that policy.
+            expect(fs.existsSync(file)).toBe(true);
+        });
+    });
+    describe('getSessionState()', () => {
+        const aliveDeps = {
+            bootTime: () => 1_600_000_000_000,
+            pidAlive: (_pid) => true,
+        };
+        it('returns "none" when no file exists', () => {
+            expect(getSessionState(appDir, 'test-app', aliveDeps)).toEqual({ state: 'none' });
+        });
+        it('returns "stale: malformed" when the file is not valid JSON', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, '{ broken', 'utf-8');
+            const result = getSessionState(appDir, 'test-app', aliveDeps);
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('malformed');
+                expect(result.file).toBeUndefined();
+            }
+        });
+        it('returns "stale: malformed" when required fields are missing', () => {
+            const { dir, file } = getSessionPaths(appDir);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, JSON.stringify({ version: 1, pid: 123 }), 'utf-8');
+            const result = getSessionState(appDir, 'test-app', aliveDeps);
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('malformed');
+            }
+        });
+        it('returns "stale: version-mismatch" when the schema version is unknown', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ version: 999 }));
+            const result = getSessionState(appDir, 'test-app', aliveDeps);
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('version-mismatch');
+                expect(result.file?.version).toBe(999);
+            }
+        });
+        it('returns "stale: app-id-mismatch" when appId does not match the expected app', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ appId: 'a-different-app' }));
+            const result = getSessionState(appDir, 'test-app', aliveDeps);
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('app-id-mismatch');
+                expect(result.file?.appId).toBe('a-different-app');
+            }
+        });
+        it('returns "stale: boot-time-mismatch" when the system has rebooted since the session was written', () => {
+            const writtenBoot = 1_600_000_000_000;
+            writeSessionFile(appDir, makeValidSessionFile({ bootTime: writtenBoot }));
+            const result = getSessionState(appDir, 'test-app', {
+                bootTime: () => writtenBoot + 24 * 60 * 60 * 1000, // 24h later
+                pidAlive: () => true,
+            });
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('boot-time-mismatch');
+            }
+        });
+        it('returns "stale: pid-dead" when the PID is no longer running', () => {
+            writeSessionFile(appDir, makeValidSessionFile());
+            const result = getSessionState(appDir, 'test-app', {
+                bootTime: () => 1_600_000_000_000,
+                pidAlive: () => false,
+            });
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('pid-dead');
+            }
+        });
+        it('returns "alive" when version + appId + bootTime + pid all check out', () => {
+            const file = makeValidSessionFile();
+            writeSessionFile(appDir, file);
+            const result = getSessionState(appDir, 'test-app', aliveDeps);
+            expect(result.state).toBe('alive');
+            if (result.state === 'alive') {
+                expect(result.file).toEqual(file);
+            }
+        });
+        it('uses real defaults when no deps are passed (regression: undefined-spread)', () => {
+            // Build a session file claiming to be the current process at the
+            // current boot time, then call getSessionState with NO deps. This
+            // exercises the real `currentBootTime` + `isPidAlive` defaults --
+            // the path that a buggy `{...realDeps, ...{bootTime: undefined}}`
+            // spread would have crashed.
+            const file = makeValidSessionFile({
+                pid: process.pid,
+                bootTime: Date.now() - os.uptime() * 1000,
+            });
+            writeSessionFile(appDir, file);
+            const result = getSessionState(appDir, 'test-app');
+            expect(result.state).toBe('alive');
+        });
+        it('checks version BEFORE app-id, so a v999 with wrong appId reports version-mismatch', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ version: 999, appId: 'wrong' }));
+            const result = getSessionState(appDir, 'test-app', aliveDeps);
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('version-mismatch');
+            }
+        });
+        it('checks bootTime BEFORE pidAlive, so a stale-rebooted file does not depend on the PID syscall', () => {
+            writeSessionFile(appDir, makeValidSessionFile({ bootTime: 1_600_000_000_000 }));
+            const pidAlive = (_pid) => {
+                throw new Error('pidAlive should not be called when bootTime is stale');
+            };
+            const result = getSessionState(appDir, 'test-app', {
+                bootTime: () => 1_600_000_000_000 + 24 * 60 * 60 * 1000,
+                pidAlive,
+            });
+            expect(result.state).toBe('stale');
+            if (result.state === 'stale') {
+                expect(result.reason).toBe('boot-time-mismatch');
+            }
+        });
+    });
+    describe('buildSessionFile()', () => {
+        it('fills version + bootTime + startedAt and passes through the rest', () => {
+            const before = Date.now();
+            const file = buildSessionFile({
+                pid: 12345,
+                sessionId: 'sess_x',
+                appId: 'app',
+                previewUrl: 'https://x',
+                cliVersion: '1.2.3',
+                mode: 'foreground',
+                deps: { bootTime: () => 42 },
+            });
+            const after = Date.now();
+            expect(file.version).toBe(SESSION_FILE_SCHEMA_VERSION);
+            expect(file.pid).toBe(12345);
+            expect(file.sessionId).toBe('sess_x');
+            expect(file.appId).toBe('app');
+            expect(file.previewUrl).toBe('https://x');
+            expect(file.cliVersion).toBe('1.2.3');
+            expect(file.mode).toBe('foreground');
+            expect(file.bootTime).toBe(42);
+            expect(file.startedAt).toBeGreaterThanOrEqual(before);
+            expect(file.startedAt).toBeLessThanOrEqual(after);
+        });
+        it('honors an explicit startedAt override', () => {
+            const file = buildSessionFile({
+                pid: 1,
+                sessionId: 's',
+                appId: 'a',
+                previewUrl: '',
+                cliVersion: '0.0.0',
+                mode: 'detached',
+                startedAt: 12345,
+                deps: { bootTime: () => 0 },
+            });
+            expect(file.startedAt).toBe(12345);
+        });
+    });
+});

package/dist/dev/__tests__/stop.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,172 @@
+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 { stopSession } from '../stop.js';
+import { buildSessionFile, getSessionPaths, writeSessionFile, } from '../session.js';
+function createTmpAppDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'runwork-stop-test-'));
+}
+function makeAliveFile(overrides = {}) {
+    return buildSessionFile({
+        pid: 99999,
+        sessionId: 'sess_test',
+        appId: 'test-app',
+        previewUrl: 'https://x',
+        cliVersion: '0.10.2',
+        mode: 'foreground',
+        deps: { bootTime: () => 1_000_000_000_000 },
+        ...overrides,
+    });
+}
+describe('stopSession()', () => {
+    let appDir;
+    beforeEach(() => {
+        appDir = createTmpAppDir();
+    });
+    afterEach(() => {
+        if (fs.existsSync(appDir)) {
+            fs.rmSync(appDir, { recursive: true, force: true });
+        }
+    });
+    it('returns "no-session" when there is no file to act on', async () => {
+        const out = await stopSession(appDir, 'test-app');
+        expect(out).toEqual({ result: 'no-session' });
+    });
+    it('cleans up a stale file (dead PID) without trying to kill anything', async () => {
+        const file = makeAliveFile();
+        writeSessionFile(appDir, file);
+        const killProcess = vi.fn();
+        const out = await stopSession(appDir, 'test-app', {
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => false,
+            killProcess,
+        });
+        expect(out.result).toBe('stale-cleaned');
+        if (out.result === 'stale-cleaned') {
+            expect(out.reason).toBe('pid-dead');
+            expect(out.pid).toBe(file.pid);
+        }
+        expect(killProcess).not.toHaveBeenCalled();
+        expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+    });
+    it('cleans up a stale file (app-id mismatch) without killing the other app\'s process', async () => {
+        writeSessionFile(appDir, makeAliveFile({ appId: 'a-different-app' }));
+        const killProcess = vi.fn();
+        const out = await stopSession(appDir, 'test-app', {
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => true,
+            killProcess,
+        });
+        expect(out.result).toBe('stale-cleaned');
+        if (out.result === 'stale-cleaned') {
+            expect(out.reason).toBe('app-id-mismatch');
+        }
+        expect(killProcess).not.toHaveBeenCalled();
+        expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+    });
+    it('on Unix: sends SIGTERM, waits for the PID to die, returns "stopped" gracefully', async () => {
+        writeSessionFile(appDir, makeAliveFile({ pid: 12345 }));
+        let alive = true;
+        const killCalls = [];
+        const out = await stopSession(appDir, 'test-app', {
+            platform: 'darwin',
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => alive,
+            killProcess: (pid, signal) => {
+                killCalls.push({ pid, signal });
+                if (signal === 'SIGTERM') {
+                    // Simulate the child cleaning up after SIGTERM with a tiny delay.
+                    setTimeout(() => { alive = false; }, 50);
+                }
+            },
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            graceTimeoutMs: 2000,
+            pollIntervalMs: 25,
+        });
+        expect(out.result).toBe('stopped');
+        if (out.result === 'stopped') {
+            expect(out.pid).toBe(12345);
+            expect(out.gracefully).toBe(true);
+        }
+        expect(killCalls).toHaveLength(1);
+        expect(killCalls[0]).toEqual({ pid: 12345, signal: 'SIGTERM' });
+        expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+    });
+    it('on Unix: falls back to SIGKILL when SIGTERM does not stop the process within graceTimeoutMs', async () => {
+        writeSessionFile(appDir, makeAliveFile({ pid: 12345 }));
+        const killCalls = [];
+        const out = await stopSession(appDir, 'test-app', {
+            platform: 'linux',
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => true, // never dies on its own
+            killProcess: (pid, signal) => {
+                killCalls.push({ pid, signal });
+            },
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            graceTimeoutMs: 200,
+            pollIntervalMs: 25,
+        });
+        expect(out.result).toBe('stopped');
+        if (out.result === 'stopped') {
+            expect(out.gracefully).toBe(false);
+        }
+        expect(killCalls.map((c) => c.signal)).toEqual(['SIGTERM', 'SIGKILL']);
+        expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+    });
+    it('on Windows: kills with TerminateProcess (no signal arg), no SIGKILL fallback path', async () => {
+        writeSessionFile(appDir, makeAliveFile({ pid: 12345 }));
+        const killCalls = [];
+        const out = await stopSession(appDir, 'test-app', {
+            platform: 'win32',
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => true,
+            killProcess: (pid, signal) => {
+                killCalls.push({ pid, signal });
+            },
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        });
+        expect(out.result).toBe('stopped');
+        expect(killCalls).toHaveLength(1);
+        expect(killCalls[0].signal).toBeUndefined();
+        expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+    });
+    it('returns "kill-failed" but still removes the session file when the kill throws', async () => {
+        writeSessionFile(appDir, makeAliveFile({ pid: 12345 }));
+        const out = await stopSession(appDir, 'test-app', {
+            platform: 'linux',
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => true,
+            killProcess: () => {
+                const err = new Error('EPERM');
+                err.code = 'EPERM';
+                throw err;
+            },
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        });
+        expect(out.result).toBe('kill-failed');
+        if (out.result === 'kill-failed') {
+            expect(out.pid).toBe(12345);
+        }
+        expect(fs.existsSync(getSessionPaths(appDir).file)).toBe(false);
+    });
+    it('treats the session file disappearing during the SIGTERM wait as graceful exit', async () => {
+        writeSessionFile(appDir, makeAliveFile({ pid: 12345 }));
+        const out = await stopSession(appDir, 'test-app', {
+            platform: 'darwin',
+            bootTime: () => 1_000_000_000_000,
+            pidAlive: () => true, // PID stays alive in the mock...
+            killProcess: () => {
+                // ...but the "child" removes its file mid-grace-period.
+                setTimeout(() => { fs.rmSync(getSessionPaths(appDir).file); }, 30);
+            },
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            graceTimeoutMs: 500,
+            pollIntervalMs: 10,
+        });
+        expect(out.result).toBe('stopped');
+        if (out.result === 'stopped') {
+            expect(out.gracefully).toBe(true);
+        }
+    });
+});

package/dist/dev/attach.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `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 { type SessionFile } from './session.js';
+export interface RenderedEvent {
+    /** Pre-styled human-readable line ready to print to a TTY. */
+    text: string;
+    /** Severity hint, useful for filtering or color. */
+    level: 'info' | 'warn' | 'error';
+}
+interface ColorFns {
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+    cyan: (s: string) => string;
+}
+/**
+ * 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 declare function renderLogLine(line: string, source: 'stdout' | 'stderr', colors?: ColorFns): RenderedEvent;
+export interface LogTailOptions {
+    /** Number of trailing lines to replay on attach. Default 50. */
+    initialLines?: number;
+    /** Poll interval. Default 500ms. */
+    intervalMs?: number;
+    /** Called for each new line. */
+    onLine: (line: string, source: 'stdout' | 'stderr') => void;
+    /**
+     * Called when we detect file truncation (size shrunk) on either file.
+     * The orchestrator decides whether this is a "session restarted -- exit
+     * attach" or "spurious -- reset and continue."
+     */
+    onTruncated?: () => void;
+    onError?: (err: unknown) => void;
+}
+export interface LogTail {
+    stop(): void;
+}
+/**
+ * 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 declare function startLogTail(stdoutPath: string, stderrPath: string, opts: LogTailOptions): LogTail;
+/**
+ * Format a "started X ago" string for human display. Pure function, no
+ * locale handling -- this is a developer tool, not a UI.
+ */
+export declare function formatStartedAgo(startedAt: number, now?: number): string;
+/**
+ * Watch the session file for `previewUrl` rotations or for the file
+ * disappearing (the session ended). Polls instead of `fs.watch` for
+ * cross-platform consistency.
+ */
+export interface SessionWatchOptions {
+    intervalMs?: number;
+    expectedAppId: string;
+    onUrlChanged?: (next: string, prev: string) => void;
+    onSessionGone?: () => void;
+    onError?: (err: unknown) => void;
+}
+export interface SessionWatch {
+    stop(): void;
+}
+export declare function startSessionFileWatch(appDir: string, initial: SessionFile, opts: SessionWatchOptions): SessionWatch;
+/**
+ * Result returned to `dev.ts` so it can pick a top-level message + exit
+ * code. The orchestrator function never calls `process.exit` itself --
+ * tests can drive it without spawning a child.
+ */
+export type AttachResult = {
+    result: 'no-session';
+} | {
+    result: 'stale-cleaned';
+    reason: string;
+} | {
+    result: 'attached';
+    file: SessionFile;
+};
+/**
+ * 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 declare function resolveAttachTarget(appDir: string, expectedAppId: string): AttachResult;
+/**
+ * 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 declare function getCurrentPreviewUrl(appDir: string, fallback: string): string;
+/** Convenience: the log file paths for the given app dir. */
+export declare function getAttachLogPaths(appDir: string): {
+    stdout: string;
+    stderr: string;
+};
+export {};