runwork 0.14.0 → 0.15.0

package/dist/commands/doctor.js

@@ -1,7 +1,9 @@
 import { Command } from 'commander';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
-import { bold, dim, green, yellow, cyan } from '../ui/colors.js';
-import { runAllChecks } from '../health/runner.js';
+import { bold, dim, green, yellow, cyan, red } from '../ui/colors.js';
+import { runAllChecks, ALL_CHECK_NAMES } from '../health/runner.js';
+import { buildContext } from '../health/checks.js';
+import { applyDoctorFixes } from '../health/fix.js';
 import { detectCurrentAgent } from '../agents/runtime-detection.js';
 /**
  * Env vars worth surfacing in --verbose for AI agents debugging their own
@@ -98,6 +100,7 @@ const CHECK_LABELS = {
     'project-config': 'Project config',
     'app-exists': 'App exists',
     'git-remote': 'Git remote',
+    'deploy-freshness': 'Deploy freshness',
     'agent-setup': 'Agent setup',
 };
 function printHumanReport(report) {
@@ -147,12 +150,70 @@ function printHumanReport(report) {
     }
     console.log('');
 }
+function printFixOutcomes(outcomes) {
+    console.log('');
+    console.log(bold('Applying fixes'));
+    if (outcomes.length === 0) {
+        console.log(`  ${dim('Nothing to fix (no auto-remediable failures).')}`);
+        return;
+    }
+    for (const o of outcomes) {
+        const marker = o.applied ? green('[fixed]') : yellow('[skip]');
+        console.log(`  ${marker} ${o.name}: ${dim(o.message)}`);
+    }
+}
+/** Parse and validate `--check a,b,c` against the known check names. */
+function parseCheckNames(raw) {
+    const requested = raw.split(',').map(s => s.trim()).filter(Boolean);
+    const known = new Set(ALL_CHECK_NAMES);
+    const only = requested.filter(n => known.has(n));
+    const unknown = requested.filter(n => !known.has(n));
+    return { only, unknown };
+}
 export const doctorCommand = new Command('doctor')
     .description('Check system health: auth, network, project config, agent setup')
     .option('-v, --verbose', 'Include host-agent detection results, runtime info, and allowlisted env vars (useful for AI agents debugging their own environment)')
