runwork 0.14.0 → 0.15.1

package/dist/commands/validate.js

@@ -0,0 +1,89 @@
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'fs';
+import { requireAuth } from '../auth/store.js';
+import { ApiClient } from '../api/client.js';
+import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { bold, dim, green, yellow, red } from '../ui/colors.js';
+import { requireGit } from '../git/preflight.js';
+import { getGitFreshness } from '../validate/freshness.js';
+import { checkPreview } from '../validate/preview.js';
+const BUILD_FOLLOWUP = 'In-sandbox typecheck/lint requires a worker exec endpoint (not yet available). The preview error-overlay check is used as a build proxy.';
+export const validateCommand = new Command('validate')
+    .description('Validate the app before deploy: git sync state + preview liveness (no local deps needed)')
+    .action(async (_opts, command) => {
+    const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    const cwd = process.cwd();
+    if (!existsSync('.runwork.json')) {
+        if (useJson) {
+            jsonOut({ success: false, command: 'validate', error: 'No .runwork.json found. Run inside a Runwork app.' });
+            process.exit(1);
+        }
+        console.error('No .runwork.json found. Run `runwork validate` inside a Runwork app.');
+        process.exit(1);
+    }
+    requireGit('validate');
+    const config = JSON.parse(readFileSync('.runwork.json', 'utf-8'));
+    const creds = requireAuth();
+    const client = new ApiClient(creds);
+    const sync = getGitFreshness(cwd);
+    // Best-effort: ask the server for the current preview URL. No running
+    // preview is not a failure -- the preview check is simply skipped.
+    let previewUrl = null;
+    try {
+        const status = await client.getDevStatus(config.appId);
+        previewUrl = status.previewUrl || null;
+    }
+    catch {
+        /* no active session -- preview check skipped */
+    }
+    const preview = await checkPreview(previewUrl);
+    // Overall: fail only on a concrete problem -- the preview is down or
+    // serving a broken build. Local commits not yet deployed are informational.
+    const ok = preview.url === null ? true : preview.responds && !preview.errorDetected;
+    const result = { sync, preview, build: { checked: false, reason: BUILD_FOLLOWUP }, ok };
+    if (useJson) {
+        jsonOut({ success: ok, command: 'validate', result });
+        if (!ok)
+            process.exit(1);
+        return;
+    }
+    console.log('');
+    console.log(bold('runwork validate'));
+    console.log('');
+    // Sync
+    if (sync.inSync) {
+        console.log(`  ${green('[ok]')}   Sync        ${dim('local matches the deploy remote, working tree clean')}`);
+    }
+    else {
+        const bits = [];
+        if (sync.uncommitted)
+            bits.push('uncommitted changes');
+        if (sync.ahead > 0)
+            bits.push(`${sync.ahead} commit(s) not yet pushed/deployed`);
+        if (sync.behind > 0)
+            bits.push(`${sync.behind} commit(s) behind the remote`);
+        if (!sync.remoteSha)
+            bits.push('no runwork/main ref (push or run dev first)');
+        console.log(`  ${yellow('[info]')} Sync        ${dim(bits.join('; ') || 'not in sync')}`);
+    }
+    // Preview
+    if (!preview.url) {
+        console.log(`  ${dim('[skip]')} Preview     ${dim('no preview running (start `runwork dev`)')}`);
+    }
+    else if (!preview.responds) {
+        console.log(`  ${red('[FAIL]')} Preview     ${dim(`not responding${preview.error ? `: ${preview.error}` : ` (status ${preview.status})`}`)}`);
+    }
+    else if (preview.errorDetected) {
+        console.log(`  ${red('[FAIL]')} Preview     ${dim('serving a build error overlay -- the app does not compile')}`);
+    }
+    else {
+        console.log(`  ${green('[ok]')}   Preview     ${dim(`live and serving a working build (status ${preview.status})`)}`);
+    }
+    // Build (proxy)
+    console.log(`  ${dim('[note]')} Build       ${dim(BUILD_FOLLOWUP)}`);
+    console.log('');
+    console.log(ok ? green('  validate: ok') : red('  validate: FAILED'));
+    console.log('');
+    if (!ok)
+        process.exit(1);
+});

