runwork 0.10.1 → 0.10.2

package/dist/git/preflight.js

@@ -1,18 +1,235 @@
 import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { win32 as winPath } from 'path';
+import { homedir } from 'os';
+const VERSION_REGEX = /(\d+\.\d+(?:\.\d+)?)/;
+function tryRun(bin) {
+    try {
+        const out = execFileSync(bin, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        return { ok: true, version: out.toString('utf-8').trim() };
+    }
+    catch (err) {
+        return { ok: false, error: err };
+    }
+}
+function whereGit() {
+    if (process.platform !== 'win32')
+        return null;
+    try {
+        // No `encoding: 'utf-8'` on purpose: keep the return as a Buffer to
+        // match tryRun()'s shape. We toString() ourselves so test mocks can
+        // return Buffers uniformly.
+        const buf = execFileSync('where.exe', ['git'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        const out = buf.toString('utf-8');
+        // `where.exe git` may print multiple matches (cmd shim, exe shim).
+        // Prefer git.exe -- the bare shim is a .cmd that's harder to invoke
+        // reliably from spawn() and that mismatch is exactly what we're trying
+        // to work around.
+        const lines = out.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+        const exe = lines.find(line => /\.exe$/i.test(line));
+        if (exe && existsSync(exe))
+            return exe;
+        const fallback = lines.find(line => existsSync(line));
+        return fallback ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * Probe whether `git` is callable from this process. We use `execFileSync`
- * (not `which`/`where.exe`) so the check follows the exact PATH lookup any
- * subsequent git invocation will use -- that way we never report "found"
- * when the real call would fail with ENOENT, and vice versa.
+ * Query Git for Windows' registry keys for an InstallPath.
+ *
+ * The official Git for Windows installer always writes
+ * `HKLM\SOFTWARE\GitForWindows\InstallPath` (system installs) or
+ * `HKCU\Software\GitForWindows\InstallPath` (per-user installs). When that
+ * value points at e.g. `C:\Program Files\Git`, the binary lives at
+ * `<value>\cmd\git.exe`. Portable / non-installer Gits (MinGit, Scoop,
+ * GitHub Desktop's bundled git) won't appear here -- they're covered by
+ * canonicalGitCandidates().
+ */
+function registryGit() {
+    if (process.platform !== 'win32')
+        return null;
+    const queries = [
+        ['HKLM\\SOFTWARE\\GitForWindows', '/v', 'InstallPath'],
+        ['HKCU\\Software\\GitForWindows', '/v', 'InstallPath'],
+    ];
+    for (const args of queries) {
+        try {
+            const buf = execFileSync('reg.exe', ['query', ...args], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+            const out = buf.toString('utf-8');
+            // Output shape:
+            //   HKEY_LOCAL_MACHINE\SOFTWARE\GitForWindows
+            //       InstallPath    REG_SZ    C:\Program Files\Git
+            const match = out.match(/InstallPath\s+REG_SZ\s+(.+)/i);
+            if (!match)
+                continue;
+            const installRoot = match[1].trim();
+            const gitExe = winPath.join(installRoot, 'cmd', 'git.exe');
+            if (existsSync(gitExe))
+                return gitExe;
+        }
+        catch {
+            // reg.exe missing or key not present -- next query.
+        }
+    }
+    return null;
+}
+function canonicalGitCandidates() {
+    if (process.platform !== 'win32')
+        return [];
+    const paths = [];
+    const push = (...parts) => {
+        if (parts.every((part) => typeof part === 'string' && part.length > 0)) {
+            // Use winPath.join (not the bare `join` from 'path') because the path
+            // module's separator is locked at module-load time. On macOS test
+            // hosts running these tests with process.platform spoofed to 'win32',
+            // bare join would mix '\' and '/' separators and miss real Windows
+            // file system paths.
+            paths.push(winPath.join(...parts));
+        }
+    };
+    const home = homedir();
+    // Standard installer locations. `Git\cmd\git.exe` is the public entry
+    // point (a small shim that sets up PATH internally then runs the real
+    // git from `Git\mingw64\bin`). Bun's spawn copes with .exe just fine,
+    // so the shim works as long as we call it by absolute path.
+    push(process.env.ProgramFiles, 'Git', 'cmd', 'git.exe');
+    push(process.env['ProgramFiles(x86)'], 'Git', 'cmd', 'git.exe');
+    push(process.env.LOCALAPPDATA, 'Programs', 'Git', 'cmd', 'git.exe');
+    // Portable / per-user installs that don't register in HKLM:
+    //   - ~/.runwork/tools/mingit, ~/.runwork/tools/git -- our own namespace.
+    //     Other tools (e.g. Codex CLI) have been observed dropping a portable
+    //     MinGit there; if anything lives in our directory we should respect
+    //     it, even when we didn't put it there ourselves.
+    //   - Scoop -- ~/scoop/apps/git/current/cmd/git.exe.
+    //   - GitHub Desktop's bundled git lives under a versioned path that's
+    //     awkward to enumerate without a glob; skipped intentionally.
+    if (home) {
+        push(home, '.runwork', 'tools', 'mingit', 'cmd', 'git.exe');
+        push(home, '.runwork', 'tools', 'git', 'cmd', 'git.exe');
+        push(home, '.runwork', 'tools', 'PortableGit', 'cmd', 'git.exe');
+        push(home, 'scoop', 'apps', 'git', 'current', 'cmd', 'git.exe');
+    }
+    // Hard-coded defaults in case the env vars are missing (e.g. bizarre
+    // sandbox where %ProgramFiles% isn't propagated).
+    paths.push('C:\\Program Files\\Git\\cmd\\git.exe');
+    paths.push('C:\\Program Files (x86)\\Git\\cmd\\git.exe');
+    // De-dup while preserving order.
+    return [...new Set(paths)];
+}
+function prependToPath(dir) {
+    // Hard-coded ';' instead of `path.delimiter`: this helper is only called
+    // from the Windows-only fallback branch of probeGit(), but the path
+    // module's `delimiter` is determined by the *real* host OS at module
+    // load time -- so unit tests that flip `process.platform` to 'win32' on
+    // a macOS host would otherwise see ':' and fail to detect a duplicate
+    // entry. PATH on Windows always uses ';'.
+    const PATH_DELIM = ';';
+    const current = process.env.PATH ?? '';
+    const parts = current.split(PATH_DELIM);
+    if (parts.includes(dir))
+        return;
+    process.env.PATH = `${dir}${PATH_DELIM}${current}`;
+    // Windows historically reads `Path` (any case). Node normalizes via
+    // process.env, but the Bun-on-Windows path lookup we're working around
+    // here has surprised us before, so make the casing redundant.
+    if (process.env.Path !== undefined) {
+        process.env.Path = process.env.PATH;
+    }
+}
+let cachedProbe;
+/**
+ * Probe whether `git` is callable from this process.
+ *
+ * Strategy:
+ *   1. Try a bare `git --version` -- the common path on macOS, Linux, and
+ *      most Windows installs.
+ *   2. On Windows, fall back to `where.exe git` (uses the same PATH +
+ *      PATHEXT rules cmd.exe applies, which are more permissive than
+ *      Bun's spawn lookup in standalone-compiled binaries).
+ *   3. On Windows, finally probe canonical install paths under
+ *      %ProgramFiles%, %ProgramFiles(x86)%, %LOCALAPPDATA%\Programs.
+ *
+ * When step 2 or 3 succeeds, we prepend the resolved directory to
+ * process.env.PATH so the ~50 other call sites that do
+ * `execFileSync('git', ...)` automatically benefit, without rewriting
+ * each one. Result is cached for the lifetime of the process.
  */
 export function probeGit() {
-    try {
-        const out = execFileSync('git', ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
-        return { installed: true, version: out.toString('utf-8').trim() };
+    if (cachedProbe)
+        return cachedProbe;
+    // 1. Bare lookup.
+    const bare = tryRun('git');
+    if (bare.ok) {
+        cachedProbe = { installed: true, version: bare.version, path: 'git', source: 'PATH' };
+        return cachedProbe;
     }
-    catch (err) {
-        return { installed: false, error: err };
+    if (process.platform === 'win32') {
+        // 2. where.exe -- uses the same PATH+PATHEXT rules cmd.exe applies.
+        const whereResult = whereGit();
+        if (whereResult) {
+            const verify = tryRun(whereResult);
+            if (verify.ok) {
+                prependToPath(winPath.dirname(whereResult));
+                cachedProbe = { installed: true, version: verify.version, path: whereResult, source: 'where' };
+                return cachedProbe;
+            }
+        }
+        // 3. Registry -- the official Git for Windows installer always writes
+        //    HKLM\SOFTWARE\GitForWindows\InstallPath (or the HKCU equivalent
+        //    for per-user installs), so this catches "git is installed but
+        //    something has stripped both PATH and any chance of where.exe
+        //    finding it" cases (e.g. sandboxed agent shells).
+        const registryResult = registryGit();
+        if (registryResult) {
+            const verify = tryRun(registryResult);
+            if (verify.ok) {
+                prependToPath(winPath.dirname(registryResult));
+                cachedProbe = { installed: true, version: verify.version, path: registryResult, source: 'registry' };
+                return cachedProbe;
+            }
+        }
+        // 4. Canonical paths -- standard installer dirs plus our own
+        //    ~/.runwork/tools/{mingit,git,PortableGit} namespace and Scoop's
+        //    install location, for portable / non-installer Gits the registry
+        //    won't know about.
+        for (const candidate of canonicalGitCandidates()) {
+            if (!existsSync(candidate))
+                continue;
+            const verify = tryRun(candidate);
+            if (verify.ok) {
+                prependToPath(winPath.dirname(candidate));
+                cachedProbe = { installed: true, version: verify.version, path: candidate, source: 'canonical' };
+                return cachedProbe;
+            }
+        }
     }
+    cachedProbe = { installed: false, error: bare.error };
+    return cachedProbe;
+}
+/**
+ * Reset the cached probe result. Exposed for tests and for `runwork doctor`
+ * when it wants to re-check after a guided install.
+ */
+export function resetGitProbeCache() {
+    cachedProbe = undefined;
+}
+/**
+ * Extract a short numeric version (e.g. "2.43.0") from a `git --version`
+ * output line. Returns null if no number could be parsed.
+ */
+export function parseGitVersion(versionLine) {
+    if (!versionLine)
+        return null;
+    const match = versionLine.match(VERSION_REGEX);
+    return match ? match[1] : null;
 }
 /**
  * Build a beginner-friendly message explaining how to recover from a missing
@@ -20,8 +237,11 @@ export function probeGit() {
  * scenario there is "winget install Git.Git just succeeded but this shell's
  * PATH was cached at launch" -- restarting the shell fixes it without a
  * second install attempt.
+ *
+ * If a probe error is supplied, the underlying message is appended so users
+ * can see *why* detection failed (ENOENT vs EACCES vs something else).
  */
-export function buildMissingGitMessage(commandName) {
+export function buildMissingGitMessage(commandName, probe) {
     const lines = [
         `Git is required to run \`runwork ${commandName}\`, but it was not found on PATH.`,
         '',
@@ -34,6 +254,12 @@ export function buildMissingGitMessage(commandName) {
         lines.push('', 'If you just installed Git, this shell\'s PATH was cached when it opened', 'and does not yet include Git. Close this PowerShell / Command Prompt', 'window, open a fresh one, and re-run the command.');
     }
     lines.push('', 'Verify the install with: git --version');
+    if (probe?.error?.message) {
+        // Surface the underlying error for diagnostics so users (and we, in bug
+        // reports) can see whether this was ENOENT, EACCES, a sandbox PATH
+        // strip, etc. -- not just "not found".
+        lines.push('', `Underlying error: ${probe.error.message}`);
+    }
     return lines.join('\n');
 }
 /**
@@ -45,6 +271,6 @@ export function requireGit(commandName) {
     const probe = probeGit();
     if (probe.installed)
         return;
-    console.error(buildMissingGitMessage(commandName));
+    console.error(buildMissingGitMessage(commandName, probe));
     process.exit(1);
 }

package/dist/health/__tests__/checks.test.js

@@ -9,6 +9,7 @@ vi.mock('child_process', async (importOriginal) => {
 });
 import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
+import { resetGitProbeCache } from '../../git/preflight.js';
 const mockedExistsSync = vi.mocked(existsSync);
 const mockedExecFileSync = vi.mocked(execFileSync);
 beforeEach(() => {
@@ -17,6 +18,10 @@ beforeEach(() => {
     vi.spyOn(console, 'log').mockImplementation(() => { });
     vi.spyOn(console, 'error').mockImplementation(() => { });
     mockedExistsSync.mockReturnValue(true);
+    // checkSystemDeps now goes through probeGit() which caches the resolved
+    // git binary for the lifetime of the process. Reset between tests so each
+    // mock setup actually drives a fresh probe.
+    resetGitProbeCache();
 });
 afterEach(() => {
     vi.restoreAllMocks();
@@ -64,6 +69,135 @@ describe('checkSystemDeps', () => {
         expect(result.fix).toBeDefined();
     });
 });
+// ── 4a. Git credential helper ────────────────────────────────────────
+describe('checkGitCredentialHelper', () => {
+    function gitConfigOutput(line) {
+        return Buffer.from(`${line}\n`);
+    }
+    function gitConfigEmpty() {
+        // git config --get-regexp returns 1 with no output when nothing matches
+        const err = new Error('git config exited with code 1');
+        err.status = 1;
+        throw err;
+    }
+    it('skips when not logged in', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        const ctx = makeCtx({ credentials: null });
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('skip');
+        expect(result.message).toContain('not logged in');
+    });
+    it('skips when git is not installed', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        // First call (probeGit -> git --version) throws ENOENT-shaped error.
+        mockedExecFileSync.mockImplementation((file) => {
+            if (file === 'git') {
+                const err = new Error('spawn git ENOENT');
+                err.code = 'ENOENT';
+                throw err;
+            }
+            throw new Error('unreachable');
+        });
+        const ctx = makeCtx();
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('skip');
+        expect(result.message).toContain('git not installed');
+    });
+    it('passes when helper is registered for the credentials origin', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        mockedExecFileSync.mockImplementation(((file, args) => {
+            if (file === 'git' && args?.[0] === '--version')
+                return Buffer.from('git version 2.43.0');
+            if (file === 'git' && args?.includes('--get-regexp')) {
+                return gitConfigOutput('credential.https://runwork.ai.helper !runwork git-credential-helper');
+            }
+            throw new Error(`unexpected call: ${file} ${args?.join(' ')}`);
+        }));
+        const ctx = makeCtx();
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('pass');
+        expect(result.message).toContain('https://runwork.ai');
+    });
+    it('fails when no entry exists in git config', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        mockedExecFileSync.mockImplementation(((file, args) => {
+            if (file === 'git' && args?.[0] === '--version')
+                return Buffer.from('git version 2.43.0');
+            if (file === 'git' && args?.includes('--get-regexp'))
+                gitConfigEmpty();
+            throw new Error(`unexpected call: ${file} ${args?.join(' ')}`);
+        }));
+        const ctx = makeCtx();
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('fail');
+        expect(result.fix).toBe('runwork login');
+    });
+    it('fails when entries exist but none match the credentials origin', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        mockedExecFileSync.mockImplementation(((file, args) => {
+            if (file === 'git' && args?.[0] === '--version')
+                return Buffer.from('git version 2.43.0');
+            if (file === 'git' && args?.includes('--get-regexp')) {
+                // Stale entry from a previous staging URL.
+                return gitConfigOutput('credential.https://runwork-staging.example.com.helper !runwork git-credential-helper');
+            }
+            throw new Error(`unexpected call: ${file} ${args?.join(' ')}`);
+        }));
+        const ctx = makeCtx({
+            credentials: { apiKey: 'k', email: 'u@e.com', baseUrl: 'https://runwork.ai' },
+        });
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('1 other runwork helper');
+    });
+    it('fails when the registered absolute path no longer exists', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        mockedExecFileSync.mockImplementation(((file, args) => {
+            if (file === 'git' && args?.[0] === '--version')
+                return Buffer.from('git version 2.43.0');
+            if (file === 'git' && args?.includes('--get-regexp')) {
+                return gitConfigOutput('credential.https://runwork.ai.helper !"/old/path/runwork" git-credential-helper');
+            }
+            throw new Error(`unexpected call: ${file} ${args?.join(' ')}`);
+        }));
+        mockedExistsSync.mockImplementation((p) => p !== '/old/path/runwork');
+        const ctx = makeCtx();
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('fail');
+        expect(result.message).toContain('binary not found');
+        expect(result.fix).toContain('runwork login');
+    });
+    it('passes when the registered absolute path still exists', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        mockedExecFileSync.mockImplementation(((file, args) => {
+            if (file === 'git' && args?.[0] === '--version')
+                return Buffer.from('git version 2.43.0');
+            if (file === 'git' && args?.includes('--get-regexp')) {
+                return gitConfigOutput('credential.https://runwork.ai.helper !"/usr/local/bin/runwork" git-credential-helper');
+            }
+            throw new Error(`unexpected call: ${file} ${args?.join(' ')}`);
+        }));
+        mockedExistsSync.mockReturnValue(true);
+        const ctx = makeCtx();
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('pass');
+    });
+    it('passes a Windows-style absolute path that exists', async () => {
+        const { checkGitCredentialHelper } = await import('../checks.js');
+        mockedExecFileSync.mockImplementation(((file, args) => {
+            if (file === 'git' && args?.[0] === '--version')
+                return Buffer.from('git version 2.43.0');
+            if (file === 'git' && args?.includes('--get-regexp')) {
+                return gitConfigOutput('credential.https://runwork.ai.helper !"C:/Users/test/.runwork/bin/runwork.exe" git-credential-helper');
+            }
+            throw new Error(`unexpected call: ${file} ${args?.join(' ')}`);
+        }));
+        mockedExistsSync.mockReturnValue(true);
+        const ctx = makeCtx();
+        const result = await checkGitCredentialHelper(ctx);
+        expect(result.status).toBe('pass');
+    });
+});
 // ── 3 & 4. Auth + Network ───────────────────────────────────────────
 describe('checkAuthAndNetwork', () => {
     it('fails auth when no credentials', async () => {

package/dist/health/checks.d.ts

@@ -16,6 +16,19 @@ export declare function checkAuthAndNetwork(ctx: DoctorContext): Promise<{
     auth: CheckResult;
     network: CheckResult;
 }>;
+/**
+ * Verify that git's credential helper for the runwork origin is registered
+ * and that the binary it points at exists on disk. Catches the very common
+ * "logged in with an older CLI before configureGitCredentials shipped"
+ * state, where the user has credentials but git falls back to the system
+ * credential manager (Git Credential Manager popup on Windows, etc.) when
+ * trying to clone or push -- producing confusing UX with no obvious fix.
+ *
+ * The check is scoped to the *user's* logged-in baseUrl when available, so
+ * it doesn't false-fail on staging deployments that point at a different
+ * origin.
+ */
+export declare function checkGitCredentialHelper(ctx: DoctorContext): Promise<CheckResult>;
 export declare function checkProjectConfig(ctx: DoctorContext): Promise<CheckResult>;
 export declare function checkAppExists(ctx: DoctorContext): Promise<CheckResult>;
 export declare function checkGitRemote(ctx: DoctorContext): Promise<CheckResult>;

package/dist/health/checks.js

@@ -7,6 +7,7 @@ import { getCredentials } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { detectAgents, getAdapterBySlug } from '../agents/detect.js';
 import { httpFetch } from '../utils/http.js';
+import { probeGit, parseGitVersion } from '../git/preflight.js';
 // First-party distribution endpoints. Defaults match the plan, can be
 // overridden via RUNWORK_DOWNLOAD_BASE_URL for staging or debugging.
 const BASE_URL = process.env.RUNWORK_DOWNLOAD_BASE_URL || 'https://runwork.ai';
@@ -50,26 +51,39 @@ export function buildContext() {
 }
 // ── 1. System dependencies ───────────────────────────────────────────
 export async function checkSystemDeps() {
-    try {
-        const output = execFileSync('git', ['--version'], { stdio: 'pipe' }).toString().trim();
-        const match = output.match(/(\d+\.\d+(?:\.\d+)?)/);
-        const version = match ? match[1] : 'unknown';
-        if (match) {
-            const [major, minor] = version.split('.').map(Number);
-            if (major < 2 || (major === 2 && minor < 20)) {
-                return { name: 'system-deps', status: 'warn', message: `git ${version} (old -- consider upgrading)` };
-            }
-        }
-        return { name: 'system-deps', status: 'pass', message: `git ${version}` };
-    }
-    catch {
+    // Delegate to probeGit() so doctor agrees with the preflight gate used by
+    // `runwork clone`/`init`/`dev`. probeGit also has Windows fallback paths
+    // (`where.exe`, canonical install dirs) that the previous bare execFileSync
+    // missed when Bun's standalone-binary spawn lookup failed despite git
+    // being installed.
+    const probe = probeGit();
+    if (!probe.installed) {
+        const detail = probe.error?.message ? ` (${probe.error.message})` : '';
         return {
             name: 'system-deps',
             status: 'fail',
-            message: 'git not found in PATH',
+            message: `git not found in PATH${detail}`,
             fix: 'Install git: https://git-scm.com/downloads',
         };
     }
+    const version = parseGitVersion(probe.version) ?? 'unknown';
+    // Show how we found it on Windows fallback paths so the user can see
+    // whether their PATH is wired up or we needed a rescue.
+    const sourceSuffix = probe.source === 'where' ? ` (resolved via where.exe at ${probe.path})`
+        : probe.source === 'registry' ? ` (resolved via Git for Windows registry at ${probe.path})`
+            : probe.source === 'canonical' ? ` (resolved via canonical install path ${probe.path})`
+                : '';
+    if (version !== 'unknown') {
+        const [major, minor] = version.split('.').map(Number);
+        if (major < 2 || (major === 2 && minor < 20)) {
+            return {
+                name: 'system-deps',
+                status: 'warn',
+                message: `git ${version} (old -- consider upgrading)${sourceSuffix}`,
+            };
+        }
+    }
+    return { name: 'system-deps', status: 'pass', message: `git ${version}${sourceSuffix}` };
 }
 // ── 2. CLI version ───────────────────────────────────────────────────
 export async function checkCliVersion() {
@@ -224,6 +238,108 @@ export async function checkAuthAndNetwork(ctx) {
         };
     }
 }
+// ── 4a. Git credential helper registration ──────────────────────────
+/**
+ * Verify that git's credential helper for the runwork origin is registered
+ * and that the binary it points at exists on disk. Catches the very common
+ * "logged in with an older CLI before configureGitCredentials shipped"
+ * state, where the user has credentials but git falls back to the system
+ * credential manager (Git Credential Manager popup on Windows, etc.) when
+ * trying to clone or push -- producing confusing UX with no obvious fix.
+ *
+ * The check is scoped to the *user's* logged-in baseUrl when available, so
+ * it doesn't false-fail on staging deployments that point at a different
+ * origin.
+ */
+export async function checkGitCredentialHelper(ctx) {
+    if (!ctx.credentials) {
+        return {
+            name: 'git-credential-helper',
+            status: 'skip',
+            message: 'skipped (not logged in)',
+        };
+    }
+    // Make sure git itself is callable before we try to read its config --
+    // probeGit() prepends the resolved git directory to PATH for us when it
+    // resolves via fallback, so this also smooths the way for the
+    // execFileSync('git', ...) call below.
+    const git = probeGit();
+    if (!git.installed) {
+        return {
+            name: 'git-credential-helper',
+            status: 'skip',
+            message: 'skipped (git not installed)',
+        };
+    }
+    let origin;
+    try {
+        origin = new URL(ctx.credentials.baseUrl).origin;
+    }
+    catch {
+        return {
+            name: 'git-credential-helper',
+            status: 'fail',
+            message: `cannot parse baseUrl from credentials: ${ctx.credentials.baseUrl}`,
+            fix: 'runwork login',
+        };
+    }
+    // `--get-regexp` returns 1 (and prints nothing) when no entry matches,
+    // so a non-zero exit is a normal "not registered" signal -- not an error.
+    let helperConfig;
+    try {
+        const buf = execFileSync('git', ['config', '--global', '--get-regexp', 'credential\\..*runwork.*\\.helper'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        helperConfig = buf.toString('utf-8');
+    }
+    catch {
+        return {
+            name: 'git-credential-helper',
+            status: 'fail',
+            message: `no credential helper registered for ${origin}`,
+            fix: 'runwork login',
+        };
+    }
+    // Each line is `credential.<scope>.helper <value>`. We want a line whose
+    // <scope> matches the user's actual baseUrl origin (not e.g. a stale
+    // staging origin from a previous login).
+    const lines = helperConfig.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+    const escapedOrigin = origin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const scopedRegex = new RegExp(`^credential\\.${escapedOrigin}\\.helper\\s+(.+)$`);
+    const matchedLine = lines.find(line => scopedRegex.test(line));
+    if (!matchedLine) {
+        return {
+            name: 'git-credential-helper',
+            status: 'fail',
+            message: `no credential helper registered for ${origin} (found ${lines.length} other runwork helper entries)`,
+            fix: 'runwork login',
+        };
+    }
+    const value = scopedRegex.exec(matchedLine)?.[1] ?? '';
+    // Helper values starting with `!` are shell commands. Common shapes:
+    //   `!runwork git-credential-helper`                 (PATH-relative)
+    //   `!"/abs/path/to/runwork" git-credential-helper`  (post-Pass-2 hardening, POSIX)
+    //   `!"C:/.../runwork.exe" git-credential-helper`    (post-Pass-2 hardening, Windows)
+    // We only validate "absolute path" entries by existsSync() because that's
+    // the unambiguous case. PATH-relative entries we trust git+bash to resolve
+    // at invocation time (no good way to simulate that without running it).
+    const absoluteHelperRegex = /^!"?(\/|[A-Za-z]:[\\/])/;
+    if (absoluteHelperRegex.test(value)) {
+        const pathMatch = value.match(/^!"([^"]+)"|^!(\S+)/);
+        const helperPath = pathMatch?.[1] ?? pathMatch?.[2] ?? '';
+        if (helperPath && !existsSync(helperPath)) {
+            return {
+                name: 'git-credential-helper',
+                status: 'fail',
+                message: `helper registered but binary not found at ${helperPath}`,
+                fix: 'runwork login (re-registers with the current binary path)',
+            };
+        }
+    }
+    return {
+        name: 'git-credential-helper',
+        status: 'pass',
+        message: `registered for ${origin}`,
+    };
+}
 // ── 5. Project config ────────────────────────────────────────────────
 export async function checkProjectConfig(ctx) {
     const configPath = join(ctx.cwd, '.runwork.json');

package/dist/health/runner.js

@@ -1,4 +1,4 @@
-import { buildContext, checkSystemDeps, checkCliVersion, checkCliArtifactReachable, checkCliInstallLocation, checkAuthAndNetwork, checkProjectConfig, checkAppExists, checkGitRemote, checkAgentSetup, } from './checks.js';
+import { buildContext, checkSystemDeps, checkCliVersion, checkCliArtifactReachable, checkCliInstallLocation, checkAuthAndNetwork, checkGitCredentialHelper, checkProjectConfig, checkAppExists, checkGitRemote, checkAgentSetup, } from './checks.js';
 export async function runAllChecks() {
     const ctx = buildContext();
     const checks = [];
@@ -14,6 +14,10 @@ export async function runAllChecks() {
     const { auth, network } = await checkAuthAndNetwork(ctx);
     checks.push(auth);
     checks.push(network);
+    // 4a. Git credential helper -- catches "logged in but git auth not wired
+    //     up" state that surfaces on Windows as a Git Credential Manager
+    //     popup mid-clone with no obvious cause.
+    checks.push(await checkGitCredentialHelper(ctx));
     // 5. Project config
     checks.push(await checkProjectConfig(ctx));
     // 6. App exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runwork",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "CLI for Runwork: develop, preview, and deploy Runwork apps from your local machine.",
   "license": "UNLICENSED",
   "author": "Runwork <info@runwork.ai> (https://www.runwork.ai)",