runwork 0.14.0 → 0.15.0

package/dist/commands/clone.js

@@ -13,6 +13,10 @@ import { runAgentWizard } from '../ui/banner.js';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
 import { buildCloneGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 import { ensureGitIdentity } from '../git/identity.js';
+import { ensureGitCredentialHelper } from '../git/credentials.js';
+import { ensureRunworkRemote } from '../git/remote.js';
+import { hardenRepoForRestrictedFs } from '../git/repo-config.js';
+import { classifySyncError } from '../git/classify-sync-error.js';
 import { requireGit } from '../git/preflight.js';
 import { formatError } from '../utils/format-error.js';
 export async function execClone(client, app, directory, creds) {
@@ -58,16 +62,24 @@ export async function execClone(client, app, directory, creds) {
             execFileSync('git', ['symbolic-ref', 'HEAD', 'refs/heads/main'], { cwd: dir, stdio: 'pipe' });
         }
         catch { /* best-effort: push uses HEAD:main so this is just cleanliness */ }
+        // Disable background gc/maintenance so pack rewrites don't fail on
+        // restricted filesystems (e.g. some agent "outputs" mounts). Harmless on
+        // normal filesystems. See git/repo-config.ts.
+        hardenRepoForRestrictedFs(dir);
     }
     // Seed a local git identity so subsequent commits do not fail on machines
     // (commonly fresh Windows installs) without `git config --global user.email`.
     ensureGitIdentity(dir, creds);
-    try {
-        execFileSync('git', ['remote', 'set-url', 'runwork', remoteUrl], { cwd: dir, stdio: 'pipe' });
-    }
-    catch {
-        execFileSync('git', ['remote', 'add', 'runwork', remoteUrl], { cwd: dir, stdio: 'pipe' });
+    // Make sure git can authenticate to the runwork remote before we fetch.
+    // Headless auth paths (the get_cli_setup MCP tool, or a hand-written
+    // ~/.runwork/.credentials) register API creds but not the git helper, so
+    // without this the fetch below silently fails and we fall back to a
+    // template-only scaffold. See git/credentials.ts:ensureGitCredentialHelper.
+    if (creds?.baseUrl) {
+        await ensureGitCredentialHelper(creds.baseUrl);
     }
+    ensureRunworkRemote(dir, remoteUrl);
+    let source = { pulled: true };
     try {
         execFileSync('git', ['fetch', 'runwork', 'main'], { cwd: dir, stdio: 'pipe' });
         // Reset to remote HEAD - overlays git-tracked files on top of template
@@ -76,11 +88,19 @@ export async function execClone(client, app, directory, creds) {
         execFileSync('git', ['checkout', '.'], { cwd: dir, stdio: 'pipe' });
     }
     catch (err) {
-        // Distinguish "remote is empty" (expected for brand-new apps) from
-        // real failures. We print both the generic next-step hint and the
-        // underlying error so authentication / network failures aren't lost.
-        console.warn('Could not pull from runwork remote. Starting with template only.');
-        console.warn(`  ${formatError(err)}`);
+        source = pullOutcomeFromError(err);
+        if (source.reason === 'empty-remote') {
+            // Brand-new app: the remote has no `main` branch yet. Expected and
+            // benign -- the template scaffold IS the starting point.
+            console.warn('No source pushed for this app yet. Starting from the template scaffold.');
+        }
+        else {
+            // A real failure (auth, missing remote, network). The scaffold here is
+            // NOT the app's code -- surface it loudly so the caller fails instead of
+            // silently editing the wrong files.
+            console.warn('Could not pull the app source from the runwork remote.');
+            console.warn(`  ${formatError(err)}`);
+        }
     }
     // Write .runwork.json config
     const config = {
@@ -107,8 +127,45 @@ export async function execClone(client, app, directory, creds) {
         directory: resolve(dir),
         workspaceId: app.workspaceId,
         workspaceName: app.workspaceName,
+        source,
     };
 }
+/** Pull the raw git stderr off an execFileSync error for classification. */
+function extractStderr(err) {
+    const e = err;
+    if (e?.stderr)
+        return e.stderr.toString().trim();
+    return formatError(err);
+}
+/**
+ * Whether a failed `git fetch runwork main` means the remote simply has no
+ * `main` branch yet (a brand-new app), as opposed to an auth/network/remote
+ * failure. Git reports this as "couldn't find remote ref main".
+ */
+function isEmptyRemote(stderr) {
+    const s = stderr.toLowerCase();
+    return s.includes("couldn't find remote ref") || s.includes('could not find remote ref');
+}
+/**
+ * Turn a failed-pull error into a CloneSource: an empty remote (benign,
+ * brand-new app) vs a classified real failure (auth/network/no-remote) that
+ * leaves a template-only scaffold.
+ */
+export function pullOutcomeFromError(err) {
+    const detail = extractStderr(err);
+    if (isEmptyRemote(detail)) {
+        return { pulled: false, reason: 'empty-remote', detail };
+    }
+    return { pulled: false, reason: classifySyncError(detail), detail };
+}
+/**
+ * A clone is a real failure -- a template-only scaffold rather than the app's
+ * code -- when the source pull didn't happen for any reason other than an
+ * empty remote. Callers must not report success in that case.
+ */
+export function isCloneSourceFailure(source) {
+    return !source.pulled && source.reason !== 'empty-remote';
+}
 /**
  * Reconcile positional args with --app. When --app is provided, the first
  * positional argument is intended as the *directory* -- not another appId
@@ -123,11 +180,24 @@ export function normalizeCloneArgs(appId, directory, options) {
     }
     return { appId, directory };
 }
+/**
+ * Help epilogue shown under `runwork clone --help`. Agents tend to read help
+ * before running, so we surface the restricted-mount caveat (friction log #9)
+ * here. Exported so it can be asserted on directly (commander's help-text
+ * hooks aren't reflected by `helpInformation()`).
+ */
+export const RESTRICTED_FS_HELP = `
+Note for AI agents: clone into a normal working directory. Some sandboxed
+"outputs" mounts (e.g. certain agent environments) disallow the unlink
+operations git uses for pack files, which can corrupt the repo with errors
+like "unable to unlink '.git/objects/pack/...': Operation not permitted". If
+you hit that, clone into your home directory or another standard path instead.`;
 export const cloneCommand = new Command('clone')
     .description('Clone a Runwork app to local development')
     .argument('[appId]', 'App ID to clone (interactive if omitted)')
     .argument('[directory]', 'Target directory')
     .option('--app <name-or-id>', 'App name or ID (skips interactive selection)')
+    .addHelpText('after', RESTRICTED_FS_HELP)
     .action(async (rawAppId, rawDirectory, options) => {
     requireGit('clone');
     const { appId, directory } = normalizeCloneArgs(rawAppId, rawDirectory, options);
@@ -156,20 +226,45 @@ export const cloneCommand = new Command('clone')
         console.log(`Cloning "${app.name}"...`);
     }
     const cloneResult = await execClone(client, app, directory, creds);
+    // A real pull failure (auth/network/missing-remote) left a template-only
+    // scaffold that is NOT the app's deployed code. Report it as a failure so
+    // an agent doesn't start editing the wrong files (friction log #1).
+    const pullFailed = isCloneSourceFailure(cloneResult.source);
     if (useJson) {
+        if (pullFailed) {
+            jsonOut(buildErrorResponse('clone', 'Cloned the scaffold but could not pull the app source', `git could not fetch the app's source (${cloneResult.source.reason}), so the directory holds only the template scaffold, not the deployed code. ${cloneResult.source.detail ?? ''}`.trim(), [
+                'Run `runwork doctor --fix` to repair git auth and the runwork remote',
+                `Then re-clone: runwork clone --app ${cloneResult.appName}`,
+            ]));
+            process.exit(1);
+        }
         const response = {
             success: true,
             command: 'clone',
             result: cloneResult,
+            warning: cloneResult.source.reason === 'empty-remote'
+                ? 'This app has no source pushed yet. The directory is the starting template scaffold.'
+                : undefined,
             guide: buildCloneGuide(cloneResult.appName, cloneResult.slug),
         };
         jsonOut(response);
         return;
     }
+    if (pullFailed) {
+        console.error(`\nCloned the scaffold for "${cloneResult.appName}", but could NOT pull the app source (${cloneResult.source.reason}).`);
+        console.error('The directory holds only the template scaffold, not the deployed code.');
+        console.error('Fix git access, then re-clone:');
+        console.error('  runwork doctor --fix');
+        console.error(`  runwork clone --app ${cloneResult.appName}`);
+        process.exit(1);
+    }
     // No trailing separator: cloneResult.directory is already an absolute
     // path. Appending '/' here mixed with Windows '\' separators produced
     // confusing output like `C:\Users\...\app/` on Windows.
     console.log(`\nApp "${cloneResult.appName}" cloned to ${cloneResult.directory}`);
+    if (cloneResult.source.reason === 'empty-remote') {
+        console.log('Note: no source pushed for this app yet. Starting from the template scaffold.');
+    }
     console.log(`Remote: ${client.getGitRemoteUrl(cloneResult.workspaceId, cloneResult.appId)}`);
     await runAgentWizard(cloneResult.directory);
     console.log(`Next: cd ${cloneResult.slug} && runwork dev`);

package/dist/commands/deploy.js

@@ -1,11 +1,18 @@
-import { Command } from 'commander';
+import { Command, Option } 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 { shouldOutputJson, jsonOut, jsonLine } from '../utils/output.js';
+import { dim, green, yellow } from '../ui/colors.js';
+import { getHeadSha, writeDeployState, getDeploySummary } from '../deploy/deploy-state.js';
+import { writeDeployStatus, readDeployStatus, deployLogPath } from '../deploy/deploy-status.js';
+import { isInternalDeployChild, buildDeployChildArgs, spawnDetachedDeploy, DEPLOY_DETACHED_CHILD_FLAG } from '../deploy/detach.js';
 import { buildDeployGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 import { requireGit } from '../git/preflight.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 { commitWorkingTree } from '../git/auto-commit.js';
 import { syncWithRemote, hasCommits } from '../git/sync.js';
 import { snapshotCriticalFiles, restoreMissingCriticalFiles, commitAndPushRestoredFiles } from '../git/critical-files.js';
@@ -14,8 +21,14 @@ import { promptConfirm } from '../utils/prompt.js';
 export const deployCommand = new Command('deploy')
     .description('Deploy the current app to production')
     .option('-y, --yes', 'Skip the confirmation prompt when the working tree differs from the preview')
+    .option('--detach', 'Run the deploy in the background and return immediately. Logs go to .runwork/deploy-{stdout,stderr}.log; poll `runwork deploy --status`.')
+    .option('--status', 'Show the status (in-progress/succeeded/failed) of the last deploy started from this machine, plus the deployed-vs-local commit.')
+    // Hidden marker the `--detach` parent passes to its background child. Not
+    // for end users -- registered so commander accepts it on the child.
+    .addOption(new Option(DEPLOY_DETACHED_CHILD_FLAG).hideHelp())
     .action(async (opts, command) => {
     const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    const cwd = process.cwd();
     if (!existsSync('.runwork.json')) {
         if (useJson) {
             jsonOut(buildErrorResponse('deploy', 'No .runwork.json found', 'This directory is not a Runwork app.', ['Run runwork init to create an app first', 'Or cd into an existing app directory']));
@@ -24,11 +37,50 @@ export const deployCommand = new Command('deploy')
         console.error('No .runwork.json found. Run `runwork init` first.');
         process.exit(1);
     }
+    // --status: a local read; no auth/git required.
+    if (opts.status) {
+        printDeployStatus(cwd, useJson);
+        return;
+    }
     requireGit('deploy');
     const config = JSON.parse(readFileSync('.runwork.json', 'utf-8'));
+    const isChild = isInternalDeployChild(process.argv);
+    // --detach parent: spawn a background child running the real deploy,
+    // record an in-progress status, print a poll hint, and exit immediately so
+    // the launching shell doesn't time out (friction log #7).
+    if (opts.detach && !isChild) {
+        const startedAt = new Date().toISOString();
+        const handle = spawnDetachedDeploy(buildDeployChildArgs(process.argv), cwd);
+        writeDeployStatus(cwd, { state: 'in-progress', startedAt, pid: handle.pid });
+        if (useJson) {
+            jsonLine({ event: 'deploy_started', detached: true, pid: handle.pid, logPath: deployLogPath(cwd), startedAt, hint: 'Poll `runwork deploy --status` for completion.' });
+        }
+        else {
+            console.log(`Deploy started in the background (pid ${handle.pid}).`);
+            console.log(`Logs:  ${deployLogPath(cwd)}`);
+            console.log('Check: runwork deploy --status');
+        }
+        return;
+    }
+    // The detached child finalizes the status file on exit. If it crashes or
+    // hits any `process.exit(1)` failure path before the success block marks
+    // it done, record `failed` so `--status` doesn't report a stuck deploy.
+    // Register this BEFORE requireAuth(): a child whose credentials expired
+    // between spawn and run would otherwise exit in requireAuth() with the
+    // status stuck at `in-progress`. (requireGit/config above ran identically
+    // in the parent before it spawned this child, so they can't fail here.)
+    let deployFinalized = false;
+    const childStartedAt = readDeployStatus(cwd)?.startedAt ?? new Date().toISOString();
+    if (isChild) {
+        jsonLine({ event: 'deploy_started', startedAt: childStartedAt });
+        process.on('exit', (code) => {
+            if (!deployFinalized && code !== 0) {
+                writeDeployStatus(cwd, { state: 'failed', startedAt: childStartedAt, finishedAt: new Date().toISOString(), error: `deploy process exited with code ${code}` });
+            }
+        });
+    }
     const creds = requireAuth();
     const client = new ApiClient(creds);
-    const cwd = process.cwd();
     // Deploy guard: the preview reflects the last *pushed* commit. If the
     // working tree is dirty or ahead of `runwork/main` and no auto-syncing
     // dev session is keeping the preview in lockstep, `runwork deploy` will
@@ -42,8 +94,9 @@ export const deployCommand = new Command('deploy')
             // Agents must never be blocked: the warning rides along in the
             // final success response below so we proceed without prompting.
         }
-        else if (opts.yes || !process.stdin.isTTY) {
-            // Non-interactive (no TTY) or explicit --yes: warn and proceed.
+        else if (opts.yes || isChild || !process.stdin.isTTY) {
+            // Non-interactive (no TTY), the detached child, or explicit --yes:
+            // warn and proceed without prompting.
             console.warn(deployGuardWarning);
         }
         else {
@@ -61,6 +114,16 @@ export const deployCommand = new Command('deploy')
     // `ensureGitIdentity` seeds a local identity so the commit cannot fail
     // on a fresh machine where git user.email/.name were never configured.
     ensureGitIdentity(cwd, creds);
+    // Ensure git can authenticate to the runwork remote before sync/push.
+    // 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, so a
+    // manually `git clone`d repo (remote named `origin`) still syncs/pushes.
+    ensureRunworkRemote(cwd, client.getGitRemoteUrl(config.workspaceId, config.appId));
     if (!useJson)
         console.log('Syncing...');
     try {
@@ -94,15 +157,14 @@ export const deployCommand = new Command('deploy')
         }
     }
     if (syncResult.status === 'sync-failed') {
-        const reason = syncResult.error && syncResult.error !== 'stash-conflict'
-            ? syncResult.error
-            : 'Local history could not be reconciled with the remote.';
+        const diag = diagnoseSyncError(syncResult.error);
         if (useJson) {
-            jsonOut(buildErrorResponse('deploy', 'Sync failed before deployment', reason, ['Run git fetch runwork && git rebase runwork/main and resolve any conflicts', 'Or run runwork dev to sync interactively', 'Then retry runwork deploy']));
+            jsonOut(buildErrorResponse('deploy', 'Sync failed before deployment', diag.diagnosis, [...diag.suggestions, 'Then retry runwork deploy']));
             process.exit(1);
         }
-        console.error(`Sync failed: ${reason}`);
-        console.error('Resolve conflicts (git status), or run `runwork dev`, then retry `runwork deploy`.');
+        console.error(`Sync failed: ${diag.message}. ${diag.diagnosis}`);
+        for (const s of diag.suggestions)
+            console.error(`  - ${s}`);
         process.exit(1);
     }
     if (!syncResult.pushed) {
@@ -143,6 +205,21 @@ export const deployCommand = new Command('deploy')
         console.error('Run `runwork info` to check state, or `runwork logs --production` to inspect errors.');
         process.exit(1);
     }
+    // Record what we just deployed (local HEAD == the pushed/deployed commit)
+    // so `runwork info` / `deploy --status` can cheaply compare it to HEAD
+    // later without scraping the production bundle.
+    const deployedSha = getHeadSha(cwd);
+    const finishedAt = new Date().toISOString();
+    if (deployedSha) {
+        writeDeployState(cwd, { sha: deployedSha, deployedAt: finishedAt, url: deploymentUrl });
+    }
+    // Mark the deploy finished so the child's exit hook doesn't overwrite this
+    // with a `failed` status, and so `runwork deploy --status` reports success.
+    deployFinalized = true;
+    writeDeployStatus(cwd, { state: 'succeeded', startedAt: childStartedAt, finishedAt, url: deploymentUrl, sha: deployedSha ?? undefined });
+    if (isChild) {
+        jsonLine({ event: 'deploy_succeeded', url: deploymentUrl, deployedSha, finishedAt });
+    }
     if (useJson) {
         const response = {
             success: true,
@@ -151,6 +228,7 @@ export const deployCommand = new Command('deploy')
                 deployed,
                 url: deploymentUrl,
                 appName: config.appName,
+                deployedSha,
             },
             guide: buildDeployGuide(),
             ...(deployGuardWarning ? { warning: deployGuardWarning } : {}),
@@ -159,4 +237,43 @@ export const deployCommand = new Command('deploy')
         return;
     }
     console.log(`Deployed: ${deploymentUrl}`);
+    if (deployedSha)
+        console.log(dim(`Commit: ${deployedSha.slice(0, 7)}`));
 });
+/**
+ * Print the status of the last deploy started from this machine
+ * (`runwork deploy --status`), reconciled with the deployed-vs-local commit
+ * comparison from deploy-state.
+ */
+function printDeployStatus(cwd, useJson) {
+    const status = readDeployStatus(cwd);
+    const summary = getDeploySummary(cwd);
+    if (useJson) {
+        jsonOut({ success: true, command: 'deploy', result: { status, deploy: summary } });
+        return;
+    }
+    if (!status) {
+        console.log('No deploy has been started from this machine yet.');
+    }
+    else {
+        const label = status.state === 'succeeded' ? green('succeeded')
+            : status.state === 'failed' ? yellow('failed')
+                : 'in-progress';
+        console.log(`Last deploy: ${label}`);
+        console.log(dim(`  started:  ${status.startedAt}`));
+        if (status.finishedAt)
+            console.log(dim(`  finished: ${status.finishedAt}`));
+        if (status.url)
+            console.log(dim(`  url:      ${status.url}`));
+        if (status.error)
+            console.log(yellow(`  error:    ${status.error}`));
+        if (status.state === 'in-progress')
+            console.log(dim(`  logs:     ${deployLogPath(cwd)}`));
+    }
+    if (summary.deployedShortSha) {
+        const sync = summary.inSync === true ? green('in sync')
+            : summary.inSync === false ? yellow('local has undeployed commits')
+                : dim('unknown');
+        console.log(`Commit: deployed ${summary.deployedShortSha}${summary.localShortSha ? `, local ${summary.localShortSha}` : ''} ${sync}`);
+    }
+}

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('');