runwork 0.13.4 → 0.15.0

package/dist/commands/__tests__/clone-args.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { normalizeCloneArgs } from '../clone.js';
+import { normalizeCloneArgs, RESTRICTED_FS_HELP } from '../clone.js';
 describe('normalizeCloneArgs', () => {
     it('passes through both args unchanged when --app is not provided', () => {
         expect(normalizeCloneArgs('app-id', 'C:/dir', undefined)).toEqual({
@@ -42,3 +42,10 @@ describe('normalizeCloneArgs', () => {
         });
     });
 });
+describe('clone --help restricted-FS guidance', () => {
+    it('warns agents about restricted "outputs" mounts and the remedy', () => {
+        expect(RESTRICTED_FS_HELP).toContain('Operation not permitted');
+        expect(RESTRICTED_FS_HELP).toContain('outputs');
+        expect(RESTRICTED_FS_HELP).toContain('home directory');
+    });
+});

package/dist/commands/__tests__/clone-source-result.test.d.ts

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

package/dist/commands/__tests__/clone-source-result.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { pullOutcomeFromError, isCloneSourceFailure } from '../clone.js';
+/** Fake an execFileSync error carrying git's stderr. */
+function gitError(stderr) {
+    const err = new Error('git failed');
+    err.stderr = Buffer.from(stderr);
+    return err;
+}
+describe('clone source outcome', () => {
+    describe('pullOutcomeFromError()', () => {
+        it('classifies an empty remote (brand-new app) as benign', () => {
+            const src = pullOutcomeFromError(gitError("fatal: couldn't find remote ref main"));
+            expect(src.pulled).toBe(false);
+            expect(src.reason).toBe('empty-remote');
+        });
+        it('classifies an auth failure', () => {
+            const src = pullOutcomeFromError(gitError('fatal: Authentication failed for https://runwork.ai'));
+            expect(src.reason).toBe('auth');
+        });
+        it('classifies a network failure', () => {
+            const src = pullOutcomeFromError(gitError('fatal: unable to access: Could not resolve host: runwork.ai'));
+            expect(src.reason).toBe('network');
+        });
+        it('classifies a missing remote', () => {
+            const src = pullOutcomeFromError(gitError("fatal: 'runwork' does not appear to be a git repository"));
+            expect(src.reason).toBe('no-remote');
+        });
+        it('preserves the raw stderr as detail', () => {
+            const src = pullOutcomeFromError(gitError('fatal: Authentication failed'));
+            expect(src.detail).toContain('Authentication failed');
+        });
+    });
+    describe('isCloneSourceFailure()', () => {
+        it('is false for a successful pull', () => {
+            expect(isCloneSourceFailure({ pulled: true })).toBe(false);
+        });
+        it('is false for an empty remote (expected for new apps)', () => {
+            expect(isCloneSourceFailure({ pulled: false, reason: 'empty-remote' })).toBe(false);
+        });
+        it.each(['auth', 'network', 'no-remote', 'unknown'])('is true for a real %s failure (template-only scaffold)', (reason) => {
+            const src = { pulled: false, reason };
+            expect(isCloneSourceFailure(src)).toBe(true);
+        });
+    });
+});

package/dist/commands/__tests__/mcp-entries.test.d.ts

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

package/dist/commands/__tests__/mcp-entries.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { buildExternalMcpEntries } from '../mcp-entries.js';
+const PLATFORM_KEY = 'rk_ws_live_supersecretplatformkey';
+function server(overrides) {
+    return {
+        id: 'srv-1',
+        name: 'example',
+        url: 'https://mcp.example.com',
+        transport: 'streamable-http',
+        enabled: true,
+        addedAt: 0,
+        addedBy: 'user-1',
+        ...overrides,
+    };
+}
+describe('buildExternalMcpEntries', () => {
+    it('never injects the Runwork platform key onto external entries', () => {
+        const entries = buildExternalMcpEntries([
+            server({ id: 'a', authType: 'header' }),
+            server({ id: 'b', authType: 'oauth' }),
+            server({ id: 'c', authType: 'none' }),
+            server({ id: 'd' }), // authType unset
+        ], { a: { Authorization: 'Bearer user-token' } });
+        // Regression: the platform key must not appear anywhere in the output.
+        expect(JSON.stringify(entries)).not.toContain(PLATFORM_KEY);
+    });
+    it('injects resolved per-server headers for header-auth servers', () => {
+        const entries = buildExternalMcpEntries([server({ id: 'a', authType: 'header' })], { a: { Authorization: 'Bearer tok', 'X-Api-Key': 'key123' } });
+        expect(entries[0].headers).toEqual({ Authorization: 'Bearer tok', 'X-Api-Key': 'key123' });
+    });
+    it('emits no auth header for oauth servers (local agent runs its own flow)', () => {
+        const entries = buildExternalMcpEntries([server({ id: 'a', authType: 'oauth' })], { a: { Authorization: 'Bearer should-not-be-used' } });
+        expect(entries[0].headers).toBeUndefined();
+    });
+    it('emits no auth header for none/unset servers', () => {
+        const entries = buildExternalMcpEntries([server({ id: 'a', authType: 'none' }), server({ id: 'b' })], {});
+        expect(entries[0].headers).toBeUndefined();
+        expect(entries[1].headers).toBeUndefined();
+    });
+    it('omits headers when a header-auth server has no resolved credentials', () => {
+        const entries = buildExternalMcpEntries([server({ id: 'a', authType: 'header' })], {});
+        expect(entries[0].headers).toBeUndefined();
+    });
+    it('skips disabled servers', () => {
+        const entries = buildExternalMcpEntries([server({ id: 'a', enabled: false })], {});
+        expect(entries).toHaveLength(0);
+    });
+});

package/dist/commands/clone.d.ts

@@ -1,6 +1,19 @@
 import { Command } from 'commander';
 import { ApiClient } from '../api/client.js';
 import type { Credentials, AppInfo } from '../types.js';
+import { type SyncErrorReason } from '../git/classify-sync-error.js';
+/**
+ * Outcome of overlaying the app's git-tracked source on top of the template.
+ * `pulled: false` with `reason: 'empty-remote'` is the expected, benign state
+ * for a brand-new app (nothing pushed yet). Any other `reason` is a real
+ * failure that left a template-only scaffold -- the caller must NOT report
+ * success, since editing it would edit the wrong code (friction log #1).
+ */
+export interface CloneSource {
+    pulled: boolean;
+    reason?: 'empty-remote' | SyncErrorReason;
+    detail?: string;
+}
 export interface CloneResult {
     appId: string;
     appName: string;
@@ -8,8 +21,21 @@ export interface CloneResult {
     directory: string;
     workspaceId: string;
     workspaceName: string;
+    source: CloneSource;
 }
 export declare function execClone(client: ApiClient, app: AppInfo, directory?: string, creds?: Credentials | null): Promise<CloneResult>;
+/**
+ * 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 declare function pullOutcomeFromError(err: unknown): CloneSource;
+/**
+ * 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 declare function isCloneSourceFailure(source: CloneSource): boolean;
 /**
  * Reconcile positional args with --app. When --app is provided, the first
  * positional argument is intended as the *directory* -- not another appId
@@ -24,4 +50,11 @@ export declare function normalizeCloneArgs(appId: string | undefined, directory:
     appId: string | undefined;
     directory: string | undefined;
 };
+/**
+ * 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 declare const RESTRICTED_FS_HELP = "\nNote for AI agents: clone into a normal working directory. Some sandboxed\n\"outputs\" mounts (e.g. certain agent environments) disallow the unlink\noperations git uses for pack files, which can corrupt the repo with errors\nlike \"unable to unlink '.git/objects/pack/...': Operation not permitted\". If\nyou hit that, clone into your home directory or another standard path instead.";
 export declare const cloneCommand: Command;

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}`);
+    }
+}