package/dist/deploy/__tests__/deploy-state.test.d.ts

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

package/dist/deploy/__tests__/deploy-state.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+vi.mock('fs', () => ({
+    existsSync: vi.fn(),
+    mkdirSync: vi.fn(),
+    readFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+}));
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const fs = await import('fs');
+const { summarizeDeploy, getHeadSha, writeDeployState, readDeployState, } = await import('../deploy-state.js');
+const SHA = 'a1b2c3d4e5f600000000000000000000deadbeef';
+describe('deploy/deploy-state', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('summarizeDeploy()', () => {
+        it('reports in-sync when local HEAD matches the deployed SHA', () => {
+            const s = summarizeDeploy(SHA, { sha: SHA, deployedAt: '2026-06-05T00:00:00Z', url: 'https://app' });
+            expect(s.inSync).toBe(true);
+            expect(s.deployedShortSha).toBe('a1b2c3d');
+            expect(s.localShortSha).toBe('a1b2c3d');
+            expect(s.deployedAt).toBe('2026-06-05T00:00:00Z');
+            expect(s.url).toBe('https://app');
+        });
+        it('reports out-of-sync when local HEAD has moved past the deploy', () => {
+            const s = summarizeDeploy('ffffffffffffffffffffffffffffffffffffffff', {
+                sha: SHA, deployedAt: '2026-06-05T00:00:00Z', url: 'https://app',
+            });
+            expect(s.inSync).toBe(false);
+            expect(s.deployedShortSha).toBe('a1b2c3d');
+            expect(s.localShortSha).toBe('fffffff');
+        });
+        it('returns inSync=null when there is no recorded deploy', () => {
+            const s = summarizeDeploy(SHA, null);
+            expect(s.inSync).toBeNull();
+            expect(s.deployedSha).toBeNull();
+            expect(s.localShortSha).toBe('a1b2c3d');
+        });
+        it('returns inSync=null when local HEAD is unknown (not a repo)', () => {
+            const s = summarizeDeploy(null, { sha: SHA, deployedAt: 't', url: '' });
+            expect(s.inSync).toBeNull();
+            expect(s.localSha).toBeNull();
+        });
+    });
+    describe('getHeadSha()', () => {
+        it('returns the trimmed HEAD sha', () => {
+            mockExecFileSync.mockReturnValue(Buffer.from(SHA + '\n'));
+            expect(getHeadSha('/repo')).toBe(SHA);
+        });
+        it('returns null when git fails (no commits / not a repo)', () => {
+            mockExecFileSync.mockImplementation(() => { throw new Error('no HEAD'); });
+            expect(getHeadSha('/repo')).toBeNull();
+        });
+    });
+    describe('writeDeployState() / readDeployState()', () => {
+        it('writes JSON, creating .runwork when missing', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            writeDeployState('/repo', { sha: SHA, deployedAt: 't', url: 'https://app' });
+            expect(fs.mkdirSync).toHaveBeenCalled();
+            expect(fs.writeFileSync).toHaveBeenCalledOnce();
+            const written = vi.mocked(fs.writeFileSync).mock.calls[0][1];
+            expect(JSON.parse(written)).toEqual({ sha: SHA, deployedAt: 't', url: 'https://app' });
+        });
+        it('reads back a valid state', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ sha: SHA, deployedAt: 't', url: 'https://app' }));
+            expect(readDeployState('/repo')).toEqual({ sha: SHA, deployedAt: 't', url: 'https://app' });
+        });
+        it('returns null when the file is missing', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            expect(readDeployState('/repo')).toBeNull();
+        });
+        it('returns null when the file is malformed', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue('{ not json');
+            expect(readDeployState('/repo')).toBeNull();
+        });
+    });
+});

package/dist/deploy/__tests__/deploy-status.test.d.ts

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

