runwork 0.9.4 → 0.10.1

package/dist/agents/__tests__/intro-skill.test.js

@@ -145,9 +145,13 @@ describe('generateInstructionHint', () => {
         expect(hint).toContain('runwork');
         expect(hint).toContain('skill');
     });
-    it('includes routing directive', () => {
+    it('includes the default-to-Runwork routing directive', () => {
+        // The earlier hint format used a "Routing:" header; the current format
+        // expresses the same idea as a "Default to Runwork" rule plus an explicit
+        // routing table. Either of those two anchors is sufficient guidance.
         const hint = generateInstructionHint(baseCtx);
-        expect(hint).toContain('Routing:');
+        expect(hint).toContain('Default to Runwork');
+        expect(hint).toContain('| User asks for | Use Runwork | Don\'t |');
     });
     it('includes inventory line', () => {
         const hint = generateInstructionHint({ ...baseCtx, appCount: 2, skillCount: 3 });

package/dist/agents/codex.js

@@ -336,12 +336,18 @@ export class CodexAdapter {
             const instructions = payload.instructions;
             if (typeof instructions !== 'string')
                 continue;
-            // Parse "- name: description (file: path/SKILL.md)" entries
-            // from the "### Available skills" section
-            const skillRegex = /^- ([^:]+):\s+.+\(file:\s+.+\/SKILL\.md\)/gm;
+            // Parse "- name: description (file: path/SKILL.md)" entries from the
+            // "### Available skills" section. Skip Codex's built-in system skills
+            // (those installed under `.system/`, e.g. skill-creator,
+            // skill-installer) since they are bundled with the agent and would
+            // skew adoption metrics meant to track *user-installed* skills.
+            const skillRegex = /^- ([^:]+):\s+.+\(file:\s+(.+\/SKILL\.md)\)/gm;
             let match;
             while ((match = skillRegex.exec(instructions)) !== null) {
                 const skillName = match[1].trim();
+                const skillPath = match[2];
+                if (skillPath.includes('/.system/'))
+                    continue;
                 const existing = skillCounts.get(skillName);
                 if (existing) {
                     existing.count++;

package/dist/api/__tests__/client.test.js

@@ -1,11 +1,19 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { ApiClient } from '../client.js';
+// HTTP goes through our `httpFetch` wrapper (single seam for diagnostics
+// and the optional `curl` transport). Tests mock that wrapper directly so
+// they exercise the same code path the production CLI uses.
 const mockFetch = vi.fn();
-globalThis.fetch = mockFetch;
+vi.mock('../../utils/http.js', () => ({
+    httpFetch: (...args) => mockFetch(...args),
+}));
+const { ApiClient } = await import('../client.js');
 function createJsonResponse(data, status = 200) {
     return {
         ok: status >= 200 && status < 300,
         status,
+        statusText: '',
+        url: '',
+        headers: new Headers(),
         json: () => Promise.resolve(data),
         text: () => Promise.resolve(JSON.stringify(data)),
         arrayBuffer: () => Promise.resolve(new ArrayBuffer(8)),

package/dist/api/client.js

@@ -1,3 +1,4 @@
+import { httpFetch } from '../utils/http.js';
 const DEFAULT_BASE_URL = 'https://runwork.ai';
 export class ApiClient {
     baseUrl;
@@ -10,12 +11,12 @@ export class ApiClient {
         const url = `${this.baseUrl}${path}`;
         const headers = {
             'Content-Type': 'application/json',
-            ...Object.fromEntries(Object.entries(options.headers || {})),
+            ...Object.fromEntries(Object.entries(options.headers || {}).filter(([, v]) => v !== undefined)),
         };
         if (this.apiKey) {
             headers['Authorization'] = `Bearer ${this.apiKey}`;
         }
-        const response = await fetch(url, { ...options, headers });
+        const response = await httpFetch(url, { ...options, headers });
         if (!response.ok) {
             const body = await response.text();
             throw new Error(`API error ${response.status}: ${body}`);
@@ -121,7 +122,7 @@ export class ApiClient {
         if (this.apiKey) {
             headers['Authorization'] = `Bearer ${this.apiKey}`;
         }
-        const response = await fetch(url, { headers });
+        const response = await httpFetch(url, { headers });
         if (!response.ok) {
             throw new Error(`Failed to download skeleton: ${response.status}`);
         }
@@ -368,7 +369,7 @@ export class ApiClient {
         if (opts?.body) {
             headers['Content-Type'] = 'application/json';
         }
-        const response = await fetch(url, {
+        const response = await httpFetch(url, {
             method,
             headers,
             body: opts?.body ? JSON.stringify(opts.body) : undefined,

package/dist/auth/__tests__/login-flow.test.js

@@ -6,7 +6,26 @@ vi.mock('../store.js', () => ({
 vi.mock('../../git/credentials.js', () => ({
     configureGitCredentials: vi.fn().mockResolvedValue(undefined),
 }));
+// HTTP goes through our `httpFetch` wrapper (single seam for diagnostics
+// and the optional `curl` transport). Tests mock that wrapper directly so
+// they exercise the same code path the production CLI uses.
+const mockFetch = vi.fn();
+vi.mock('../../utils/http.js', () => ({
+    httpFetch: (...args) => mockFetch(...args),
+}));
 import { saveCredentials } from '../store.js';
+function jsonResponse(data, status = 200) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: '',
+        url: '',
+        headers: new Headers(),
+        json: () => Promise.resolve(data),
+        text: () => Promise.resolve(JSON.stringify(data)),
+        arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+    };
+}
 beforeEach(() => {
     vi.clearAllMocks();
     vi.spyOn(console, 'log').mockImplementation(() => { });
@@ -14,100 +33,58 @@ beforeEach(() => {
 });
 describe('performLoginNoOpen', () => {
     it('with printOnly prints URL and returns null without polling', async () => {
-        // Mock ApiClient at the instance level via fetch
-        const originalFetch = globalThis.fetch;
-        const mockFetch = vi.fn().mockResolvedValue({
-            ok: true,
-            status: 200,
-            json: () => Promise.resolve({
-                data: { sessionId: 'sess-123', loginUrl: 'https://runwork.ai/cli-auth?session=sess-123' },
-            }),
-        });
-        globalThis.fetch = mockFetch;
-        try {
-            const { performLoginNoOpen } = await import('../login-flow.js');
-            const result = await performLoginNoOpen('https://runwork.ai', true);
-            expect(console.log).toHaveBeenCalledWith('https://runwork.ai/cli-auth?session=sess-123');
-            expect(result).toBeNull();
-            expect(saveCredentials).not.toHaveBeenCalled();
-        }
-        finally {
-            globalThis.fetch = originalFetch;
-        }
+        mockFetch.mockResolvedValue(jsonResponse({
+            data: { sessionId: 'sess-123', loginUrl: 'https://runwork.ai/cli-auth?session=sess-123' },
+        }));
+        const { performLoginNoOpen } = await import('../login-flow.js');
+        const result = await performLoginNoOpen('https://runwork.ai', true);
+        expect(console.log).toHaveBeenCalledWith('https://runwork.ai/cli-auth?session=sess-123');
+        expect(result).toBeNull();
+        expect(saveCredentials).not.toHaveBeenCalled();
     });
 });
 describe('performLoginWithApiKey', () => {
     it('validates key by listing workspaces and saves credentials', async () => {
-        const originalFetch = globalThis.fetch;
-        const mockFetch = vi.fn().mockResolvedValue({
-            ok: true,
-            status: 200,
-            json: () => Promise.resolve({
-                data: [{ id: 'ws-1', name: 'My Workspace' }],
-            }),
-        });
-        globalThis.fetch = mockFetch;
-        try {
-            const { performLoginWithApiKey } = await import('../login-flow.js');
-            const result = await performLoginWithApiKey('rw_test123');
-            expect(saveCredentials).toHaveBeenCalledWith(expect.objectContaining({
-                apiKey: 'rw_test123',
-                defaultWorkspaceId: 'ws-1',
-                defaultWorkspaceName: 'My Workspace',
-            }));
-            expect(result.apiKey).toBe('rw_test123');
-        }
-        finally {
-            globalThis.fetch = originalFetch;
-        }
+        mockFetch.mockResolvedValue(jsonResponse({
+            data: [{ id: 'ws-1', name: 'My Workspace' }],
+        }));
+        const { performLoginWithApiKey } = await import('../login-flow.js');
+        const result = await performLoginWithApiKey('rw_test123');
+        expect(saveCredentials).toHaveBeenCalledWith(expect.objectContaining({
+            apiKey: 'rw_test123',
+            defaultWorkspaceId: 'ws-1',
+            defaultWorkspaceName: 'My Workspace',
+        }));
+        expect(result.apiKey).toBe('rw_test123');
     });
     it('saves credentials with custom base URL', async () => {
-        const originalFetch = globalThis.fetch;
-        const mockFetch = vi.fn().mockResolvedValue({
-            ok: true,
-            status: 200,
-            json: () => Promise.resolve({ data: [{ id: 'ws-1', name: 'WS' }] }),
-        });
-        globalThis.fetch = mockFetch;
-        try {
-            const { performLoginWithApiKey } = await import('../login-flow.js');
-            const result = await performLoginWithApiKey('rw_key', 'https://custom.runwork.dev');
-            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('https://custom.runwork.dev'), expect.anything());
-            expect(result.baseUrl).toBe('https://custom.runwork.dev');
-        }
-        finally {
-            globalThis.fetch = originalFetch;
-        }
+        mockFetch.mockResolvedValue(jsonResponse({ data: [{ id: 'ws-1', name: 'WS' }] }));
+        const { performLoginWithApiKey } = await import('../login-flow.js');
+        const result = await performLoginWithApiKey('rw_key', 'https://custom.runwork.dev');
+        expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('https://custom.runwork.dev'), expect.anything());
+        expect(result.baseUrl).toBe('https://custom.runwork.dev');
     });
     it('handles no workspaces (sets no default)', async () => {
-        const originalFetch = globalThis.fetch;
-        const mockFetch = vi.fn().mockResolvedValue({
-            ok: true,
-            status: 200,
-            json: () => Promise.resolve({ data: [] }),
-        });
-        globalThis.fetch = mockFetch;
-        try {
-            const { performLoginWithApiKey } = await import('../login-flow.js');
-            const result = await performLoginWithApiKey('rw_key');
-            expect(saveCredentials).toHaveBeenCalledWith(expect.objectContaining({
-                apiKey: 'rw_key',
-                defaultWorkspaceId: undefined,
-                defaultWorkspaceName: undefined,
-            }));
-            expect(result.apiKey).toBe('rw_key');
-        }
-        finally {
-            globalThis.fetch = originalFetch;
-        }
+        mockFetch.mockResolvedValue(jsonResponse({ data: [] }));
+        const { performLoginWithApiKey } = await import('../login-flow.js');
+        const result = await performLoginWithApiKey('rw_key');
+        expect(saveCredentials).toHaveBeenCalledWith(expect.objectContaining({
+            apiKey: 'rw_key',
+            defaultWorkspaceId: undefined,
+            defaultWorkspaceName: undefined,
+        }));
+        expect(result.apiKey).toBe('rw_key');
     });
     it('exits on invalid API key', async () => {
-        const originalFetch = globalThis.fetch;
-        globalThis.fetch = vi.fn().mockResolvedValue({
+        mockFetch.mockResolvedValue({
             ok: false,
             status: 401,
+            statusText: 'Unauthorized',
+            url: '',
+            headers: new Headers(),
             json: () => Promise.resolve({ error: 'Unauthorized' }),
             text: () => Promise.resolve('Unauthorized'),
+            arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
         });
         const mockExit = vi.spyOn(process, 'exit').mockImplementation(((code) => {
             throw new Error(`process.exit(${code})`);
@@ -118,7 +95,6 @@ describe('performLoginWithApiKey', () => {
             expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Invalid API key'));
         }
         finally {
-            globalThis.fetch = originalFetch;
             mockExit.mockRestore();
         }
     });

package/dist/auth/__tests__/store.test.js

@@ -87,17 +87,46 @@ describe('auth/store', () => {
             const result = requireAuth();
             expect(result).toEqual(validCredentials);
         });
-        it('exits process with code 1 when not logged in', () => {
+        it('exits process with code 1 with TTY guidance when invoked from a terminal', () => {
             vi.mocked(mockFs.existsSync).mockReturnValue(false);
             const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
                 throw new Error('process.exit called');
             }));
             const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
-            expect(() => requireAuth()).toThrow('process.exit called');
-            expect(exitSpy).toHaveBeenCalledWith(1);
-            expect(errorSpy).toHaveBeenCalledWith('Not logged in. Run `runwork login` first.');
-            exitSpy.mockRestore();
-            errorSpy.mockRestore();
+            const previousTTY = process.stdin.isTTY;
+            Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+            try {
+                expect(() => requireAuth()).toThrow('process.exit called');
+                expect(exitSpy).toHaveBeenCalledWith(1);
+                expect(errorSpy).toHaveBeenCalledWith('Not logged in. Run `runwork login` first.');
+            }
+            finally {
+                Object.defineProperty(process.stdin, 'isTTY', { value: previousTTY, configurable: true });
+                exitSpy.mockRestore();
+                errorSpy.mockRestore();
+            }
+        });
+        it('exits process with code 1 with headless guidance when invoked without a TTY', () => {
+            vi.mocked(mockFs.existsSync).mockReturnValue(false);
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
+                throw new Error('process.exit called');
+            }));
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const previousTTY = process.stdin.isTTY;
+            Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+            try {
+                expect(() => requireAuth()).toThrow('process.exit called');
+                expect(exitSpy).toHaveBeenCalledWith(1);
+                const message = errorSpy.mock.calls[0]?.[0];
+                expect(message).toContain('Not logged in.');
+                expect(message).toContain('RUNWORK_API_KEY');
+                expect(message).toContain('runwork login --api-key');
+            }
+            finally {
+                Object.defineProperty(process.stdin, 'isTTY', { value: previousTTY, configurable: true });
+                exitSpy.mockRestore();
+                errorSpy.mockRestore();
+            }
         });
     });
 });

package/dist/commands/__tests__/info-merge.test.d.ts

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

package/dist/commands/__tests__/info-merge.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { __testing } from '../info.js';
+const { mergeSources, padName } = __testing;
+describe('mergeSources — bad data resilience', () => {
+    it('drops blueprint entries with missing name', () => {
+        const map = mergeSources([
+            { name: 'good', extra: {} },
+            { name: undefined, extra: {} },
+            { name: '', extra: {} },
+        ], [], (item) => item.name ?? '', 'app-1');
+        expect(Array.from(map.keys())).toEqual(['good']);
+    });
+    it('drops server items whose name resolver returns undefined or empty', () => {
+        const map = mergeSources([], [
+            { name: 'good', appId: 'app-1', appName: 'My App', deploymentMode: 'preview' },
+            { name: undefined, appId: 'app-1', appName: 'My App', deploymentMode: 'preview' },
+            { name: '', appId: 'app-1', appName: 'My App', deploymentMode: 'preview' },
+        ], (item) => item.name ?? '', 'app-1');
+        expect(Array.from(map.keys())).toEqual(['good']);
+    });
+    it('skips server items belonging to other apps', () => {
+        const map = mergeSources([], [
+            { name: 'mine', appId: 'app-1', appName: 'A', deploymentMode: 'preview' },
+            { name: 'theirs', appId: 'app-2', appName: 'B', deploymentMode: 'preview' },
+        ], (item) => item.name ?? '', 'app-1');
+        expect(Array.from(map.keys())).toEqual(['mine']);
+    });
+    it('merges blueprint and server entries by name', () => {
+        const map = mergeSources([{ name: 'agent-x', extra: { type: 'task' } }], [
+            { name: 'agent-x', appId: 'app-1', appName: 'A', deploymentMode: 'production' },
+            { name: 'agent-y', appId: 'app-1', appName: 'A', deploymentMode: 'preview' },
+        ], (item) => item.name ?? '', 'app-1');
+        const x = map.get('agent-x');
+        const y = map.get('agent-y');
+        expect(x?.sources).toEqual(['blueprint', 'production']);
+        expect(x?.blueprintExtra).toEqual({ type: 'task' });
+        expect(y?.sources).toEqual(['preview']);
+    });
+});
+describe('padName — defensive printer', () => {
+    it('pads valid names to the requested width', () => {
+        expect(padName('foo', 8)).toBe('foo     ');
+    });
+    it('returns a placeholder for undefined / null / empty inputs', () => {
+        expect(padName(undefined, 12)).toContain('(unnamed)');
+        expect(padName(null, 12)).toContain('(unnamed)');
+        expect(padName('', 12)).toContain('(unnamed)');
+        // Placeholder is also padded to the requested width.
+        expect(padName(undefined, 12).length).toBe(12);
+    });
+    it('does not throw on non-string inputs', () => {
+        expect(() => padName(42, 8)).not.toThrow();
+        expect(() => padName({}, 8)).not.toThrow();
+    });
+});

package/dist/commands/__tests__/upgrade.test.js

@@ -2,12 +2,27 @@
  * Tests for `runwork upgrade`.
  *
  * The module under test has top-level side effects (it builds a Commander
- * command and captures fetch/process references), so we exercise the exported
+ * command and captures `httpFetch` references), so we exercise the exported
  * __internal helpers against a local HTTP server that serves a fake
- * /cli/latest.json.
+ * /cli/latest.json. We intercept `httpFetch` and rewrite the LATEST_JSON_URL
+ * to point at the test server so the actual node:https-backed wrapper is
+ * exercised end to end.
  */
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createServer } from 'node:http';
+let currentServerUrl = null;
+vi.mock('../../utils/http.js', async () => {
+    const actual = await vi.importActual('../../utils/http.js');
+    return {
+        ...actual,
+        httpFetch: (url, init) => {
+            if (currentServerUrl && url.endsWith('/cli/latest.json')) {
+                return actual.httpFetch(`${currentServerUrl}/cli/latest.json`, init);
+            }
+            return actual.httpFetch(url, init);
+        },
+    };
+});
 import { __internal } from '../upgrade.js';
 function startJsonServer(body, status = 200) {
     return new Promise((resolvePromise) => {
@@ -41,17 +56,15 @@ function startJsonServer(body, status = 200) {
 }
 describe('__internal.fetchLatestVersion', () => {
     let originalBase;
-    let originalFetch;
     let serverStop = null;
     beforeEach(() => {
         originalBase = process.env.RUNWORK_DOWNLOAD_BASE_URL;
-        originalFetch = globalThis.fetch;
     });
     afterEach(async () => {
         if (serverStop)
             await serverStop();
         serverStop = null;
-        globalThis.fetch = originalFetch;
+        currentServerUrl = null;
         if (originalBase === undefined)
             delete process.env.RUNWORK_DOWNLOAD_BASE_URL;
         else
@@ -65,64 +78,34 @@ describe('__internal.fetchLatestVersion', () => {
             artifacts: {},
         });
         serverStop = server.stop;
-        // Override fetch URL by intercepting via globalThis.fetch
-        const realFetch = globalThis.fetch;
-        globalThis.fetch = ((input, init) => {
-            const url = typeof input === 'string' ? input : input.toString();
-            if (url === __internal.LATEST_JSON_URL) {
-                return realFetch(`${server.url}/cli/latest.json`, init);
-            }
-            return realFetch(input, init);
-        });
+        currentServerUrl = server.url;
         const version = await __internal.fetchLatestVersion();
         expect(version).toBe('1.2.3');
     });
     it('strips a leading v from the version', async () => {
         const server = await startJsonServer({ version: 'v9.9.9' });
         serverStop = server.stop;
-        const realFetch = globalThis.fetch;
-        globalThis.fetch = ((input, init) => {
-            const url = typeof input === 'string' ? input : input.toString();
-            if (url === __internal.LATEST_JSON_URL) {
-                return realFetch(`${server.url}/cli/latest.json`, init);
-            }
-            return realFetch(input, init);
-        });
+        currentServerUrl = server.url;
         const version = await __internal.fetchLatestVersion();
         expect(version).toBe('9.9.9');
     });
     it('returns null on HTTP error', async () => {
         const server = await startJsonServer(null, 500);
         serverStop = server.stop;
-        const realFetch = globalThis.fetch;
-        globalThis.fetch = ((input, init) => {
-            const url = typeof input === 'string' ? input : input.toString();
-            if (url === __internal.LATEST_JSON_URL) {
-                return realFetch(`${server.url}/cli/latest.json`, init);
-            }
-            return realFetch(input, init);
-        });
+        currentServerUrl = server.url;
         const version = await __internal.fetchLatestVersion();
         expect(version).toBeNull();
     });
     it('returns null when fetch throws', async () => {
-        globalThis.fetch = (() => {
-            throw new Error('network down');
-        });
+        // Point at a port that is virtually guaranteed to refuse connections.
+        currentServerUrl = 'http://127.0.0.1:1';
         const version = await __internal.fetchLatestVersion();
         expect(version).toBeNull();
     });
     it('returns null when the manifest has no version field', async () => {
         const server = await startJsonServer({ name: 'runwork' });
         serverStop = server.stop;
-        const realFetch = globalThis.fetch;
-        globalThis.fetch = ((input, init) => {
-            const url = typeof input === 'string' ? input : input.toString();
-            if (url === __internal.LATEST_JSON_URL) {
-                return realFetch(`${server.url}/cli/latest.json`, init);
-            }
-            return realFetch(input, init);
-        });
+        currentServerUrl = server.url;
         const version = await __internal.fetchLatestVersion();
         expect(version).toBeNull();
     });

package/dist/commands/clone.d.ts

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { ApiClient } from '../api/client.js';
-import type { AppInfo } from '../types.js';
+import type { Credentials, AppInfo } from '../types.js';
 export interface CloneResult {
     appId: string;
     appName: string;
@@ -9,5 +9,5 @@ export interface CloneResult {
     workspaceId: string;
     workspaceName: string;
 }
-export declare function execClone(client: ApiClient, app: AppInfo, directory?: string): Promise<CloneResult>;
+export declare function execClone(client: ApiClient, app: AppInfo, directory?: string, creds?: Credentials | null): Promise<CloneResult>;
 export declare const cloneCommand: Command;

package/dist/commands/clone.js

@@ -12,7 +12,10 @@ import { removeNestedGitDirs } from '../utils/fs.js';
 import { runAgentWizard } from '../ui/banner.js';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
 import { buildCloneGuide, buildErrorResponse } from '../utils/agent-guidance.js';
-export async function execClone(client, app, directory) {
+import { ensureGitIdentity } from '../git/identity.js';
+import { requireGit } from '../git/preflight.js';
+import { formatError } from '../utils/format-error.js';
+export async function execClone(client, app, directory, creds) {
     const slug = app.slug || app.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
     const dir = directory || slug;
     const remoteUrl = client.getGitRemoteUrl(app.workspaceId, app.id);
@@ -24,8 +27,13 @@ export async function execClone(client, app, directory) {
         extractZip(zipData, dir);
         removeNestedGitDirs(dir);
     }
-    catch {
-        console.warn('Failed to download template. Cloning git-tracked files only.');
+    catch (err) {
+        // Surface the real error so we never silently end up with an empty
+        // clone directory. The clone is best-effort here -- git fetch may
+        // still recover the project below -- but the user should know what
+        // went wrong on the way in.
+        console.warn(`Failed to download template: ${formatError(err)}`);
+        console.warn('Continuing with the git overlay only.');
     }
     // Generate template manifest BEFORE git overlay (captures pristine template checksums)
     const manifest = await generateManifest(dir);
@@ -33,8 +41,27 @@ export async function execClone(client, app, directory) {
     // Step 2: Git clone into the directory (overlays changed files on top of template)
     // Init git, add remote, fetch, and checkout to overlay on existing template files
     if (!existsSync(join(dir, '.git'))) {
-        execFileSync('git', ['init'], { cwd: dir, stdio: 'pipe' });
+        try {
+            execFileSync('git', ['init'], { cwd: dir, stdio: 'pipe' });
+        }
+        catch (err) {
+            // `stdio: 'pipe'` discards git's stderr, so we have to print the
+            // error ourselves -- otherwise this fails silently and the user
+            // is left with an empty directory and no clue what happened.
+            console.error(`git init failed in ${dir}: ${formatError(err)}`);
+            throw err;
+        }
+        // Force the initial branch to `main` regardless of the user's
+        // `init.defaultBranch` config (older Git installs default to
+        // `master`). symbolic-ref works before any commits exist.
+        try {
+            execFileSync('git', ['symbolic-ref', 'HEAD', 'refs/heads/main'], { cwd: dir, stdio: 'pipe' });
+        }
+        catch { /* best-effort: push uses HEAD:main so this is just cleanliness */ }
     }
+    // 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' });
     }
@@ -48,8 +75,12 @@ export async function execClone(client, app, directory) {
         // Checkout git-tracked files (overwrites template files where they differ)
         execFileSync('git', ['checkout', '.'], { cwd: dir, stdio: 'pipe' });
     }
-    catch {
-        console.warn('No remote commits yet. Starting with template only.');
+    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)}`);
     }
     // Write .runwork.json config
     const config = {
@@ -84,6 +115,7 @@ export const cloneCommand = new Command('clone')
     .argument('[directory]', 'Target directory')
     .option('--app <name-or-id>', 'App name or ID (skips interactive selection)')
     .action(async (appId, directory, options) => {
+    requireGit('clone');
     const creds = requireAuth();
     const client = new ApiClient(creds);
     const useJson = shouldOutputJson(undefined);
@@ -108,7 +140,7 @@ export const cloneCommand = new Command('clone')
     if (!useJson) {
         console.log(`Cloning "${app.name}"...`);
     }
-    const cloneResult = await execClone(client, app, directory);
+    const cloneResult = await execClone(client, app, directory, creds);
     if (useJson) {
         const response = {
             success: true,

package/dist/commands/dev.js

@@ -6,6 +6,8 @@ import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { watchAndAutoCommit, stopAutoCommit } from '../git/auto-commit.js';
 import { syncWithRemote } from '../git/sync.js';
+import { ensureGitIdentity } from '../git/identity.js';
+import { requireGit } from '../git/preflight.js';
 import { startLogTailer } from '../logs/tailer.js';
 import { populateTypes } from '../types-manager.js';
 import { loadManifest, generateManifest, saveManifest, detectUserEdits } from '../template/manifest.js';
@@ -85,7 +87,8 @@ function commitAndPushRestoredFiles(cwd, files) {
         return false;
     }
     try {
-        execFileSync('git', ['push', 'runwork', 'main'], { cwd, stdio: 'pipe' });
+        // `HEAD:main` so the push works regardless of local branch name.
+        execFileSync('git', ['push', 'runwork', 'HEAD:main'], { cwd, stdio: 'pipe' });
         return true;
     }
     catch {
@@ -96,11 +99,16 @@ function commitAndPushRestoredFiles(cwd, files) {
 }
 export async function execDev(options) {
     const useJson = options?.json ?? false;
+    requireGit('dev');
     const config = readConfig();
     const creds = requireAuth();
     const client = new ApiClient(creds);
     const cwd = process.cwd();
     const ts = () => new Date().toISOString();
+    // Seed a local git identity so the very first commit cannot fail on a
+    // fresh machine where `git config --global user.email/.name` has never
+    // been set (extremely common on Windows after a clean install).
+    ensureGitIdentity(cwd, creds);
     // Detect user edits made outside of `runwork dev`
     const oldManifest = await loadManifest(cwd);
     if (oldManifest) {