runwork 0.13.4 → 0.15.0

package/dist/commands/dev.js

@@ -8,6 +8,10 @@ import { watchAndAutoCommit, stopAutoCommit } from '../git/auto-commit.js';
 import { syncWithRemote } from '../git/sync.js';
 import { snapshotCriticalFiles, restoreMissingCriticalFiles, commitAndPushRestoredFiles } from '../git/critical-files.js';
 import { ensureGitIdentity } from '../git/identity.js';
+import { ensureGitCredentialHelper } from '../git/credentials.js';
+import { ensureRunworkRemote } from '../git/remote.js';
+import { diagnoseSyncError } from '../git/classify-sync-error.js';
+import { buildStartupSyncSummary } from '../dev/startup-sync.js';
 import { requireGit } from '../git/preflight.js';
 import { startLogTailer } from '../logs/tailer.js';
 import { startPreviewUrlPoller } from '../dev/preview-url-poller.js';
@@ -110,6 +114,17 @@ export async function execDev(options) {
     // fresh machine where `git config --global user.email/.name` has never
     // been set (extremely common on Windows after a clean install).
     ensureGitIdentity(cwd, creds);
+    // Ensure git can authenticate to the runwork remote before the sync loop
+    // fetches/pushes. Headless auth (get_cli_setup / hand-written credentials)
+    // registers API creds but not the git helper. See
+    // git/credentials.ts:ensureGitCredentialHelper.
+    if (creds?.baseUrl) {
+        await ensureGitCredentialHelper(creds.baseUrl);
+    }
+    // Ensure the `runwork` remote exists and points at the canonical URL. A
+    // manual `git clone <url>` names the remote `origin`, which otherwise makes
+    // the sync loop fail with "'runwork' does not appear to be a git repository".
+    ensureRunworkRemote(cwd, client.getGitRemoteUrl(config.workspaceId, config.appId));
     // Detect user edits made outside of `runwork dev`. When this fires
     // for an AI agent, it almost always means the agent edited code
     // before starting dev -- the wrong order. We surface this loudly so
@@ -189,6 +204,10 @@ export async function execDev(options) {
     await populateSkill(cwd, client, config.appId);
     if (useJson)
         jsonLine({ event: 'startup', phase: 'skill_fetched', timestamp: ts() });
+    // Track the startup sync outcome so `session_started` can tell agents
+    // whether the preview reflects their latest edits or is serving stale code
+    // (friction log #2: a happy session_started masked a failed initial sync).
+    let startupSync = buildStartupSyncSummary({ noSync });
     // Sync. In no-sync mode we never mutate the working tree: instead of
     // syncWithRemote (rebase/merge/commit/push) we do a best-effort,
     // read-only `git fetch` so remote-tracking refs stay current and
@@ -212,6 +231,7 @@ export async function execDev(options) {
             console.log(dim('Syncing...'));
         const criticalSnapshot = snapshotCriticalFiles(cwd);
         const syncResult = syncWithRemote(cwd);
+        startupSync = buildStartupSyncSummary({ noSync: false, status: syncResult.status });
         const restoredCriticalFiles = restoreMissingCriticalFiles(cwd, criticalSnapshot);
         if (restoredCriticalFiles.length > 0) {
             const pushed = commitAndPushRestoredFiles(cwd, restoredCriticalFiles);
@@ -233,37 +253,24 @@ export async function execDev(options) {
         if (useJson) {
             jsonLine({ event: 'startup', phase: 'sync', status: syncResult.status, pushed: syncResult.pushed, timestamp: ts() });
             if (syncResult.status === 'sync-failed') {
-                if (syncResult.error === 'stash-conflict') {
-                    jsonLine({
-                        event: 'error',
-                        phase: 'sync',
-                        timestamp: ts(),
-                        error: {
-                            message: 'Merge conflicts detected after stash pop',
-                            diagnosis: 'Local changes could not be automatically merged with the remote state. The stash pop resulted in conflicts that require manual resolution.',
-                            suggestions: [
-                                'Resolve the merge conflicts in the affected files',
-                                'Run git add on resolved files, then git commit',
-                                'Run runwork dev again after resolving conflicts',
-                            ],
-                        },
-                    });
-                    process.exit(1);
-                }
+                const diag = diagnoseSyncError(syncResult.error);
                 jsonLine({
                     event: 'error',
                     phase: 'sync',
                     timestamp: ts(),
                     error: {
-                        message: syncResult.error ?? 'File sync failed',
-                        diagnosis: 'Could not sync files to the sandbox. This usually means the sandbox session expired or the network connection was interrupted.',
-                        suggestions: [
-                            'Run runwork dev again to start a fresh session',
-                            'Check your network connection',
-                            'Run runwork doctor to diagnose environment issues',
-                        ],
+                        reason: diag.reason,
+                        message: diag.message,
+                        diagnosis: diag.diagnosis,
+                        suggestions: diag.suggestions,
                     },
                 });
+                // A stash-pop conflict leaves the working tree in a state the user
+                // must resolve, so we stop. Other sync failures are non-fatal -- the
+                // preview keeps serving the last good state -- so we continue.
+                if (syncResult.error === 'stash-conflict') {
+                    process.exit(1);
+                }
             }
         }
         else {
@@ -277,16 +284,20 @@ export async function execDev(options) {
                 case 'merged':
                     console.log(yellow('  Merged with Runwork (histories diverged).'));
                     break;
-                case 'sync-failed':
+                case 'sync-failed': {
+                    const diag = diagnoseSyncError(syncResult.error);
                     if (syncResult.error === 'stash-conflict') {
-                        console.error('Merge conflicts detected after stash pop. Resolve conflicts and restart.');
+                        console.error(`${diag.message}. ${diag.diagnosis}`);
+                        for (const s of diag.suggestions)
+                            console.error(dim(`  - ${s}`));
                         process.exit(1);
                     }
-                    console.warn(yellow(`Sync failed. Continuing...`));
-                    if (syncResult.error) {
-                        console.warn(dim(`  ${syncResult.error}`));
-                    }
+                    console.warn(yellow(`Sync failed: ${diag.message}. Continuing...`));
+                    console.warn(dim(`  ${diag.diagnosis}`));
+                    for (const s of diag.suggestions)
+                        console.warn(dim(`  - ${s}`));
                     break;
+                }
             }
             if (!syncResult.pushed && syncResult.status !== 'skipped' && syncResult.status !== 'sync-failed') {
                 console.warn(yellow('Push failed. Continuing with current state...'));
@@ -311,13 +322,33 @@ export async function execDev(options) {
         cliVersion: VERSION,
         mode,
         noSync,
+        // Persist the startup sync outcome so the detached parent can relay
+        // stale-code warnings -- not just the child's own log (friction log #2).
+        startupSync,
     }));
-    // Emit session_started (JSON) or show banner (human)
+    // Emit session_started (JSON) or show banner (human). We always emit
+    // session_started -- it's the rendezvous signal `runwork dev --detach`
+    // polls for -- but carry the startup sync outcome so agents don't mistake a
+    // stale preview for one reflecting their latest edits. `staleCode: true`
+    // means the initial sync failed and the preview is serving the last good
+    // state, not the current working tree.
     if (useJson) {
-        jsonLine({ event: 'session_started', previewUrl: currentPreviewUrl, appName: config.appName, timestamp: ts(), guide: buildDevSessionGuide() });
+        jsonLine({
+            event: 'session_started',
+            previewUrl: currentPreviewUrl,
+            appName: config.appName,
+            syncStatus: startupSync.syncStatus,
+            syncFailed: startupSync.syncFailed,
+            staleCode: startupSync.staleCode,
+            timestamp: ts(),
+            guide: buildDevSessionGuide(),
+        });
     }
     else {
         console.log(getDevBanner({ appName: config.appName, previewUrl: currentPreviewUrl, workspaceName: config.workspaceName }));
+        if (startupSync.syncFailed) {
+            console.log(yellow('  Warning: initial sync failed. The preview shows the last deployed code, NOT your latest changes.'));
+        }
         console.log(getKeyboardHints());
         console.log('');
         console.log(dim('  ─────────────────────────────────────────────'));
@@ -568,6 +599,9 @@ async function runDevDetachParent(opts) {
     switch (outcome.result) {
         case 'started': {
             const f = outcome.file;
+            // Relay the child's startup sync outcome so a detached caller learns the
+            // preview may be serving stale code (the child only logs it otherwise).
+            const syncFailed = f.startupSync?.syncFailed ?? false;
             if (opts.json) {
                 jsonLine({
                     event: 'session_started',
@@ -575,6 +609,9 @@ async function runDevDetachParent(opts) {
                     pid: f.pid,
                     sessionId: f.sessionId,
                     mode: f.mode,
+                    syncStatus: f.startupSync?.syncStatus,
+                    syncFailed,
+                    staleCode: f.startupSync?.staleCode ?? false,
                     timestamp: ts(),
                     guide: buildDevSessionGuide(),
                 });
@@ -583,6 +620,9 @@ async function runDevDetachParent(opts) {
                 console.log('');
                 console.log(`Dev session running in background (PID ${f.pid}).`);
                 console.log(`  Preview: ${green(f.previewUrl)}`);
+                if (syncFailed) {
+                    console.log(yellow('  Warning: initial sync failed. The preview shows the last deployed code, NOT your latest changes.'));
+                }
                 console.log(dim(`  Stop with: runwork dev stop`));
                 console.log(dim(`  Logs:      tail -f .runwork/dev-stdout.log`));
                 console.log('');

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/mcp-entries.d.ts

@@ -0,0 +1,13 @@
+import type { McpServerConfig } from '../types.js';
+import type { McpServerEntry } from '../agents/types.js';
+/**
+ * Build local-agent MCP entries for external (third-party) servers added to the
+ * workspace. Auth handling by `authType`:
+ * - 'header': inject the user's resolved per-server headers (decrypted server-side).
+ * - 'oauth': emit no auth header so the local agent runs its own browser flow.
+ * - 'none'/unset: no auth header.
+ *
+ * Critically, external entries never receive the Runwork platform API key. That key
+ * belongs only on the Runwork workspace-tools entry, which is added separately.
+ */
+export declare function buildExternalMcpEntries(mcpServers: McpServerConfig[], resolvedCredentials: Record<string, Record<string, string>>): McpServerEntry[];

package/dist/commands/mcp-entries.js

@@ -0,0 +1,26 @@
+import { RUNWORK_MCP_PREFIX } from '../agents/types.js';
+/**
+ * Build local-agent MCP entries for external (third-party) servers added to the
+ * workspace. Auth handling by `authType`:
+ * - 'header': inject the user's resolved per-server headers (decrypted server-side).
+ * - 'oauth': emit no auth header so the local agent runs its own browser flow.
+ * - 'none'/unset: no auth header.
+ *
+ * Critically, external entries never receive the Runwork platform API key. That key
+ * belongs only on the Runwork workspace-tools entry, which is added separately.
+ */
+export function buildExternalMcpEntries(mcpServers, resolvedCredentials) {
+    return mcpServers
+        .filter(s => s.enabled)
+        .map(s => {
+        const resolved = s.authType === 'header' ? resolvedCredentials[s.id] : undefined;
+        const headers = resolved && Object.keys(resolved).length > 0 ? resolved : undefined;
+        return {
+            name: `${RUNWORK_MCP_PREFIX}${s.name}`,
+            url: s.url,
+            transport: s.transport,
+            ...(headers ? { headers } : {}),
+            description: `Runwork MCP server: ${s.name}. Provides tools for interacting with this workspace resource.`,
+        };
+    });
+}

package/dist/commands/sync.js

@@ -7,6 +7,7 @@ import { ApiClient } from '../api/client.js';
 import { getAdapterBySlug, detectAgents } from '../agents/detect.js';
 import { CodexAdapter } from '../agents/codex.js';
 import { RUNWORK_MCP_PREFIX, RUNWORK_WORKSPACE_MCP_NAME } from '../agents/types.js';
+import { buildExternalMcpEntries } from './mcp-entries.js';
 import { RUNWORK_AGENT_DEFAULTS, AGENT_DEFAULTS_SCHEMA_VERSION } from '../agents/default-config.js';
 import { resolveAgentDefaults } from '../agents/defaults-merge.js';
 import { collectTelemetryEvents, printTelemetryVerbose, summarizeTelemetryForDryRun, } from './sync-telemetry.js';
@@ -15,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;
@@ -135,7 +136,7 @@ export async function syncFromState(state, statePath, credentials, opts) {
     }
     console.log('  Fetching workspace data...');
     // Fetch latest data (includeContent=true gets all skill content in one request)
-    const [allSkills, mcpServers, externalSkills, registries, connectedIntegrations] = await Promise.all([
+    const [allSkills, mcpServers, externalSkills, registries, connectedIntegrations, resolvedMcpCredentials] = await Promise.all([
         client.listWorkspaceSkills(state.workspaceId, true),
         client.listMcpServers(state.workspaceId),
         client.listExternalSkills(state.workspaceId),
@@ -143,6 +144,9 @@ export async function syncFromState(state, statePath, credentials, opts) {
         client.listConnectedIntegrations(state.workspaceId)
             .then(list => list.map(i => i.canonicalId ?? i.integrationId))
             .catch(() => []),
+        // Decrypted auth headers for header-auth servers, scoped to this user.
+        // Tolerate older backends that lack the endpoint.
+        client.resolveMcpCredentials(state.workspaceId).catch(() => ({})),
     ]);
     const appCount = allSkills.filter(s => s.type === 'app').length;
     const parts = [];
@@ -167,15 +171,7 @@ export async function syncFromState(state, statePath, credentials, opts) {
     }
     // Build MCP entries (pull-only)
     const baseUrl = credentials.baseUrl || 'https://runwork.ai';
-    const mcpEntries = mcpServers
-        .filter(s => s.enabled)
-        .map(s => ({
-        name: `${RUNWORK_MCP_PREFIX}${s.name}`,
-        url: s.url,
-        transport: s.transport,
-        headers: { Authorization: `Bearer ${credentials.apiKey}` },
-        description: `Runwork MCP server: ${s.name}. Provides tools for interacting with this workspace resource.`,
-    }));
+    const mcpEntries = buildExternalMcpEntries(mcpServers, resolvedMcpCredentials);
     mcpEntries.push({
         name: RUNWORK_WORKSPACE_MCP_NAME,
         url: `${baseUrl}/api/workspaces/${state.workspaceId}/mcp`,
@@ -344,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 {
@@ -437,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;
@@ -459,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;
@@ -511,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 {};