+    .option('--check <names>', `Run only the named checks (comma-separated). Available: ${ALL_CHECK_NAMES.join(', ')}`)
+    .option('--fix', 'Auto-remediate fixable failures (git credential helper, runwork remote), then re-check')
     .action(async (opts, command) => {
     const asJson = shouldOutputJson(command.optsWithGlobals().json);
-    const report = await runAllChecks();
+    // Resolve `--check` scope (if any) up front so both fix and report honor it.
+    let only;
+    if (opts.check) {
+        const parsed = parseCheckNames(opts.check);
+        if (parsed.unknown.length > 0) {
+            const msg = `Unknown check(s): ${parsed.unknown.join(', ')}. Available: ${ALL_CHECK_NAMES.join(', ')}`;
+            if (asJson) {
+                jsonOut({ success: false, command: 'doctor', error: msg });
+            }
+            else {
+                console.error(red(msg));
+            }
+            process.exit(1);
+        }
+        only = parsed.only;
+    }
+    // --- Fix flow: report, remediate fixable failures, re-check ---
+    if (opts.fix) {
+        const before = await runAllChecks({ only });
+        const failingNames = before.checks.filter(c => c.status === 'fail').map(c => c.name);
+        const ctx = buildContext();
+        const outcomes = await applyDoctorFixes(ctx, failingNames);
+        const after = await runAllChecks({ only });
+        if (asJson) {
+            jsonOut({ success: after.status !== 'fail', command: 'doctor', fixes: outcomes, report: after });
+        }
+        else {
+            printFixOutcomes(outcomes);
+            printHumanReport(after);
+        }
+        if (after.checks.some(c => c.status === 'fail')) {
+            process.exit(1);
+        }
+        return;
+    }
+    // --- Normal (optionally scoped) report ---
+    const report = await runAllChecks({ only });
     const verboseInfo = opts.verbose ? collectVerboseInfo() : null;
     if (asJson) {
         jsonOut(verboseInfo ? { ...report, verbose: verboseInfo } : report);

package/dist/commands/info.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { type SessionMode, type SessionStaleReason } from '../dev/session.js';
+import { type DeploySummary } from '../deploy/deploy-state.js';
 import type { WorkspaceAllData } from '../types.js';
 interface BlueprintEntity {
     entityName: string;
@@ -124,6 +125,8 @@ interface InfoOutput {
         url: string | null;
         deployed: boolean;
     };
+    /** Last deploy from this machine vs the current local HEAD (friction log #8). */
+    deploy: DeploySummary;
     integrations: Array<{
         id: string;
         status: string;

package/dist/commands/info.js

@@ -10,6 +10,7 @@ import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { resolveWorkspace } from '../workspace/resolve.js';
 import { getSessionState } from '../dev/session.js';
+import { getDeploySummary } from '../deploy/deploy-state.js';
 function readLocalDevSession(appDir, appId) {
     if (!appId)
         return { state: 'none' };
@@ -245,6 +246,15 @@ function printHumanOutput(data) {
         else {
             console.log(`  ${dim(pad('Production:'))}${dim('(not deployed)')}`);
         }
+        if (data.deploy.deployedShortSha) {
+            const localPart = data.deploy.localShortSha ? `, local ${data.deploy.localShortSha}` : '';
+            const sync = data.deploy.inSync === true
+                ? green('in sync')
+                : data.deploy.inSync === false
+                    ? yellow('local has undeployed commits')
+                    : dim('unknown');
+            console.log(`  ${dim(pad('Last deploy:'))}${data.deploy.deployedShortSha}${dim(localPart)} ${sync}`);
+        }
         // Local dev session view: what's running on THIS machine, from the
         // session file. This may disagree with the server's "preview"
         // status above; that's diagnostic, not a bug.
@@ -428,6 +438,7 @@ export const infoCommand = new Command('info')
         preview,
         localDevSession,
         production: appInfo?.production ?? { url: null, deployed: false },
+        deploy: getDeploySummary(process.cwd()),
         integrations,
         registries,
         cli: {

package/dist/commands/sync.js

@@ -16,7 +16,7 @@ import { buildShareConversationSkill, buildSaveConversationSkill, BUILT_IN_SKILL
 import { computeSyncPlan } from '../sync/change-detect.js';
 import { printSyncSummary, resolveConflict, resolveConflictNonInteractive } from '../sync/conflict-ui.js';
 import { executeSyncPlan } from '../sync/executor.js';
-import { getRegistryAgent, resolveToAbsolute } from '../agents/registry.js';
+import { getRegistryAgent, resolveToAbsolute, isConnectOnlyAgent } from '../agents/registry.js';
 function loadSetupState(filePath) {
     if (!existsSync(filePath))
         return null;
@@ -340,6 +340,13 @@ export async function syncFromState(state, statePath, credentials, opts) {
         hookInstallCalls: 0,
     };
     for (const adapter of adapters) {
+        // Connect-only agents (e.g. ChatGPT) have no local files to write; the
+        // connector lives in the user's account. Skip all local-write phases.
+        if (isConnectOnlyAgent(getRegistryAgent(adapter.slug))) {
+            console.log(`  [${adapter.name}] Connect-only agent: no local files to sync`);
+            summary.adaptersProcessed++;
+            continue;
+        }
         let adapterFailedAnyScope = false;
         for (const scope of scopes) {
             try {
@@ -433,6 +440,8 @@ export async function syncFromState(state, statePath, credentials, opts) {
     }
     // Write team instructions and/or per-agent extra instructions.
     for (const adapter of adapters) {
+        if (isConnectOnlyAgent(getRegistryAgent(adapter.slug)))
+            continue;
         if (!adapter.writeTeamInstructions)
             continue;
         const agentExtra = agentConfigs?.[adapter.slug]?.extraInstructions;
@@ -455,6 +464,8 @@ export async function syncFromState(state, statePath, credentials, opts) {
     // User scope is handled below in the unified defaults+network+minimum block.
     if (agentConfigs) {
         for (const adapter of adapters) {
+            if (isConnectOnlyAgent(getRegistryAgent(adapter.slug)))
+                continue;
             const agentConfig = agentConfigs[adapter.slug];
             if (!agentConfig || !adapter.writeAgentConfig)
                 continue;
@@ -507,6 +518,8 @@ export async function syncFromState(state, statePath, credentials, opts) {
         if (!state.agentDefaults)
             state.agentDefaults = {};
         for (const adapter of adapters) {
+            if (isConnectOnlyAgent(getRegistryAgent(adapter.slug)))
+                continue;
             if (!adapter.writeAgentConfig)
                 continue;
             const slug = adapter.slug;

package/dist/commands/validate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const validateCommand: Command;

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;