dsh-git-branch-manage 1.2.0 → 1.3.0

package/lib/git.js

@@ -7,52 +7,90 @@ import { execFile } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { appendFile, mkdir, readFile, rm } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path';
+import { classifyGitFailure, FETCH_TIMEOUT_MS, PROBE_TIMEOUT_MS, PUSH_TIMEOUT_MS, VERIFY_TIMEOUT_MS } from './network.js';
 import { accelerateUrlError, localBranchName, normalizeAccelerateUrl } from './normalize.js';
 /** Failure of one git invocation: non-zero exit with the stderr text. */
 export class GitError extends Error {
     args;
     code;
     stderr;
-    constructor(args, code, stderr) {
+    timedOut;
+    constructor(args, code, stderr, 
+    /** True when the executor killed the command at its budget — no verdict. */
+    timedOut = false) {
         super(`git ${args.join(' ')} failed (exit ${code}): ${stderr.trim()}`);
         this.args = args;
         this.code = code;
         this.stderr = stderr;
+        this.timedOut = timedOut;
         this.name = 'GitError';
     }
 }
+/** Appended to reachability errors on an SSH remote: the HTTP channels
+ * (mirror prefix, DNS pin, http proxy) cannot carry an SSH transport, so the
+ * user has to change the endpoint itself. */
+const SSH_REMOTE_HINT = 'SSH remote: 代理与 IP 优选只作用于 https 远端；网络到 github.com:22 不通时可把远端改成 https://github.com/<owner>/<repo>.git。';
+/**
+ * Whether an endpoint speaks the SSH transport (`ssh://…`, `git@host:…`, or
+ * any `user@host:path` scp-style URL) — none of the network channels apply.
+ * @param url - a remote URL as git printed it, or undefined.
+ */
+export function isSshEndpoint(url) {
+    if (url === undefined)
+        return false;
+    const text = url.trim();
+    return text.startsWith('ssh://') || /^[^\s/]+@[^\s/]+:/.test(text);
+}
+/** Re-throw a failure with the SSH hint appended once. */
+function withSshHint(error) {
+    if (!(error instanceof GitError) || error.stderr.includes(SSH_REMOTE_HINT))
+        return error;
+    return new GitError(error.args, error.code, `${error.stderr.trimEnd()}\n\n${SSH_REMOTE_HINT}`, error.timedOut);
+}
 /** Default hard timeout for one git call: generous for every LOCAL
  * operation (status/log/commit/worktree) while still bounding hangs. */
 export const GIT_TIMEOUT_MS = 20_000;
-/** Network operations (fetch/push) get a far wider budget: a slow link with
- * a real pack transfer outruns the local default, and a killed push may have
- * ALREADY updated the remote refs — an error toast for a push that actually
- * landed. 120s still bounds a hung credential prompt. */
-export const NETWORK_TIMEOUT_MS = 120_000;
+/** Network budgets live in `network.ts` (probe/fetch/push/verify): a slow
+ * link with a real pack transfer outruns the local default, and a killed
+ * push may have ALREADY updated the remote refs — an error toast for a push
+ * that actually landed. */
 /** Real executor over node:child_process with a hard timeout. */
 export function childProcessExec(file, args, options) {
     return new Promise((resolvePromise) => {
-        execFile(file, args, { cwd: options.cwd, encoding: 'utf8', timeout: options.timeoutMs ?? GIT_TIMEOUT_MS, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+        execFile(file, args, {
+            cwd: options.cwd,
+            encoding: 'utf8',
+            timeout: options.timeoutMs ?? GIT_TIMEOUT_MS,
+            windowsHide: true,
+            maxBuffer: 4 * 1024 * 1024,
+            ...(options.env === undefined ? {} : { env: { ...process.env, ...options.env } }),
+        }, (error, stdout, stderr) => {
             const code = error === null ? 0 : typeof error.code === 'number' ? error.code : 1;
+            // execFile sets `killed` when its own timeout fired; the exit code is a
+            // synthetic 1, so without this flag a timeout is indistinguishable from
+            // a genuine refusal and a push would be reported failed although the
+            // remote may have applied it.
+            const timedOut = error !== null && error.killed === true;
             resolvePromise({
                 code,
                 stdout: stdout ?? '',
                 stderr: stderr ?? '',
                 ...(error instanceof Error ? { errorMessage: error.message } : {}),
+                ...(timedOut ? { timedOut } : {}),
             });
         });
     });
 }
 /** Run one git command; a non-zero exit raises {@link GitError} with stderr. */
-async function git(exec, cwd, args, timeoutMs) {
-    const result = await exec('git', args, { cwd, ...(timeoutMs === undefined ? {} : { timeoutMs }) });
+async function git(exec, cwd, args, timeoutMs, env) {
+    const result = await exec('git', args, { cwd, ...(timeoutMs === undefined ? {} : { timeoutMs }), ...(env === undefined ? {} : { env }) });
     if (result.code !== 0) {
         const diagnostic = result.stderr.trim() !== ''
             ? result.stderr
             : result.stdout.trim() !== ''
                 ? result.stdout
                 : result.errorMessage ?? 'git produced no diagnostic output';
-        throw new GitError(args, result.code, diagnostic);
+        throw new GitError(args, result.code, diagnostic, result.timedOut === true);
     }
     return result.stdout;
 }
@@ -509,7 +547,11 @@ export async function deleteBranch(exec, repoRoot, name) {
 export function accelArgs(prefix) {
     if (prefix === undefined || accelerateUrlError(prefix) !== undefined)
         return [];
-    return ['-c', `url.${normalizeAccelerateUrl(prefix)}.insteadOf=https://github.com/`];
+    const normalized = normalizeAccelerateUrl(prefix);
+    // The setting is a proxy prefix, not a replacement for github.com. Also
+    // accept a prefix that already includes the complete GitHub base URL.
+    const base = normalized.endsWith('/https://github.com/') ? normalized : `${normalized}https://github.com/`;
+    return ['-c', `url.${base}.insteadOf=https://github.com/`];
 }
 /**
  * Sync remote-tracking refs: fetch every remote and prune tracking branches
@@ -524,8 +566,51 @@ export function accelArgs(prefix) {
  * @param authArgs - optional per-host credential `-c` pairs (see
  * `credentials.ts`); prepended before the subcommand like the accel rewrite.
  */
-export async function fetchAll(exec, repoRoot, accelPrefix, authArgs = []) {
-    await git(exec, repoRoot, [...accelArgs(accelPrefix), ...authArgs, 'fetch', '--all', '--prune'], NETWORK_TIMEOUT_MS);
+export async function fetchAll(exec, repoRoot, accelPrefix, authArgs = [], options = {}) {
+    const accel = accelArgs(accelPrefix);
+    const base = [...accel, ...authArgs];
+    try {
+        await git(exec, repoRoot, [...base, 'fetch', '--all', '--prune'], FETCH_TIMEOUT_MS);
+    }
+    catch (firstError) {
+        let error = firstError;
+        // The mirror is only an accelerator, never an authority: a private repo
+        // answers 401 there, a bad day answers 5xx, and neither should hide the
+        // direct URL. Reads are idempotent, so one direct retry costs nothing.
+        if (accel.length > 0) {
+            try {
+                await git(exec, repoRoot, [...authArgs, 'fetch', '--all', '--prune'], FETCH_TIMEOUT_MS);
+                return;
+            }
+            catch (directError) {
+                error = directError;
+            }
+        }
+        // Reading is idempotent, so a retry on another channel cannot duplicate
+        // anything. The first remote's URL stands for the fetch: with one remote
+        // (the normal case) it IS the fetch.
+        const failure = error instanceof GitError ? classifyGitFailure(error.stderr, { timedOut: error.timedOut }) : undefined;
+        if (failure === undefined || !failure.retryable || (options.fallbackChannels ?? []).length === 0)
+            throw error;
+        const names = (await gitMaybe(exec, repoRoot, ['remote']))?.split('\n').map(item => item.trim()).filter(item => item !== '') ?? [];
+        const first = names[0];
+        if (first === undefined)
+            throw error;
+        const endpoint = (await gitMaybe(exec, repoRoot, ['remote', 'get-url', first]))?.trim() ?? '';
+        if (endpoint === '')
+            throw error;
+        // An SSH remote has no HTTP channel to switch to; the hint is the only
+        // actionable answer (and saves three probes that can never succeed).
+        if (isSshEndpoint(endpoint))
+            throw withSshHint(error);
+        // The probe IS the retry here: reading is idempotent, so a successful
+        // channel probe has already performed the work. A channel pins the real
+        // host, so the mirror rewrite is dropped with it.
+        await firstWorkingChannel(endpoint, options, async (channel) => {
+            await git(exec, repoRoot, [...channel, ...authArgs, 'fetch', '--all', '--prune'], FETCH_TIMEOUT_MS);
+        })
+            .catch(() => { throw error; });
+    }
 }
 /**
  * Update the CURRENT checkout: fetch every remote, then fast-forward the
@@ -551,6 +636,114 @@ export async function updateBranch(exec, cwd, accelPrefix, authArgs = []) {
     const branch = (await gitMaybe(exec, cwd, ['branch', '--show-current']))?.trim() ?? '';
     return { branch, updated: before !== after };
 }
+/**
+ * Walk the fallback chain until one provider yields a channel that answers
+ * its own probe. A provider that returns argv which cannot reach the endpoint
+ * is skipped, not fatal: the direct error is still the one worth reporting.
+ * @param endpoint - URL the command talks to.
+ * @param options - caller's channel list.
+ * @param probe - probe for one candidate argv (throws when it fails).
+ */
+async function firstWorkingChannel(endpoint, options, probe) {
+    for (const provider of options.fallbackChannels ?? []) {
+        const args = await provider(endpoint);
+        if (args === undefined)
+            continue;
+        try {
+            await probe(args);
+            return args;
+        }
+        catch {
+            // Try the next provider; the caller reports the direct failure if none works.
+        }
+    }
+    return undefined;
+}
+/**
+ * Pick the channel a write will use: the direct one when its probe answers,
+ * otherwise the fallback channel when the failure is retryable and the
+ * caller supplied one. The fallback is probed too — a fallback that cannot
+ * reach the endpoint must not replace a clear direct error with a vague one.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param target - resolved endpoint of the write.
+ * @param options - caller's channels.
+ * @param authArgs - per-host credential argv.
+ * @returns the argv to prepend to the push and its verification read.
+ */
+async function chooseChannel(exec, cwd, target, options, authArgs) {
+    const direct = options.channelArgs ?? [];
+    if (target.url === undefined)
+        return direct;
+    try {
+        await probePushTarget(exec, cwd, target, { channelArgs: direct }, authArgs);
+        return direct;
+    }
+    catch (error) {
+        // A credential or divergence failure is about state, not reachability:
+        // pinning an IP would just fail again with the same message. An SSH remote
+        // cannot use any HTTP channel at all — say so instead of probing three
+        // times into the same wall.
+        if (isSshEndpoint(target.url))
+            throw withSshHint(error);
+        const failure = error instanceof GitError ? classifyGitFailure(error.stderr, { timedOut: error.timedOut }) : undefined;
+        if (failure === undefined || !failure.retryable)
+            throw error;
+        const fallback = await firstWorkingChannel(target.url, options, async (args) => {
+            await probePushTarget(exec, cwd, target, { channelArgs: args }, authArgs);
+        });
+        if (fallback === undefined)
+            throw error;
+        return fallback;
+    }
+}
+/**
+ * Resolve where a write to `@{u}` would go, WITHOUT sending anything.
+ * `remote get-url --push` is the one source of truth for the endpoint: a
+ * remote may configure a separate `pushurl`, and probing the fetch URL
+ * would validate a host the push never talks to.
+ * @param exec - executor seam.
+ * @param cwd - directory whose checked-out branch supplies the upstream.
+ * @param authArgs - per-host credential argv (kept for symmetry; `rev-parse`
+ * and `remote` are local and never authenticate).
+ * @returns the remote (and its push URL when git names one), or undefined
+ * when the branch has no upstream — that case belongs to git's own message.
+ */
+export async function resolvePushTarget(exec, cwd, authArgs = []) {
+    const upstream = (await gitMaybe(exec, cwd, [...authArgs, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']))?.trim() ?? '';
+    const slash = upstream.indexOf('/');
+    if (slash <= 0)
+        return undefined;
+    const remote = upstream.slice(0, slash);
+    const url = (await gitMaybe(exec, cwd, ['remote', 'get-url', '--push', remote]))?.trim() ?? '';
+    return { remote, ...(url === '' ? {} : { url }) };
+}
+/**
+ * Reachability probe for a write: a READ of the push endpoint. A host that
+ * cannot answer `ls-remote` cannot receive a pack either, so failing here
+ * costs the probe budget (10s) instead of the push budget (600s), and the
+ * caller learns which endpoint was unreachable before any object moved.
+ * Terminal prompts are disabled for the probe: a probe must fail, never
+ * block on a credential dialog the user cannot see.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param target - endpoint from {@link resolvePushTarget}.
+ * @param options - channel argv (proxy) to route the probe the same way.
+ * @param authArgs - per-host credential argv.
+ */
+export async function probePushTarget(exec, cwd, target, options = {}, authArgs = []) {
+    await git(exec, cwd, [...(options.channelArgs ?? []), ...authArgs, 'ls-remote', '--heads', target.url ?? target.remote], PROBE_TIMEOUT_MS, { GIT_TERMINAL_PROMPT: '0' });
+}
+/**
+ * Read one remote ref through the same channel a write used. The single
+ * line answering `ls-remote --refs <endpoint> <ref>` is `<sha>\t<ref>`;
+ * anything else (no output, a diagnostic) answers undefined.
+ */
+async function remoteRefOf(exec, cwd, target, ref, options, authArgs) {
+    const listed = await gitMaybe(exec, cwd, [...(options.channelArgs ?? []), ...authArgs, 'ls-remote', '--refs', target.url ?? target.remote, ref], VERIFY_TIMEOUT_MS);
+    const line = (listed ?? '').split('\n').map(item => item.trim()).find(item => item !== '');
+    return line?.split(/\s+/)[0];
+}
 /**
  * Push the branch checked out by `cwd` to its upstream (`@{u}`) — the
  * counterpart of {@link updateBranch}. Deliberately a bare `git push`: the
@@ -565,16 +758,41 @@ export async function updateBranch(exec, cwd, accelPrefix, authArgs = []) {
  * pushed content to a third party.
  * @param exec - executor seam.
  * @param cwd - directory whose checked-out branch is pushed.
+ * @param authArgs - per-host credential argv.
+ * @param options - channel argv (proxy) applied to the probe and the push.
  * @returns the branch and whether the remote-tracking ref changed. A branch
  * without an upstream can still be handed to `git push`, so Git's own
  * push-specific diagnostic is preserved; in that case `pushed` is false.
  */
-export async function pushBranch(exec, cwd, authArgs = []) {
+export async function pushBranch(exec, cwd, authArgs = [], options = {}) {
     const before = await gitMaybe(exec, cwd, ['rev-parse', '@{u}']);
-    await git(exec, cwd, [...authArgs, 'push'], NETWORK_TIMEOUT_MS);
-    const after = await gitMaybe(exec, cwd, ['rev-parse', '@{u}']);
+    if (before === undefined) {
+        // No upstream: let git push speak (its message is the actionable one)
+        // and skip a probe that could only replace it with a reachability error.
+        await git(exec, cwd, [...(options.channelArgs ?? []), ...authArgs, 'push'], PUSH_TIMEOUT_MS);
+        const branch = (await gitMaybe(exec, cwd, ['branch', '--show-current']))?.trim() ?? '';
+        return { branch, pushed: false };
+    }
     const branch = (await gitMaybe(exec, cwd, ['branch', '--show-current']))?.trim() ?? '';
-    return { branch, pushed: before !== undefined && after !== undefined && before.trim() !== after.trim() };
+    const head = (await git(exec, cwd, ['rev-parse', 'HEAD'])).trim();
+    const target = await resolvePushTarget(exec, cwd, authArgs);
+    const channel = target === undefined ? (options.channelArgs ?? []) : await chooseChannel(exec, cwd, target, options, authArgs);
+    try {
+        await git(exec, cwd, [...channel, ...authArgs, 'push'], PUSH_TIMEOUT_MS);
+    }
+    catch (error) {
+        // A killed push carries no verdict: the remote may have applied it before
+        // the socket died. One `ls-remote` settles it; anything else (a genuine
+        // refusal, a rejected pack) is reported as-is and never retried.
+        if (error instanceof GitError && error.timedOut && target !== undefined && branch !== '') {
+            const landed = await remoteRefOf(exec, cwd, target, `refs/heads/${branch}`, { channelArgs: channel }, authArgs);
+            if (landed === head)
+                return { branch, pushed: true, note: 'timed-out-but-landed' };
+        }
+        throw error;
+    }
+    const after = await gitMaybe(exec, cwd, ['rev-parse', '@{u}']);
+    return { branch, pushed: after !== undefined && before.trim() !== after.trim() };
 }
 /** Every LOCAL tag name of the repository, in git's own sort order. */
 export async function listTagNames(exec, cwd) {
@@ -631,16 +849,34 @@ export async function resolvePushRemote(exec, cwd) {
  * @param remote - the remote to publish to (see {@link resolvePushRemote}).
  * @returns the tag, the remote, and whether the push had to run.
  */
-export async function pushTag(exec, cwd, name, remote, authArgs = []) {
+export async function pushTag(exec, cwd, name, remote, authArgs = [], options = {}) {
     const ref = `refs/tags/${name}`;
     const local = (await git(exec, cwd, ['rev-parse', '--verify', ref])).trim();
-    const listed = await gitMaybe(exec, cwd, [...authArgs, 'ls-remote', '--refs', remote, ref], NETWORK_TIMEOUT_MS);
-    const present = (listed ?? '').split('\n')
-        .map(line => line.trim().split(/\s+/)[0] ?? '')
-        .includes(local);
-    if (present)
+    // The existence check doubles as the reachability probe and as the
+    // verification a timed-out push needs: the same read decides all three.
+    // Same channel policy as a branch push, but only when a fallback exists:
+    // without one a tag needs no extra probe (and no extra remote lookup).
+    let target = { remote };
+    let channel = options.channelArgs ?? [];
+    if ((options.fallbackChannels ?? []).length > 0) {
+        const url = (await gitMaybe(exec, cwd, ['remote', 'get-url', '--push', remote]))?.trim() ?? '';
+        target = url === '' ? { remote } : { remote, url };
+        channel = await chooseChannel(exec, cwd, target, options, authArgs);
+    }
+    const already = await remoteRefOf(exec, cwd, target, ref, { channelArgs: channel }, authArgs);
+    if (already === local)
         return { tag: name, remote, pushed: false };
-    await git(exec, cwd, [...authArgs, 'push', remote, `${ref}:${ref}`], NETWORK_TIMEOUT_MS);
+    try {
+        await git(exec, cwd, [...channel, ...authArgs, 'push', remote, `${ref}:${ref}`], PUSH_TIMEOUT_MS);
+    }
+    catch (error) {
+        if (error instanceof GitError && error.timedOut) {
+            const landed = await remoteRefOf(exec, cwd, target, ref, { channelArgs: channel }, authArgs);
+            if (landed === local)
+                return { tag: name, remote, pushed: true, note: 'timed-out-but-landed' };
+        }
+        throw error;
+    }
     return { tag: name, remote, pushed: true };
 }
 /** Guard for route inputs: a non-empty absolute directory path. */

package/lib/index.d.ts

@@ -30,6 +30,9 @@ export interface Config {
     cnAccelerate?: Volatile<boolean> | boolean;
     /** cn-accelerate mirror prefix; absent = the shipped default. */
     cnAccelerateUrl?: Volatile<string> | string;
+    /** Explicit proxy URL (http/https/socks5) tried before any other fallback;
+     * empty/absent = no proxy channel. */
+    networkProxy?: Volatile<string> | string;
 }
 /** The shipped prune cap (whole storage root, valid git worktrees only). */
 export declare const KEEP_WORKTREES_DEFAULT = 30;
@@ -48,6 +51,12 @@ export declare function validateConfig(config: Config): void;
  * not a fetchable remote. Absent = the shipped default, which passes.
  */
 export declare function validateCnAccelerateUrl(value: string | undefined): void;
+/**
+ * An explicit proxy must be a URL git can hand to libcurl: no credentials
+ * (they would be stored and displayed in clear text), no path. Empty means
+ * "no proxy channel", which is the default and always valid.
+ */
+export declare function validateNetworkProxy(value: string | undefined): void;
 /**
  * The prune cap must be an integer >= 1: 0 would read as "create then
  * immediately self-delete" (the fresh worktree is excluded, but every other
@@ -76,6 +85,8 @@ export interface SectionConfig {
     cnAccelerate?: boolean;
     /** cn-accelerate mirror prefix; absent = the shipped default. */
     cnAccelerateUrl?: string;
+    /** Explicit proxy URL; absent/blank = no proxy channel. */
+    networkProxy?: string;
 }
 /** The section-shaped view of a config: absent keys stay absent
  * (`exactOptionalPropertyTypes`) except the switches, which spell their

package/lib/index.js

@@ -8,13 +8,15 @@
 import { homedir } from 'node:os';
 import z from '@deepseek-ai/schemastery';
 import { childProcessExec } from './git.js';
+import { pinnedChannelFor, pinnedProbe } from './network-ip.js';
+import { proxyArgs, proxyUrlError, systemProxyUrl } from './network-proxy.js';
 import { ACCEL_DEFAULT_URL, accelerateUrlError } from './normalize.js';
-import { handleCredentials, handleCredentialsDelete, handleCredentialsImport, handleCredentialsOAuthPoll, handleCredentialsOAuthStart, handleCredentialsSave, handleRemote, handleRemotes, handleAiCommitMessage, handleChanges, handleCommit, handleCommitFiles, handleCreateBranch, handleCreateTag, handleCreateWorktree, handleDeleteBranch, handleEnsureDirectory, handleFetch, handleGroupWorktrees, handleInspectWorktree, handleLog, handlePathExists, handlePurgeDirectory, handlePushTag, handleRemoveWorktree, handleRenameBranch, handleStage, handleStatus, handleSwitch, handleUpdate, handlePush, handleWorktreesAll, } from './routes.js';
+import { handleCredentials, handleCredentialsDelete, handleCredentialsImport, handleCredentialsOAuthPoll, handleCredentialsOAuthStart, handleCredentialsSave, handleRemote, handleRemotes, handleAiCommitMessage, handleChanges, handleCommit, handleCommitFiles, handleCreateBranch, handleCreateTag, handleCreateWorktree, handleDeleteBranch, handleEnsureDirectory, handleFetch, handleGroupWorktrees, handleInspectWorktree, handleLog, handlePathExists, handlePurgeDirectory, handlePushTag, handleRemoveWorktree, handleRenameBranch, handleStage, handleStatus, handleSwitch, handleUpdate, handlePush, handleNetworkProbe, handleWorktreesAll, } from './routes.js';
 import { validateRootDir } from './settings.js';
 import { gitNetworkTool } from './network-tool.js';
 import { gitCredentialsTool } from './tool.js';
 import { createCredentialService } from './credential-service.js';
-import { ROUTE_AI_COMMIT_MESSAGE, ROUTE_BRANCH, ROUTE_BRANCH_DELETE, ROUTE_BRANCH_RENAME, ROUTE_CHANGES, ROUTE_COMMIT, ROUTE_COMMIT_FILES, ROUTE_CREDENTIALS, ROUTE_CREDENTIALS_DELETE, ROUTE_CREDENTIALS_IMPORT, ROUTE_CREDENTIALS_OAUTH_POLL, ROUTE_CREDENTIALS_OAUTH_START, ROUTE_CREDENTIALS_SAVE, ROUTE_ENSURE_DIRECTORY, ROUTE_EXISTS, ROUTE_FETCH, ROUTE_GROUP, ROUTE_INSPECT, ROUTE_LOG, ROUTE_PUSH, ROUTE_PURGE, ROUTE_REMOTE, ROUTE_REMOTES, ROUTE_REMOVE, ROUTE_STAGE, ROUTE_STATUS, ROUTE_SWITCH, ROUTE_TAG, ROUTE_TAG_PUSH, ROUTE_UPDATE, ROUTE_WORKTREE, ROUTE_WORKTREES_ALL } from './wire.js';
+import { ROUTE_AI_COMMIT_MESSAGE, ROUTE_BRANCH, ROUTE_BRANCH_DELETE, ROUTE_BRANCH_RENAME, ROUTE_CHANGES, ROUTE_COMMIT, ROUTE_COMMIT_FILES, ROUTE_CREDENTIALS, ROUTE_CREDENTIALS_DELETE, ROUTE_CREDENTIALS_IMPORT, ROUTE_CREDENTIALS_OAUTH_POLL, ROUTE_CREDENTIALS_OAUTH_START, ROUTE_CREDENTIALS_SAVE, ROUTE_ENSURE_DIRECTORY, ROUTE_EXISTS, ROUTE_FETCH, ROUTE_GROUP, ROUTE_INSPECT, ROUTE_LOG, ROUTE_NETWORK_PROBE, ROUTE_PUSH, ROUTE_PURGE, ROUTE_REMOTE, ROUTE_REMOTES, ROUTE_REMOVE, ROUTE_STAGE, ROUTE_STATUS, ROUTE_SWITCH, ROUTE_TAG, ROUTE_TAG_PUSH, ROUTE_UPDATE, ROUTE_WORKTREE, ROUTE_WORKTREES_ALL } from './wire.js';
 export const name = 'dsh-git-branch';
 export const inject = [];
 /** Largest accepted request body (bytes) — these payloads are a few strings. */
@@ -43,10 +45,11 @@ export const Config = z.object({
     postCreateCopyFiles: z.array(z.string()).default([]).volatile(),
     cnAccelerate: z.boolean().default(false).volatile(),
     cnAccelerateUrl: z.string().default(ACCEL_DEFAULT_URL).volatile(),
+    networkProxy: z.string().default('').volatile(),
 });
 /** Reject stale or misspelled config keys before defaults can hide them. */
 export function validateConfig(config) {
-    const unknown = Object.keys(config).find(key => key !== 'rootDir' && key !== 'groupSidebar' && key !== 'fetchBeforeCreate' && key !== 'autoPruneWorktrees' && key !== 'keepWorktrees' && key !== 'postCreateCopyFiles' && key !== 'cnAccelerate' && key !== 'cnAccelerateUrl');
+    const unknown = Object.keys(config).find(key => key !== 'rootDir' && key !== 'groupSidebar' && key !== 'fetchBeforeCreate' && key !== 'autoPruneWorktrees' && key !== 'keepWorktrees' && key !== 'postCreateCopyFiles' && key !== 'cnAccelerate' && key !== 'cnAccelerateUrl' && key !== 'networkProxy');
     if (unknown !== undefined) {
         throw new Error(`GitWorktreeConfig: unknown key "${unknown}"`);
     }
@@ -77,6 +80,7 @@ export function validateConfig(config) {
         throw new Error('GitWorktreeConfig: "cnAccelerate" must be a boolean');
     }
     validateCnAccelerateUrl(readVolatile(config.cnAccelerateUrl));
+    validateNetworkProxy(readVolatile(config.networkProxy));
     validateKeepWorktrees(readVolatile(config.keepWorktrees));
     validateRootDir(root);
 }
@@ -93,6 +97,18 @@ export function validateCnAccelerateUrl(value) {
         throw new Error('GitWorktreeConfig: "cnAccelerateUrl" must be an http(s) URL without whitespace');
     }
 }
+/**
+ * An explicit proxy must be a URL git can hand to libcurl: no credentials
+ * (they would be stored and displayed in clear text), no path. Empty means
+ * "no proxy channel", which is the default and always valid.
+ */
+export function validateNetworkProxy(value) {
+    if (value === undefined || value === '')
+        return;
+    if (typeof value !== 'string' || proxyUrlError(value) !== undefined) {
+        throw new Error('GitWorktreeConfig: "networkProxy" must be an http(s)/socks5 proxy URL without credentials');
+    }
+}
 /**
  * The prune cap must be an integer >= 1: 0 would read as "create then
  * immediately self-delete" (the fresh worktree is excluded, but every other
@@ -120,10 +136,12 @@ export function sectionOf(config) {
     const keepWorktrees = readVolatile(config.keepWorktrees);
     const cnAccelerate = readVolatile(config.cnAccelerate);
     const cnAccelerateUrl = readVolatile(config.cnAccelerateUrl);
+    const networkProxy = readVolatile(config.networkProxy);
     return {
         ...(rootDir === undefined ? {} : { rootDir }),
         ...(postCreateCopyFiles === undefined ? {} : { postCreateCopyFiles }),
         ...(cnAccelerateUrl === undefined ? {} : { cnAccelerateUrl }),
+        ...(networkProxy === undefined || networkProxy === '' ? {} : { networkProxy }),
         // The composition layer spells the shipped defaults so a user-layer
         // unset can always fall back to them.
         groupSidebar: groupSidebar ?? true,
@@ -163,11 +181,23 @@ export function apply(ctx, config = {}) {
     }, 'git-worktree: credential service dispose');
     const deps = () => ({
         exec: childProcessExec,
+        networkChannels: (exec, cwd, authArgs) => {
+            const providers = [];
+            // An explicit proxy outranks the IP heuristic: the user configured it
+            // because it is the path they trust. Absent/blank = no proxy channel.
+            const proxy = readVolatile(currentConfig().networkProxy);
+            if (proxy !== undefined && proxy !== '')
+                providers.push(async () => proxyArgs(proxy));
+            providers.push(endpoint => pinnedChannelFor({ endpoint, probe: pinnedProbe(exec, cwd, endpoint, authArgs) }));
+            return providers;
+        },
         sectionRootDir: () => readVolatile(currentConfig().rootDir),
         sectionFetchBeforeCreate: () => readVolatile(currentConfig().fetchBeforeCreate),
         sectionPostCreateCopyFiles: () => readVolatile(currentConfig().postCreateCopyFiles),
         sectionCnAccelerate: () => readVolatile(currentConfig().cnAccelerate),
         sectionCnAccelerateUrl: () => readVolatile(currentConfig().cnAccelerateUrl),
+        sectionNetworkProxy: () => readVolatile(currentConfig().networkProxy),
+        sectionSystemProxy: () => systemProxyUrl(childProcessExec, homedir()),
         home: () => homedir(),
         envHome: () => process.env.DSH_HOME,
         credentialsService: credentials,
@@ -253,6 +283,7 @@ export function apply(ctx, config = {}) {
         postRoute(ROUTE_GROUP, 'group', handleGroupWorktrees);
         postRoute(ROUTE_UPDATE, 'update', handleUpdate);
         postRoute(ROUTE_PUSH, 'push', handlePush);
+        postRoute(ROUTE_NETWORK_PROBE, 'network-probe', handleNetworkProbe);
         postRoute(ROUTE_INSPECT, 'inspect', handleInspectWorktree);
         postRoute(ROUTE_REMOVE, 'remove', handleRemoveWorktree);
         postRoute(ROUTE_EXISTS, 'exists', handlePathExists);

package/lib/network-ip.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The second network channel: resolve the host yourself, then race a few
+ * edge IPs with a real `ls-remote` and pin the winner with
+ * `http.curloptResolve`.
+ *
+ * Why a runtime lookup and not a built-in table: measured on 2026-11-03, a
+ * static list of eight GitHub edge IPs had seven TCP-reachable but only four
+ * that could answer `ls-remote`, two of them taking 88s and 211s. Edge
+ * assignment moves; a table baked into a release rots. So the table is
+ * fetched from DNS-over-HTTPS at the moment of need, and every candidate is
+ * validated by the same command the push will run.
+ *
+ * TCP reachability is deliberately NOT the judge: `connect()` succeeding
+ * says nothing about TLS termination or the git endpoint behind it.
+ */
+import type { Exec } from './git.js';
+/** Budget for ONE pinned probe; candidates run in parallel, so the race is bounded by this. */
+export declare const IP_PROBE_TIMEOUT_MS = 5000;
+/** How long a winning channel is reused before the IPs are re-resolved. */
+export declare const IP_CACHE_TTL_MS = 600000;
+/**
+ * Concurrent candidates. Probes run in parallel, so the wall clock is one
+ * timeout no matter how many run; this only bounds process count.
+ */
+export declare const MAX_IP_CANDIDATES = 6;
+/** Drop every cached channel (tests, and a user-triggered re-probe). */
+export declare function resetIpChannelCache(): void;
+/**
+ * Pull the IPv4 answers out of one DoH JSON body. Anything malformed answers
+ * `[]` rather than throwing: a resolver hiccup must degrade to the direct
+ * channel, not fail the push before it starts.
+ */
+export declare function parseDohIps(payload: unknown): string[];
+/** Budget for one DoH query. Three resolvers are asked in parallel, so this bounds resolution. */
+export declare const DOH_TIMEOUT_MS = 3000;
+/**
+ * Ask every resolver about one host, in parallel, and union the answers.
+ *
+ * Sequential fallback was measured to be the wrong shape: the resolvers that
+ * are blocked here are blocked for the full timeout each, so a "fallback
+ * chain" spends three timeouts to learn what one parallel round trip tells.
+ * @param host - hostname to resolve.
+ * @param fetchImpl - fetch seam (tests inject a stub).
+ */
+export declare function resolveHostIps(host: string, fetchImpl?: typeof fetch): Promise<string[]>;
+/**
+ * Candidates to race for one endpoint: the endpoint's own answers first, then
+ * the sibling services' answers (only for `github.com`), deduplicated and
+ * capped at {@link MAX_IP_CANDIDATES}. Everything runs in parallel, so the
+ * whole lookup is bounded by {@link DOH_TIMEOUT_MS}.
+ * @param host - endpoint hostname.
+ * @param fetchImpl - fetch seam.
+ */
+export declare function candidateIpsFor(host: string, fetchImpl?: typeof fetch): Promise<string[]>;
+/** Whether this endpoint is one the pinned-IP channel may rewrite. */
+export declare function isOptimizableEndpoint(endpoint: string): boolean;
+/**
+ * The argv that pins `host:443` to one IP for a single command. `-c` goes
+ * before the subcommand, per git's global-option rule.
+ */
+export declare function pinArgs(host: string, ip: string): readonly string[];
+/** Seam for the race: resolves when the candidate answered `ls-remote`. */
+export type Probe = (args: readonly string[]) => Promise<void>;
+/**
+ * Race up to {@link MAX_IP_CANDIDATES} pinned channels and answer the argv of
+ * the first that actually answers `ls-remote`. "First" means first to
+ * SUCCEED: all candidates start together and a slow-but-working IP can beat
+ * one that fails later.
+ * @param ips - candidates in resolver order.
+ * @param host - hostname being pinned.
+ * @param probe - one pinned probe (the caller supplies the budget + argv).
+ * @returns the winning `-c` argv, or undefined when every candidate failed.
+ */
+export declare function racePinnedChannels(ips: readonly string[], host: string, probe: Probe): Promise<readonly string[] | undefined>;
+/**
+ * The channel a read/write may fall back to when the direct one fails in a
+ * retryable way. Wraps resolution + race + caching; answers undefined for
+ * endpoints outside {@link OPTIMIZABLE_HOSTS} or when nothing works.
+ * @param options.endpoint - the URL the command would use.
+ * @param options.probe - one pinned probe, built by {@link pinnedProbe}.
+ * @param options.now - clock seam for the cache.
+ * @param options.fetchImpl - DoH fetch seam.
+ */
+export declare function pinnedChannelFor(options: {
+    endpoint: string;
+    probe: Probe;
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+}): Promise<readonly string[] | undefined>;
+/**
+ * Build the probe the race runs: one pinned `ls-remote` at the probe budget,
+ * with terminal prompts disabled so a credentialed endpoint fails instead of
+ * hanging on an invisible dialog.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param endpoint - URL being probed.
+ * @param authArgs - per-host credential argv.
+ */
+export declare function pinnedProbe(exec: Exec, cwd: string, endpoint: string, authArgs?: readonly string[]): Probe;