runwork 0.14.0 → 0.15.0

package/dist/deploy/detach.js

@@ -0,0 +1,71 @@
+/**
+ * `runwork deploy --detach` orchestration.
+ *
+ * Unlike `runwork dev --detach`, a deploy has no "ready" rendezvous to wait
+ * for -- it's fire-and-forget-then-poll. So the parent simply spawns a
+ * detached child (whose stdout/stderr go to `.runwork/deploy-*.log`), records
+ * an `in-progress` status, prints a poll hint, and exits. The child runs the
+ * real deploy and finalizes the status file to `succeeded`/`failed`.
+ *
+ * This exists so agents whose shell tool times out (~45s) can launch a deploy
+ * that survives, then poll `runwork deploy --status` (friction log #7).
+ */
+import * as fs from 'fs';
+import * as child_process from 'child_process';
+import { join } from 'path';
+import { looksLikeBunStandaloneArtifact } from '../dev/detach.js';
+/** Hidden marker passed to the spawned child. Not shown in --help. */
+export const DEPLOY_DETACHED_CHILD_FLAG = '--internal-detached-deploy-child';
+/** Whether this invocation is the detached deploy child. */
+export function isInternalDeployChild(argv = process.argv) {
+    return argv.includes(DEPLOY_DETACHED_CHILD_FLAG);
+}
+/**
+ * Build the args for the spawned child so it re-runs the same deploy in the
+ * foreground (the child must NOT re-detach). Drops `--detach`, any stale
+ * marker, and a Bun-on-Windows virtual-FS path; re-adds exactly one marker.
+ * Pure for testability.
+ */
+export function buildDeployChildArgs(parentArgv) {
+    const rest = [];
+    for (let i = 1; i < parentArgv.length; i++) {
+        if (i === 1 && looksLikeBunStandaloneArtifact(parentArgv[i]))
+            continue;
+        rest.push(parentArgv[i]);
+    }
+    const filtered = rest.filter((a) => a !== DEPLOY_DETACHED_CHILD_FLAG && a !== '--detach');
+    return [...filtered, DEPLOY_DETACHED_CHILD_FLAG];
+}
+/**
+ * Spawn the detached deploy child with stdout/stderr routed to
+ * `.runwork/deploy-{stdout,stderr}.log`. Cross-platform: uses
+ * `process.execPath` so it never depends on PATH (Bun-standalone-safe).
+ */
+export function spawnDetachedDeploy(childArgs, cwd) {
+    const dir = join(cwd, '.runwork');
+    fs.mkdirSync(dir, { recursive: true });
+    const stdoutFd = fs.openSync(join(dir, 'deploy-stdout.log'), 'w');
+    const stderrFd = fs.openSync(join(dir, 'deploy-stderr.log'), 'w');
+    try {
+        const proc = child_process.spawn(process.execPath, childArgs, {
+            cwd,
+            env: process.env,
+            detached: true,
+            stdio: ['ignore', stdoutFd, stderrFd],
+            windowsHide: true,
+        });
+        if (proc.pid !== undefined)
+            proc.unref();
+        return { pid: proc.pid ?? 0 };
+    }
+    finally {
+        try {
+            fs.closeSync(stdoutFd);
+        }
+        catch { /* ignore */ }
+        try {
+            fs.closeSync(stderrFd);
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/dev/__tests__/session.test.js

@@ -368,6 +368,45 @@ describe('session lifecycle primitives', () => {
             });
             expect(file.noSync).toBe(true);
         });
+        it('omits startupSync when not provided, includes it when provided', () => {
+            const base = {
+                pid: 1, sessionId: 's', appId: 'a', previewUrl: '', cliVersion: '0.0.0',
+                mode: 'detached', deps: { bootTime: () => 0 },
+            };
+            expect(buildSessionFile(base).startupSync).toBeUndefined();
+            const withSync = buildSessionFile({
+                ...base,
+                startupSync: { syncStatus: 'sync-failed', syncFailed: true, staleCode: true },
+            });
+            expect(withSync.startupSync).toEqual({ syncStatus: 'sync-failed', syncFailed: true, staleCode: true });
+        });
+    });
+    describe('startupSync field back-compat', () => {
+        it('round-trips startupSync through write/read', () => {
+            const file = buildSessionFile({
+                pid: process.pid,
+                sessionId: 's',
+                appId: 'a',
+                previewUrl: 'https://x',
+                cliVersion: '0.0.0',
+                mode: 'detached',
+                startupSync: { syncStatus: 'sync-failed', syncFailed: true, staleCode: true },
+                deps: { bootTime: () => 0 },
+            });
+            writeSessionFile(appDir, file);
+            const read = readSessionFile(appDir);
+            expect(read?.startupSync).toEqual({ syncStatus: 'sync-failed', syncFailed: true, staleCode: true });
+        });
+        it('accepts an older session file with no startupSync field', () => {
+            const file = buildSessionFile({
+                pid: process.pid, sessionId: 's', appId: 'a', previewUrl: 'https://x',
+                cliVersion: '0.0.0', mode: 'detached', deps: { bootTime: () => 0 },
+            });
+            writeSessionFile(appDir, file);
+            const read = readSessionFile(appDir);
+            expect(read).not.toBeNull();
+            expect(read?.startupSync).toBeUndefined();
+        });
     });
     describe('noSync field back-compat', () => {
         it('round-trips noSync through write/read', () => {

package/dist/dev/__tests__/startup-sync.test.d.ts

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

package/dist/dev/__tests__/startup-sync.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { buildStartupSyncSummary } from '../startup-sync.js';
+describe('dev/startup-sync', () => {
+    it('reports no-sync mode as neither failed nor stale', () => {
+        expect(buildStartupSyncSummary({ noSync: true })).toEqual({
+            syncStatus: 'no-sync',
+            syncFailed: false,
+            staleCode: false,
+        });
+    });
+    it('flags a failed startup sync as stale (preview serving old code)', () => {
+        expect(buildStartupSyncSummary({ noSync: false, status: 'sync-failed' })).toEqual({
+            syncStatus: 'sync-failed',
+            syncFailed: true,
+            staleCode: true,
+        });
+    });
+    it.each(['synced', 'merged', 'skipped'])('treats a %s startup sync as live (not stale)', (status) => {
+        expect(buildStartupSyncSummary({ noSync: false, status })).toEqual({
+            syncStatus: status,
+            syncFailed: false,
+            staleCode: false,
+        });
+    });
+    it('defaults to skipped when no status is provided', () => {
+        expect(buildStartupSyncSummary({ noSync: false })).toEqual({
+            syncStatus: 'skipped',
+            syncFailed: false,
+            staleCode: false,
+        });
+    });
+});

package/dist/dev/session.d.ts

@@ -14,6 +14,7 @@
  * See `docs/plans/2026-05-06-runwork-dev-lifecycle-design.md` for the full
  * lifecycle contract.
  */
+import type { StartupSyncSummary } from './startup-sync.js';
 export declare const SESSION_FILE_SCHEMA_VERSION = 1;
 /**
  * Tolerance (ms) when comparing the stored bootTime to the currently
@@ -40,6 +41,13 @@ export interface SessionFile {
      * treated as `false`.
      */
     noSync?: boolean;
+    /**
+     * Startup sync outcome, so a detached parent can relay stale-code warnings
+     * to the caller instead of those signals only living in the child's log
+     * (friction log #2). Optional for back-compat with session files that
+     * predate the field.
+     */
+    startupSync?: StartupSyncSummary;
 }
 export type SessionStaleReason = 'malformed' | 'version-mismatch' | 'app-id-mismatch' | 'boot-time-mismatch' | 'pid-dead';
 export type SessionState = {
@@ -161,6 +169,7 @@ export declare function buildSessionFile(input: {
     cliVersion: string;
     mode: SessionMode;
     noSync?: boolean;
+    startupSync?: StartupSyncSummary;
     startedAt?: number;
     deps?: SessionDeps;
 }): SessionFile;

package/dist/dev/session.js

@@ -113,7 +113,9 @@ function validateSessionFile(raw) {
         typeof r.cliVersion === 'string' &&
         (r.mode === 'foreground' || r.mode === 'detached') &&
         // Optional for back-compat: v1 files lack the field. Accept absent or boolean.
-        (r.noSync === undefined || typeof r.noSync === 'boolean'));
+        (r.noSync === undefined || typeof r.noSync === 'boolean') &&
+        // Optional: absent on older files; otherwise an object (shape from buildStartupSyncSummary).
+        (r.startupSync === undefined || (typeof r.startupSync === 'object' && r.startupSync !== null)));
 }
 /**
  * Read and parse the session file. Returns `null` for a missing file or
@@ -251,5 +253,6 @@ export function buildSessionFile(input) {
         cliVersion: input.cliVersion,
         mode: input.mode,
         noSync: input.noSync ?? false,
+        ...(input.startupSync ? { startupSync: input.startupSync } : {}),
     };
 }

package/dist/dev/startup-sync.d.ts

@@ -0,0 +1,23 @@
+import type { SyncResult } from '../git/sync.js';
+/**
+ * Summary of the startup sync outcome, surfaced on the `session_started`
+ * event so agents can tell whether the preview reflects their latest edits.
+ * `staleCode` is the key signal: when true, the initial sync failed and the
+ * preview is serving the last good state, NOT the current working tree
+ * (friction log #2).
+ */
+export interface StartupSyncSummary {
+    syncStatus: SyncResult['status'] | 'no-sync';
+    syncFailed: boolean;
+    staleCode: boolean;
+}
+/**
+ * Derive the startup sync summary from how dev started:
+ * - no-sync mode never mutates the tree, so it's neither failed nor stale.
+ * - otherwise it mirrors the syncWithRemote() status; a `sync-failed` status
+ *   means the preview is stale.
+ */
+export declare function buildStartupSyncSummary(input: {
+    noSync: boolean;
+    status?: SyncResult['status'];
+}): StartupSyncSummary;

package/dist/dev/startup-sync.js

@@ -0,0 +1,14 @@
+/**
+ * Derive the startup sync summary from how dev started:
+ * - no-sync mode never mutates the tree, so it's neither failed nor stale.
+ * - otherwise it mirrors the syncWithRemote() status; a `sync-failed` status
+ *   means the preview is stale.
+ */
+export function buildStartupSyncSummary(input) {
+    if (input.noSync) {
+        return { syncStatus: 'no-sync', syncFailed: false, staleCode: false };
+    }
+    const status = input.status ?? 'skipped';
+    const failed = status === 'sync-failed';
+    return { syncStatus: status, syncFailed: failed, staleCode: failed };
+}

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.14.0";
+export declare const VERSION = "0.15.0";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/embed-types.ts -- do not edit
-export const VERSION = "0.14.0";
+export const VERSION = "0.15.0";

package/dist/git/__tests__/classify-sync-error.test.d.ts

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

package/dist/git/__tests__/classify-sync-error.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { classifySyncError, diagnoseSyncError } from '../classify-sync-error.js';
+describe('git/classify-sync-error', () => {
+    describe('classifySyncError()', () => {
+        it('detects a missing/misnamed runwork remote', () => {
+            expect(classifySyncError("fatal: 'runwork' does not appear to be a git repository")).toBe('no-remote');
+            expect(classifySyncError('fatal: No such remote: runwork')).toBe('no-remote');
+        });
+        it('detects authentication failures', () => {
+            expect(classifySyncError('fatal: Authentication failed for https://runwork.ai/...')).toBe('auth');
+            expect(classifySyncError('fatal: could not read Username for https://runwork.ai: terminal prompts disabled')).toBe('auth');
+            expect(classifySyncError("fatal: unable to access '...': The requested URL returned error: 403")).toBe('auth');
+        });
+        it('detects network failures', () => {
+            expect(classifySyncError("fatal: unable to access '...': Could not resolve host: runwork.ai")).toBe('network');
+            expect(classifySyncError('fatal: unable to access: Failed to connect to runwork.ai port 443: Connection timed out')).toBe('network');
+        });
+        it('detects merge/rebase conflicts and the stash-conflict sentinel', () => {
+            expect(classifySyncError('CONFLICT (content): Merge conflict in src/App.tsx')).toBe('conflict');
+            expect(classifySyncError('error: Automatic merge failed')).toBe('conflict');
+            expect(classifySyncError('stash-conflict')).toBe('conflict');
+        });
+        it('falls back to unknown for unrecognized errors and empty input', () => {
+            expect(classifySyncError('some unexpected git failure')).toBe('unknown');
+            expect(classifySyncError(undefined)).toBe('unknown');
+            expect(classifySyncError('')).toBe('unknown');
+        });
+        it('is case-insensitive', () => {
+            expect(classifySyncError('AUTHENTICATION FAILED')).toBe('auth');
+            expect(classifySyncError('could not resolve HOST')).toBe('network');
+        });
+    });
+    describe('diagnoseSyncError()', () => {
+        it('points a no-remote failure at doctor --fix, not network/session', () => {
+            const d = diagnoseSyncError("fatal: 'runwork' does not appear to be a git repository");
+            expect(d.reason).toBe('no-remote');
+            expect(d.suggestions.join(' ')).toContain('runwork doctor --fix');
+            // Must NOT regress to the old misleading "session expired / network" advice.
+            expect(d.diagnosis.toLowerCase()).not.toContain('session expired');
+        });
+        it('points an auth failure at credential-helper remediation', () => {
+            const d = diagnoseSyncError('fatal: Authentication failed');
+            expect(d.reason).toBe('auth');
+            expect(d.suggestions.join(' ')).toContain('runwork doctor --fix');
+        });
+        it('gives stash-conflict a restore-specific message', () => {
+            const d = diagnoseSyncError('stash-conflict');
+            expect(d.reason).toBe('conflict');
+            expect(d.message).toContain('restoring local changes');
+        });
+        it('preserves the raw error in the unknown-case message', () => {
+            const d = diagnoseSyncError('weird git explosion');
+            expect(d.reason).toBe('unknown');
+            expect(d.message).toBe('weird git explosion');
+        });
+    });
+});

package/dist/git/__tests__/ensure-git-credential-helper.test.d.ts

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

package/dist/git/__tests__/ensure-git-credential-helper.test.js

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+vi.mock('fs', () => ({
+    existsSync: vi.fn(),
+}));
+vi.mock('../../auth/store.js', () => ({
+    getCredentials: vi.fn(),
+}));
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const { existsSync: mockExistsSync } = await import('fs');
+const { lookupCredentialHelper, helperBinaryStatus, ensureGitCredentialHelper, } = await import('../credentials.js');
+/** Build a `git config --get-regexp` stdout block from full config lines. */
+function gitConfigOutput(...lines) {
+    return Buffer.from(lines.join('\n') + '\n');
+}
+/** True when a recorded execFileSync call wrote a credential helper config. */
+function isHelperWrite(call) {
+    const args = call[1];
+    return call[0] === 'git'
+        && Array.isArray(args)
+        && args.includes('--global')
+        && args.some(a => /^credential\..*\.helper$/.test(a))
+        && !args.includes('--get-regexp')
+        && !args.includes('--unset');
+}
+describe('git/credentials lazy-ensure', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('lookupCredentialHelper()', () => {
+        it('returns "none" when git has no matching entries (get-regexp exits non-zero)', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error('exit 1'); // git config --get-regexp: no match
+            });
+            expect(lookupCredentialHelper('https://runwork.ai')).toEqual({ status: 'none' });
+        });
+        it('returns "unscoped" when entries exist but none match the origin', () => {
+            mockExecFileSync.mockReturnValue(gitConfigOutput('credential.https://runwork-staging.example.com.helper !runwork git-credential-helper'));
+            expect(lookupCredentialHelper('https://runwork.ai')).toEqual({
+                status: 'unscoped',
+                otherCount: 1,
+            });
+        });
+        it('returns "registered" with the helper value when a scoped entry exists', () => {
+            mockExecFileSync.mockReturnValue(gitConfigOutput('credential.https://runwork.ai.helper !"/usr/local/bin/runwork" git-credential-helper'));
+            expect(lookupCredentialHelper('https://runwork.ai')).toEqual({
+                status: 'registered',
+                value: '!"/usr/local/bin/runwork" git-credential-helper',
+            });
+        });
+        it('matches the correct origin among multiple entries', () => {
+            mockExecFileSync.mockReturnValue(gitConfigOutput('credential.https://runwork-staging.example.com.helper !runwork git-credential-helper', 'credential.https://runwork.ai.helper !"/usr/local/bin/runwork" git-credential-helper'));
+            const result = lookupCredentialHelper('https://runwork.ai');
+            expect(result.status).toBe('registered');
+        });
+    });
+    describe('helperBinaryStatus()', () => {
+        it('trusts PATH-relative helper values (no on-disk check)', () => {
+            expect(helperBinaryStatus('!runwork git-credential-helper')).toEqual({ ok: true, path: null });
+            expect(mockExistsSync).not.toHaveBeenCalled();
+        });
+        it('reports ok when an absolute-path binary exists', () => {
+            vi.mocked(mockExistsSync).mockReturnValue(true);
+            expect(helperBinaryStatus('!"/usr/local/bin/runwork" git-credential-helper')).toEqual({
+                ok: true,
+                path: '/usr/local/bin/runwork',
+            });
+        });
+        it('reports not-ok with the path when an absolute-path binary is missing', () => {
+            vi.mocked(mockExistsSync).mockReturnValue(false);
+            expect(helperBinaryStatus('!"/old/path/runwork" git-credential-helper')).toEqual({
+                ok: false,
+                path: '/old/path/runwork',
+            });
+        });
+        it('handles Windows absolute paths', () => {
+            vi.mocked(mockExistsSync).mockReturnValue(true);
+            const result = helperBinaryStatus('!"C:/Users/test/.runwork/bin/runwork.exe" git-credential-helper');
+            expect(result.ok).toBe(true);
+            expect(result.path).toBe('C:/Users/test/.runwork/bin/runwork.exe');
+        });
+    });
+    describe('ensureGitCredentialHelper()', () => {
+        it('is a no-op when a valid scoped helper is already registered', async () => {
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    return gitConfigOutput('credential.https://runwork.ai.helper !runwork git-credential-helper');
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai/api/git/ws/app');
+            // No registration write should have happened.
+            expect(mockExecFileSync.mock.calls.some(isHelperWrite)).toBe(false);
+        });
+        it('registers the helper when none is present (the get_cli_setup path)', async () => {
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    throw new Error('exit 1'); // nothing registered yet
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai/api/git/ws/app');
+            const write = mockExecFileSync.mock.calls.find(isHelperWrite);
+            expect(write).toBeDefined();
+            expect(write[1]).toContain('credential.https://runwork.ai.helper');
+        });
+        it('registers when entries exist but none are scoped to this origin', async () => {
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    return gitConfigOutput('credential.https://other.example.com.helper !runwork git-credential-helper');
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai');
+            expect(mockExecFileSync.mock.calls.some(isHelperWrite)).toBe(true);
+        });
+        it('repairs a stale helper that points at a missing binary', async () => {
+            vi.mocked(mockExistsSync).mockReturnValue(false);
+            mockExecFileSync.mockImplementation((_file, args) => {
+                if (args.includes('--get-regexp')) {
+                    return gitConfigOutput('credential.https://runwork.ai.helper !"/old/path/runwork" git-credential-helper');
+                }
+                return Buffer.from('');
+            });
+            await ensureGitCredentialHelper('https://runwork.ai');
+            expect(mockExecFileSync.mock.calls.some(isHelperWrite)).toBe(true);
+        });
+        it('is a no-op for an unparseable baseUrl', async () => {
+            await ensureGitCredentialHelper('not a url');
+            expect(mockExecFileSync).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/git/__tests__/ensure-runwork-remote.test.d.ts

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

package/dist/git/__tests__/ensure-runwork-remote.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const { normalizeRemoteUrl, listRemotes, ensureRunworkRemote, } = await import('../remote.js');
+/** Build `git remote -v` stdout from name->url pairs (fetch + push lines). */
+function remoteVerbose(pairs) {
+    const lines = [];
+    for (const [name, url] of Object.entries(pairs)) {
+        lines.push(`${name}\t${url} (fetch)`);
+        lines.push(`${name}\t${url} (push)`);
+    }
+    return Buffer.from(lines.join('\n') + '\n');
+}
+/**
+ * Drive ensureRunworkRemote/listRemotes against a fixed `git remote -v`
+ * result, recording any set-url/add mutations.
+ */
+function withRemotes(pairs) {
+    const setUrl = [];
+    const add = [];
+    mockExecFileSync.mockImplementation((_file, args) => {
+        if (args[0] === 'remote' && args[1] === '-v') {
+            return remoteVerbose(pairs);
+        }
+        if (args[0] === 'remote' && args[1] === 'set-url') {
+            setUrl.push(args);
+            return Buffer.from('');
+        }
+        if (args[0] === 'remote' && args[1] === 'add') {
+            add.push(args);
+            return Buffer.from('');
+        }
+        return Buffer.from('');
+    });
+    return { setUrl, add };
+}
+const CANONICAL = 'https://runwork.ai/api/git/ws/app';
+describe('git/remote', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('normalizeRemoteUrl()', () => {
+        it('strips a trailing .git', () => {
+            expect(normalizeRemoteUrl('https://runwork.ai/api/git/ws/app.git')).toBe(CANONICAL);
+        });
+        it('strips trailing slashes and lower-cases the host (path preserved)', () => {
+            expect(normalizeRemoteUrl('https://RunWork.ai/api/git/ws/app/')).toBe(CANONICAL);
+        });
+        it('drops userinfo so embedded creds do not break equality', () => {
+            expect(normalizeRemoteUrl('https://x-access-token:KEY@runwork.ai/api/git/ws/app')).toBe(CANONICAL);
+        });
+        it('falls back to a lower-cased trim for scp-style remotes', () => {
+            expect(normalizeRemoteUrl('git@GitHub.com:Foo/Bar.git')).toBe('git@github.com:foo/bar');
+        });
+    });
+    describe('listRemotes()', () => {
+        it('parses name -> fetch URL, ignoring push duplicates', () => {
+            withRemotes({ origin: 'https://example.com/a', runwork: CANONICAL });
+            expect(listRemotes('/repo')).toEqual({
+                origin: 'https://example.com/a',
+                runwork: CANONICAL,
+            });
+        });
+        it('returns {} when git fails (not a repo)', () => {
+            mockExecFileSync.mockImplementation(() => { throw new Error('not a git repo'); });
+            expect(listRemotes('/repo')).toEqual({});
+        });
+    });
+    describe('ensureRunworkRemote()', () => {
+        it('is a no-op when runwork already points at the canonical URL', () => {
+            const { setUrl, add } = withRemotes({ runwork: CANONICAL });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'noop' });
+            expect(setUrl).toHaveLength(0);
+            expect(add).toHaveLength(0);
+        });
+        it('treats a .git-suffixed existing runwork remote as a match (no rewrite)', () => {
+            const { setUrl, add } = withRemotes({ runwork: `${CANONICAL}.git` });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'noop' });
+            expect(setUrl).toHaveLength(0);
+            expect(add).toHaveLength(0);
+        });
+        it('repoints an existing runwork remote that points elsewhere', () => {
+            const { setUrl, add } = withRemotes({ runwork: 'https://runwork.ai/api/git/OLD/app' });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'updated' });
+            expect(setUrl).toHaveLength(1);
+            expect(setUrl[0]).toEqual(['remote', 'set-url', 'runwork', CANONICAL]);
+            expect(add).toHaveLength(0);
+        });
+        it('adds the runwork remote when missing (clean repo)', () => {
+            const { setUrl, add } = withRemotes({});
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'added' });
+            expect(add).toHaveLength(1);
+            expect(add[0]).toEqual(['remote', 'add', 'runwork', CANONICAL]);
+            expect(setUrl).toHaveLength(0);
+        });
+        it('recognizes a matching origin (manual git clone) via reusedFrom and still adds the runwork alias', () => {
+            const { setUrl, add } = withRemotes({ origin: CANONICAL });
+            expect(ensureRunworkRemote('/repo', CANONICAL)).toEqual({ action: 'added', reusedFrom: 'origin' });
+            expect(add).toHaveLength(1);
+            expect(add[0]).toEqual(['remote', 'add', 'runwork', CANONICAL]);
+            expect(setUrl).toHaveLength(0);
+        });
+        it('does not set reusedFrom when no existing remote matches', () => {
+            withRemotes({ origin: 'https://github.com/someone/fork' });
+            const result = ensureRunworkRemote('/repo', CANONICAL);
+            expect(result).toEqual({ action: 'added' });
+        });
+    });
+});