package/dist/deploy/__tests__/deploy-status.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('fs', () => ({
+    existsSync: vi.fn(),
+    mkdirSync: vi.fn(),
+    readFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+}));
+const fs = await import('fs');
+const { writeDeployStatus, readDeployStatus, deployLogPath } = await import('../deploy-status.js');
+describe('deploy/deploy-status', () => {
+    beforeEach(() => vi.clearAllMocks());
+    it('writes status JSON, creating .runwork when missing', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        writeDeployStatus('/repo', { state: 'in-progress', startedAt: '2026-06-05T00:00:00Z', pid: 123 });
+        expect(fs.mkdirSync).toHaveBeenCalled();
+        const written = vi.mocked(fs.writeFileSync).mock.calls[0][1];
+        expect(JSON.parse(written)).toEqual({ state: 'in-progress', startedAt: '2026-06-05T00:00:00Z', pid: 123 });
+    });
+    it('reads back a valid status', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ state: 'succeeded', startedAt: 't', finishedAt: 'u', url: 'https://app', sha: 'abc' }));
+        expect(readDeployStatus('/repo')).toMatchObject({ state: 'succeeded', url: 'https://app', sha: 'abc' });
+    });
+    it('returns null when the file is missing', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        expect(readDeployStatus('/repo')).toBeNull();
+    });
+    it('rejects a malformed state', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ state: 'weird', startedAt: 't' }));
+        expect(readDeployStatus('/repo')).toBeNull();
+    });
+    it('rejects invalid JSON', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue('{ not json');
+        expect(readDeployStatus('/repo')).toBeNull();
+    });
+    it('deployLogPath points at .runwork/deploy-stdout.log', () => {
+        expect(deployLogPath('/repo')).toContain('deploy-stdout.log');
+    });
+});

package/dist/deploy/__tests__/detach-args.test.d.ts

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

package/dist/deploy/__tests__/detach-args.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { buildDeployChildArgs, isInternalDeployChild, DEPLOY_DETACHED_CHILD_FLAG, } from '../detach.js';
+describe('deploy/detach arg handling', () => {
+    describe('buildDeployChildArgs()', () => {
+        it('drops --detach and appends exactly one child marker', () => {
+            const out = buildDeployChildArgs(['node', '/p/runwork', 'deploy', '--detach']);
+            expect(out).toEqual(['/p/runwork', 'deploy', DEPLOY_DETACHED_CHILD_FLAG]);
+        });
+        it('preserves other flags like --json', () => {
+            const out = buildDeployChildArgs(['node', '/p/runwork', 'deploy', '--detach', '--json']);
+            expect(out).toEqual(['/p/runwork', 'deploy', '--json', DEPLOY_DETACHED_CHILD_FLAG]);
+        });
+        it('does not duplicate the marker when already present', () => {
+            const out = buildDeployChildArgs(['node', '/p/runwork', 'deploy', DEPLOY_DETACHED_CHILD_FLAG]);
+            expect(out.filter(a => a === DEPLOY_DETACHED_CHILD_FLAG)).toHaveLength(1);
+        });
+        it('skips a Bun-on-Windows virtual-FS argv[1]', () => {
+            const out = buildDeployChildArgs(['runwork.exe', 'B:/~BUN/root/runwork-windows-x64.exe', 'deploy', '--detach']);
+            expect(out).toEqual(['deploy', DEPLOY_DETACHED_CHILD_FLAG]);
+        });
+    });
+    describe('isInternalDeployChild()', () => {
+        it('detects the marker', () => {
+            expect(isInternalDeployChild(['node', 'runwork', 'deploy', DEPLOY_DETACHED_CHILD_FLAG])).toBe(true);
+        });
+        it('is false without the marker', () => {
+            expect(isInternalDeployChild(['node', 'runwork', 'deploy'])).toBe(false);
+        });
+    });
+});