package/dist/git/__tests__/repo-config.test.d.ts

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

package/dist/git/__tests__/repo-config.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('child_process');
+const mockExecFileSync = (await import('child_process')).execFileSync;
+const { hardenRepoForRestrictedFs } = await import('../repo-config.js');
+describe('git/repo-config hardenRepoForRestrictedFs', () => {
+    beforeEach(() => vi.clearAllMocks());
+    it('disables gc.auto and maintenance.auto in the repo (local scope)', () => {
+        mockExecFileSync.mockReturnValue(Buffer.from(''));
+        hardenRepoForRestrictedFs('/repo');
+        const configCalls = mockExecFileSync.mock.calls
+            .filter((c) => c[0] === 'git' && c[1][0] === 'config')
+            .map((c) => c[1].slice(1));
+        expect(configCalls).toContainEqual(['gc.auto', '0']);
+        expect(configCalls).toContainEqual(['maintenance.auto', 'false']);
+        // Repo scope, not --global.
+        expect(configCalls.every((args) => !args.includes('--global'))).toBe(true);
+        // Run against the given cwd.
+        for (const call of mockExecFileSync.mock.calls) {
+            expect(call[2].cwd).toBe('/repo');
+        }
+    });
+    it('never throws when git config fails (best-effort)', () => {
+        mockExecFileSync.mockImplementation(() => { throw new Error('git unavailable'); });
+        expect(() => hardenRepoForRestrictedFs('/repo')).not.toThrow();
+    });
+});

package/dist/git/classify-sync-error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Classify a git sync failure from the raw stderr that `syncWithRemote`
+ * captures, so `runwork dev`/`deploy` can show an accurate cause and fix
+ * instead of the old catch-all "the sandbox session expired or the network
+ * connection was interrupted" (which pointed users away from the real
+ * problem, e.g. a missing `runwork` remote -- see friction log #3).
+ */
+export type SyncErrorReason = 'no-remote' | 'auth' | 'network' | 'conflict' | 'unknown';
+export interface SyncErrorDiagnosis {
+    reason: SyncErrorReason;
+    /** One-line summary suitable for an `error.message` field. */
+    message: string;
+    /** Plain explanation of the likely cause. */
+    diagnosis: string;
+    /** Actionable next steps, most-likely-fix first. */
+    suggestions: string[];
+}
+/** Map raw git stderr (or the stash-conflict sentinel) to a coarse reason. */
+export declare function classifySyncError(raw: string | undefined): SyncErrorReason;
+/** Build a full, user-facing diagnosis from the raw git stderr. */
+export declare function diagnoseSyncError(raw: string | undefined): SyncErrorDiagnosis;