package/dist/deploy/deploy-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Record of the last deploy triggered from this machine, persisted to
+ * `.runwork/last-deploy.json`. `sha` is the commit that was pushed and
+ * deployed (local HEAD at deploy time), so comparing it to the current HEAD
+ * cheaply answers "is what I have locally what's deployed?" without scraping
+ * the production bundle (friction log #8).
+ *
+ * NOTE: this reflects deploys from THIS machine. A teammate deploying
+ * elsewhere won't update this file -- an authoritative production-build SHA
+ * would require the deploy API to return it (tracked as a follow-up).
+ */
+export interface DeployState {
+    sha: string;
+    deployedAt: string;
+    url: string;
+}
+export interface DeploySummary {
+    deployedSha: string | null;
+    deployedShortSha: string | null;
+    deployedAt: string | null;
+    url: string | null;
+    localSha: string | null;
+    localShortSha: string | null;
+    /** true/false when both SHAs are known; null when undeterminable. */
+    inSync: boolean | null;
+}
+/** Current git HEAD commit SHA, or null if not a repo / no commits. */
+export declare function getHeadSha(cwd: string): string | null;
+/** Persist the deploy state for `cwd`. Creates `.runwork/` if needed. */
+export declare function writeDeployState(cwd: string, state: DeployState): void;
+/** Read the recorded deploy state for `cwd`, or null if none/unreadable. */
+export declare function readDeployState(cwd: string): DeployState | null;
+/** Compare the local HEAD against a recorded deploy. Pure (no IO). */
+export declare function summarizeDeploy(localSha: string | null, state: DeployState | null): DeploySummary;
+/** Convenience: read git HEAD + recorded deploy and summarize the comparison. */
+export declare function getDeploySummary(cwd: string): DeploySummary;

package/dist/deploy/deploy-state.js

@@ -0,0 +1,63 @@
+import { execFileSync } from '../utils/subprocess.js';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+function deployStatePath(cwd) {
+    return join(cwd, '.runwork', 'last-deploy.json');
+}
+/** Current git HEAD commit SHA, or null if not a repo / no commits. */
+export function getHeadSha(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString()
+            .trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the deploy state for `cwd`. Creates `.runwork/` if needed. */
+export function writeDeployState(cwd, state) {
+    const path = deployStatePath(cwd);
+    try {
+        if (!existsSync(dirname(path)))
+            mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(state, null, 2));
+    }
+    catch {
+        // Best-effort: a failure to record state must never fail a deploy.
+    }
+}
+/** Read the recorded deploy state for `cwd`, or null if none/unreadable. */
+export function readDeployState(cwd) {
+    const path = deployStatePath(cwd);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (typeof parsed.sha === 'string' && typeof parsed.deployedAt === 'string') {
+            return { sha: parsed.sha, deployedAt: parsed.deployedAt, url: parsed.url ?? '' };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compare the local HEAD against a recorded deploy. Pure (no IO). */
+export function summarizeDeploy(localSha, state) {
+    const deployedSha = state?.sha ?? null;
+    const inSync = deployedSha && localSha ? deployedSha === localSha : null;
+    return {
+        deployedSha,
+        deployedShortSha: deployedSha ? deployedSha.slice(0, 7) : null,
+        deployedAt: state?.deployedAt ?? null,
+        url: state?.url ?? null,
+        localSha,
+        localShortSha: localSha ? localSha.slice(0, 7) : null,
+        inSync,
+    };
+}
+/** Convenience: read git HEAD + recorded deploy and summarize the comparison. */
+export function getDeploySummary(cwd) {
+    return summarizeDeploy(getHeadSha(cwd), readDeployState(cwd));
+}

package/dist/deploy/deploy-status.d.ts

@@ -0,0 +1,21 @@
+/** Lifecycle state of a (possibly detached) deploy run. */
+export type DeployRunState = 'in-progress' | 'succeeded' | 'failed';
+/**
+ * Status of the most recent deploy started from this machine, persisted to
+ * `.runwork/deploy-status.json`. Lets `runwork deploy --status` report
+ * progress/outcome of a `--detach`ed deploy that outlived the shell that
+ * launched it (friction log #7).
+ */
+export interface DeployStatus {
+    state: DeployRunState;
+    startedAt: string;
+    finishedAt?: string;
+    url?: string;
+    sha?: string;
+    error?: string;
+    pid?: number;
+}
+/** Path of the detached deploy's stdout log (mirrors dev's log convention). */
+export declare function deployLogPath(cwd: string): string;
+export declare function writeDeployStatus(cwd: string, status: DeployStatus): void;
+export declare function readDeployStatus(cwd: string): DeployStatus | null;

package/dist/deploy/deploy-status.js

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+function statusPath(cwd) {
+    return join(cwd, '.runwork', 'deploy-status.json');
+}
+/** Path of the detached deploy's stdout log (mirrors dev's log convention). */
+export function deployLogPath(cwd) {
+    return join(cwd, '.runwork', 'deploy-stdout.log');
+}
+export function writeDeployStatus(cwd, status) {
+    const path = statusPath(cwd);
+    try {
+        if (!existsSync(dirname(path)))
+            mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(status, null, 2));
+    }
+    catch {
+        // Best-effort: status recording must never fail a deploy.
+    }
+}
+export function readDeployStatus(cwd) {
+    const path = statusPath(cwd);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if ((parsed.state === 'in-progress' || parsed.state === 'succeeded' || parsed.state === 'failed') &&
+            typeof parsed.startedAt === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/deploy/detach.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `runwork deploy --detach` orchestration.
+ *
+ * Unlike `runwork dev --detach`, a deploy has no "ready" rendezvous to wait
+ * for -- it's fire-and-forget-then-poll. So the parent simply spawns a
+ * detached child (whose stdout/stderr go to `.runwork/deploy-*.log`), records
+ * an `in-progress` status, prints a poll hint, and exits. The child runs the
+ * real deploy and finalizes the status file to `succeeded`/`failed`.
+ *
+ * This exists so agents whose shell tool times out (~45s) can launch a deploy
+ * that survives, then poll `runwork deploy --status` (friction log #7).
+ */
+/** Hidden marker passed to the spawned child. Not shown in --help. */
+export declare const DEPLOY_DETACHED_CHILD_FLAG = "--internal-detached-deploy-child";
+/** Whether this invocation is the detached deploy child. */
+export declare function isInternalDeployChild(argv?: readonly string[]): boolean;
+/**
+ * Build the args for the spawned child so it re-runs the same deploy in the
+ * foreground (the child must NOT re-detach). Drops `--detach`, any stale
+ * marker, and a Bun-on-Windows virtual-FS path; re-adds exactly one marker.
+ * Pure for testability.
+ */
+export declare function buildDeployChildArgs(parentArgv: readonly string[]): string[];
+export interface SpawnedDeployHandle {
+    pid: number;
+}
+/**
+ * Spawn the detached deploy child with stdout/stderr routed to
+ * `.runwork/deploy-{stdout,stderr}.log`. Cross-platform: uses
+ * `process.execPath` so it never depends on PATH (Bun-standalone-safe).
+ */
+export declare function spawnDetachedDeploy(childArgs: string[], cwd: string): SpawnedDeployHandle;

package/dist/deploy/detach.js

@@ -0,0 +1,71 @@
+/**
+ * `runwork deploy --detach` orchestration.
+ *
+ * Unlike `runwork dev --detach`, a deploy has no "ready" rendezvous to wait
+ * for -- it's fire-and-forget-then-poll. So the parent simply spawns a
+ * detached child (whose stdout/stderr go to `.runwork/deploy-*.log`), records
+ * an `in-progress` status, prints a poll hint, and exits. The child runs the
+ * real deploy and finalizes the status file to `succeeded`/`failed`.
+ *
+ * This exists so agents whose shell tool times out (~45s) can launch a deploy
+ * that survives, then poll `runwork deploy --status` (friction log #7).
+ */
+import * as fs from 'fs';
+import * as child_process from 'child_process';
+import { join } from 'path';
+import { looksLikeBunStandaloneArtifact } from '../dev/detach.js';
+/** Hidden marker passed to the spawned child. Not shown in --help. */
+export const DEPLOY_DETACHED_CHILD_FLAG = '--internal-detached-deploy-child';
+/** Whether this invocation is the detached deploy child. */
+export function isInternalDeployChild(argv = process.argv) {
+    return argv.includes(DEPLOY_DETACHED_CHILD_FLAG);
+}
+/**
+ * Build the args for the spawned child so it re-runs the same deploy in the
+ * foreground (the child must NOT re-detach). Drops `--detach`, any stale
+ * marker, and a Bun-on-Windows virtual-FS path; re-adds exactly one marker.
+ * Pure for testability.
+ */
+export function buildDeployChildArgs(parentArgv) {
+    const rest = [];
+    for (let i = 1; i < parentArgv.length; i++) {
+        if (i === 1 && looksLikeBunStandaloneArtifact(parentArgv[i]))
+            continue;
+        rest.push(parentArgv[i]);
+    }
+    const filtered = rest.filter((a) => a !== DEPLOY_DETACHED_CHILD_FLAG && a !== '--detach');
+    return [...filtered, DEPLOY_DETACHED_CHILD_FLAG];
+}
+/**
+ * Spawn the detached deploy child with stdout/stderr routed to
+ * `.runwork/deploy-{stdout,stderr}.log`. Cross-platform: uses
+ * `process.execPath` so it never depends on PATH (Bun-standalone-safe).
+ */
+export function spawnDetachedDeploy(childArgs, cwd) {
+    const dir = join(cwd, '.runwork');
+    fs.mkdirSync(dir, { recursive: true });
+    const stdoutFd = fs.openSync(join(dir, 'deploy-stdout.log'), 'w');
+    const stderrFd = fs.openSync(join(dir, 'deploy-stderr.log'), 'w');
+    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();
+        return { pid: proc.pid ?? 0 };
+    }
+    finally {
+        try {
+            fs.closeSync(stdoutFd);
+        }
+        catch { /* ignore */ }
+        try {
+            fs.closeSync(stderrFd);
+        }
+        catch { /* ignore */ }
+    }
+}

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

@@ -368,6 +368,45 @@ describe('session lifecycle primitives', () => {
             });
             expect(file.noSync).toBe(true);
         });
+        it('omits startupSync when not provided, includes it when provided', () => {
+            const base = {
+                pid: 1, sessionId: 's', appId: 'a', previewUrl: '', cliVersion: '0.0.0',
+                mode: 'detached', deps: { bootTime: () => 0 },
+            };
+            expect(buildSessionFile(base).startupSync).toBeUndefined();
+            const withSync = buildSessionFile({
+                ...base,
+                startupSync: { syncStatus: 'sync-failed', syncFailed: true, staleCode: true },
+            });
+            expect(withSync.startupSync).toEqual({ syncStatus: 'sync-failed', syncFailed: true, staleCode: true });
+        });
+    });
+    describe('startupSync field back-compat', () => {
+        it('round-trips startupSync through write/read', () => {
+            const file = buildSessionFile({
+                pid: process.pid,
+                sessionId: 's',
+                appId: 'a',
+                previewUrl: 'https://x',
+                cliVersion: '0.0.0',
+                mode: 'detached',
+                startupSync: { syncStatus: 'sync-failed', syncFailed: true, staleCode: true },
+                deps: { bootTime: () => 0 },
+            });
+            writeSessionFile(appDir, file);
+            const read = readSessionFile(appDir);
+            expect(read?.startupSync).toEqual({ syncStatus: 'sync-failed', syncFailed: true, staleCode: true });
+        });
+        it('accepts an older session file with no startupSync field', () => {
+            const file = buildSessionFile({
+                pid: process.pid, sessionId: 's', appId: 'a', previewUrl: 'https://x',
+                cliVersion: '0.0.0', mode: 'detached', deps: { bootTime: () => 0 },
+            });
+            writeSessionFile(appDir, file);
+            const read = readSessionFile(appDir);
+            expect(read).not.toBeNull();
+            expect(read?.startupSync).toBeUndefined();
+        });
     });
     describe('noSync field back-compat', () => {
         it('round-trips noSync through write/read', () => {

package/dist/dev/__tests__/startup-sync.test.d.ts

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

package/dist/dev/__tests__/startup-sync.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { buildStartupSyncSummary } from '../startup-sync.js';
+describe('dev/startup-sync', () => {
+    it('reports no-sync mode as neither failed nor stale', () => {
+        expect(buildStartupSyncSummary({ noSync: true })).toEqual({
+            syncStatus: 'no-sync',
+            syncFailed: false,
+            staleCode: false,
+        });
+    });
+    it('flags a failed startup sync as stale (preview serving old code)', () => {
+        expect(buildStartupSyncSummary({ noSync: false, status: 'sync-failed' })).toEqual({
+            syncStatus: 'sync-failed',
+            syncFailed: true,
+            staleCode: true,
+        });
+    });
+    it.each(['synced', 'merged', 'skipped'])('treats a %s startup sync as live (not stale)', (status) => {
+        expect(buildStartupSyncSummary({ noSync: false, status })).toEqual({
+            syncStatus: status,
+            syncFailed: false,
+            staleCode: false,
+        });
+    });
+    it('defaults to skipped when no status is provided', () => {
+        expect(buildStartupSyncSummary({ noSync: false })).toEqual({
+            syncStatus: 'skipped',
+            syncFailed: false,
+            staleCode: false,
+        });
+    });
+});

package/dist/dev/session.d.ts

@@ -14,6 +14,7 @@
  * See `docs/plans/2026-05-06-runwork-dev-lifecycle-design.md` for the full
  * lifecycle contract.
  */
+import type { StartupSyncSummary } from './startup-sync.js';
 export declare const SESSION_FILE_SCHEMA_VERSION = 1;
 /**
  * Tolerance (ms) when comparing the stored bootTime to the currently
@@ -40,6 +41,13 @@ export interface SessionFile {
      * treated as `false`.
      */
     noSync?: boolean;
+    /**
+     * Startup sync outcome, so a detached parent can relay stale-code warnings
+     * to the caller instead of those signals only living in the child's log
+     * (friction log #2). Optional for back-compat with session files that
+     * predate the field.
+     */
+    startupSync?: StartupSyncSummary;
 }
 export type SessionStaleReason = 'malformed' | 'version-mismatch' | 'app-id-mismatch' | 'boot-time-mismatch' | 'pid-dead';
 export type SessionState = {
@@ -161,6 +169,7 @@ export declare function buildSessionFile(input: {
     cliVersion: string;
     mode: SessionMode;
     noSync?: boolean;
+    startupSync?: StartupSyncSummary;
     startedAt?: number;
     deps?: SessionDeps;
 }): SessionFile;

package/dist/dev/session.js

@@ -113,7 +113,9 @@ function validateSessionFile(raw) {
         typeof r.cliVersion === 'string' &&
         (r.mode === 'foreground' || r.mode === 'detached') &&
         // Optional for back-compat: v1 files lack the field. Accept absent or boolean.
-        (r.noSync === undefined || typeof r.noSync === 'boolean'));
+        (r.noSync === undefined || typeof r.noSync === 'boolean') &&
+        // Optional: absent on older files; otherwise an object (shape from buildStartupSyncSummary).
+        (r.startupSync === undefined || (typeof r.startupSync === 'object' && r.startupSync !== null)));
 }
 /**
  * Read and parse the session file. Returns `null` for a missing file or
@@ -251,5 +253,6 @@ export function buildSessionFile(input) {
         cliVersion: input.cliVersion,
         mode: input.mode,
         noSync: input.noSync ?? false,
+        ...(input.startupSync ? { startupSync: input.startupSync } : {}),
     };
 }