dsh-git-branch-manage 1.2.0 → 1.3.1

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;

package/lib/network-ip.js

@@ -0,0 +1,206 @@
+/** Budget for ONE pinned probe; candidates run in parallel, so the race is bounded by this. */
+export const IP_PROBE_TIMEOUT_MS = 5_000;
+/** How long a winning channel is reused before the IPs are re-resolved. */
+export const IP_CACHE_TTL_MS = 600_000;
+/**
+ * Concurrent candidates. Probes run in parallel, so the wall clock is one
+ * timeout no matter how many run; this only bounds process count.
+ */
+export const MAX_IP_CANDIDATES = 6;
+/** Hosts this channel applies to. A mirror or an enterprise host has its own DNS. */
+const OPTIMIZABLE_HOSTS = ['github.com'];
+/** DNS-over-HTTPS resolvers, tried in order until one answers. */
+const DOH_URLS = [
+    host => `https://dns.alidns.com/resolve?name=${encodeURIComponent(host)}&type=A`,
+    host => `https://doh.pub/dns-query?name=${encodeURIComponent(host)}&type=A`,
+    host => `https://doh.360.cn/resolve?name=${encodeURIComponent(host)}&type=A`,
+];
+/**
+ * Hostnames whose answers widen the candidate pool for `github.com`.
+ *
+ * Measured on 2026-11-03: `dns.alidns.com` answered a single address for
+ * `github.com` (20.205.243.166) and `doh.pub` answered a different one
+ * (140.82.112.3) — one resolver gives one edge, and that edge may be dead.
+ * GitHub's edge fleet serves `api.`/`codeload.` from the same ranges, so their
+ * answers are extra tickets in the same lottery. Every candidate still has to
+ * answer a real `ls-remote` before it is used, so a wrong guess costs one
+ * parallel probe and nothing else.
+ */
+const SIBLING_SOURCES = ['api.github.com', 'codeload.github.com'];
+const cache = new Map();
+/** Drop every cached channel (tests, and a user-triggered re-probe). */
+export function resetIpChannelCache() {
+    cache.clear();
+}
+/**
+ * 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 function parseDohIps(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return [];
+    const answer = payload.Answer;
+    if (!Array.isArray(answer))
+        return [];
+    const ips = [];
+    for (const item of answer) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const record = item;
+        if (record.type !== 1 || typeof record.data !== 'string')
+            continue;
+        if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(record.data))
+            continue;
+        if (!record.data.split('.').every(part => Number(part) <= 255))
+            continue;
+        if (!ips.includes(record.data))
+            ips.push(record.data);
+    }
+    return ips;
+}
+/** Budget for one DoH query. Three resolvers are asked in parallel, so this bounds resolution. */
+export const DOH_TIMEOUT_MS = 3_000;
+/** One DoH question, or no answers (a blocked resolver is a normal state, not an error). */
+async function askResolver(url, fetchImpl) {
+    try {
+        const response = await fetchImpl(url, {
+            headers: { accept: 'application/dns-json' },
+            signal: AbortSignal.timeout(DOH_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return [];
+        return parseDohIps(await response.json());
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 async function resolveHostIps(host, fetchImpl = fetch) {
+    const answers = await Promise.all(DOH_URLS.map(url => askResolver(url(host), fetchImpl)));
+    const ips = [];
+    for (const answer of answers) {
+        for (const ip of answer) {
+            if (!ips.includes(ip))
+                ips.push(ip);
+        }
+    }
+    return ips;
+}
+/**
+ * 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 async function candidateIpsFor(host, fetchImpl = fetch) {
+    const sources = host === 'github.com' ? [host, ...SIBLING_SOURCES] : [host];
+    const answers = await Promise.all(sources.map(source => resolveHostIps(source, fetchImpl)));
+    const ips = [];
+    for (const answer of answers) {
+        for (const ip of answer) {
+            if (!ips.includes(ip))
+                ips.push(ip);
+        }
+    }
+    return ips.slice(0, MAX_IP_CANDIDATES);
+}
+/** Whether this endpoint is one the pinned-IP channel may rewrite. */
+export function isOptimizableEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        return url.protocol === 'https:' && OPTIMIZABLE_HOSTS.includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function pinArgs(host, ip) {
+    return ['-c', `http.curloptResolve=${host}:443:${ip}`];
+}
+/**
+ * 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 async function racePinnedChannels(ips, host, probe) {
+    const candidates = ips.slice(0, MAX_IP_CANDIDATES);
+    const results = await Promise.all(candidates.map(async (ip) => {
+        const args = pinArgs(host, ip);
+        try {
+            await probe(args);
+            return args;
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    // Promise.all keeps resolver order, so a tie goes to the first answer.
+    return results.find(item => item !== 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 async function pinnedChannelFor(options) {
+    const { endpoint, probe } = options;
+    if (!isOptimizableEndpoint(endpoint))
+        return undefined;
+    const host = new URL(endpoint).hostname;
+    const now = options.now ?? Date.now;
+    const cached = cache.get(endpoint);
+    if (cached !== undefined && now() - cached.at < IP_CACHE_TTL_MS)
+        return cached.args;
+    const ips = await candidateIpsFor(host, options.fetchImpl);
+    if (ips.length === 0)
+        return undefined;
+    const args = await racePinnedChannels(ips, host, probe);
+    if (args !== undefined)
+        cache.set(endpoint, { args, at: now() });
+    return args;
+}
+/**
+ * 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 function pinnedProbe(exec, cwd, endpoint, authArgs = []) {
+    return async (args) => {
+        const result = await exec('git', [...args, ...authArgs, 'ls-remote', '--heads', endpoint], {
+            cwd,
+            timeoutMs: IP_PROBE_TIMEOUT_MS,
+            env: { GIT_TERMINAL_PROMPT: '0' },
+        });
+        if (result.code !== 0)
+            throw new Error(result.errorMessage ?? result.stderr ?? 'pinned probe failed');
+    };
+}

package/lib/network-probe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Channel diagnostics for the settings UI: one read of the endpoint per
+ * channel, so a user whose network is failing can see WHICH path reaches
+ * GitHub instead of guessing.
+ *
+ * A probe is the same judgement the write path makes (0041/0042), run on
+ * demand: the channel is good only when `ls-remote` exits 0. A TCP-level
+ * "reachable" proves nothing — measured on 2026-11-03, 7 of 8 GitHub edges
+ * accepted a connection and still failed the read.
+ *
+ * @module git-worktree/network-probe
+ */
+import type { Exec } from './git.js';
+import type { NetworkChannelId, NetworkChannelReport } from './wire.js';
+/**
+ * Probe one channel by reading the endpoint through it.
+ *
+ * Failures are returned as data: a dead channel must not hide the next one,
+ * and the caller renders every report side by side.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param channel - which channel this argv stands for.
+ * @param url - endpoint to read.
+ * @param channelArgs - the channel's argv prefix (empty for direct).
+ * @param authArgs - credential argv for this host.
+ * @returns the channel's verdict, failures included.
+ */
+export declare function channelReport(exec: Exec, cwd: string, channel: NetworkChannelId, url: string, channelArgs: readonly string[], authArgs?: readonly string[]): Promise<NetworkChannelReport>;

package/lib/network-probe.js

@@ -0,0 +1,47 @@
+/**
+ * Channel diagnostics for the settings UI: one read of the endpoint per
+ * channel, so a user whose network is failing can see WHICH path reaches
+ * GitHub instead of guessing.
+ *
+ * A probe is the same judgement the write path makes (0041/0042), run on
+ * demand: the channel is good only when `ls-remote` exits 0. A TCP-level
+ * "reachable" proves nothing — measured on 2026-11-03, 7 of 8 GitHub edges
+ * accepted a connection and still failed the read.
+ *
+ * @module git-worktree/network-probe
+ */
+import { PROBE_TIMEOUT_MS } from './network.js';
+const DETAIL_LIMIT = 300;
+/**
+ * Keep a failure readable in a toast: the first non-empty line, capped.
+ * @param text - raw stderr or error message.
+ */
+function firstLine(text) {
+    const line = text.split(/\r?\n/).find(item => item.trim() !== '') ?? '';
+    return line.length > DETAIL_LIMIT ? `${line.slice(0, DETAIL_LIMIT)}…` : line;
+}
+/**
+ * Probe one channel by reading the endpoint through it.
+ *
+ * Failures are returned as data: a dead channel must not hide the next one,
+ * and the caller renders every report side by side.
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param channel - which channel this argv stands for.
+ * @param url - endpoint to read.
+ * @param channelArgs - the channel's argv prefix (empty for direct).
+ * @param authArgs - credential argv for this host.
+ * @returns the channel's verdict, failures included.
+ */
+export async function channelReport(exec, cwd, channel, url, channelArgs, authArgs = []) {
+    const started = Date.now();
+    const result = await exec('git', [...channelArgs, ...authArgs, 'ls-remote', '--heads', url], {
+        cwd,
+        timeoutMs: PROBE_TIMEOUT_MS,
+        env: { GIT_TERMINAL_PROMPT: '0' },
+    });
+    const elapsedMs = Date.now() - started;
+    if (result.code === 0)
+        return { channel, ok: true, elapsedMs };
+    return { channel, ok: false, elapsedMs, detail: firstLine(result.errorMessage ?? result.stderr) };
+}

package/lib/network-proxy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The third network channel: an explicit proxy, or the one Windows already
+ * has configured.
+ *
+ * Why the registry matters: git links libcurl, and libcurl does NOT read the
+ * WinINET/PAC settings that every browser on the machine honours. Measured on
+ * 2026-11-03 with a dead local proxy: `git ls-remote` failed with
+ * `Failed to connect to github.com:443 over proxy 127.0.0.1` the moment
+ * `-c http.proxy=…` was passed, i.e. git honours the argv and ignores the
+ * system setting entirely. A `gitport`-style tool bundles its own proxy; this
+ * plugin instead borrows the user's, and needs a way to find it.
+ */
+import type { Exec } from './git.js';
+import { proxyUrlError } from './normalize.js';
+/** A registry read is local and cheap; it must not become the slowest step. */
+export declare const SYSTEM_PROXY_TIMEOUT_MS = 3000;
+/** Re-exported so host callers keep one import site for the proxy rules. */
+export { proxyUrlError };
+/** The argv that routes one command through the proxy; `-c` precedes the subcommand. */
+export declare function proxyArgs(url: string): readonly string[];
+/**
+ * Parse the `ProxyServer` value WinINET stores, which is either `host:port` or
+ * a per-scheme list like `http=host:port;https=host:port`. The https entry
+ * wins; a plain value is used as is. Anything malformed answers undefined.
+ * @param raw - stdout of `reg query … /v ProxyServer`.
+ */
+export declare function parseProxyServer(raw: string): string | undefined;
+/**
+ * The system proxy Windows already has configured, when it is enabled and
+ * points somewhere usable; undefined otherwise (off Windows, disabled, empty,
+ * or unparseable). Read-only: nothing here changes the machine's settings.
+ * @param exec - executor seam.
+ * @param cwd - directory for the `reg` calls.
+ */
+export declare function systemProxyUrl(exec: Exec, cwd: string): Promise<string | undefined>;

package/lib/network-proxy.js

@@ -0,0 +1,55 @@
+import { proxyUrlError } from './normalize.js';
+/** A registry read is local and cheap; it must not become the slowest step. */
+export const SYSTEM_PROXY_TIMEOUT_MS = 3_000;
+const INTERNET_SETTINGS = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings';
+/** Re-exported so host callers keep one import site for the proxy rules. */
+export { proxyUrlError };
+/** The argv that routes one command through the proxy; `-c` precedes the subcommand. */
+export function proxyArgs(url) {
+    return ['-c', `http.proxy=${url}`];
+}
+/**
+ * Parse the `ProxyServer` value WinINET stores, which is either `host:port` or
+ * a per-scheme list like `http=host:port;https=host:port`. The https entry
+ * wins; a plain value is used as is. Anything malformed answers undefined.
+ * @param raw - stdout of `reg query … /v ProxyServer`.
+ */
+export function parseProxyServer(raw) {
+    const line = raw.split(/\r?\n/).find(item => /ProxyServer\s+REG_SZ/i.test(item));
+    if (line === undefined)
+        return undefined;
+    const value = line.replace(/^.*?ProxyServer\s+REG_SZ\s*/i, '').trim();
+    if (value === '')
+        return undefined;
+    if (!value.includes('='))
+        return value.includes(':') ? `http://${value}` : undefined;
+    const entries = value.split(';').map(item => item.trim()).filter(item => item !== '');
+    const https = entries.find(item => /^https=/i.test(item));
+    const chosen = https ?? entries.find(item => /^http=/i.test(item)) ?? entries[0];
+    const address = chosen?.replace(/^[a-z]+=/i, '').trim();
+    if (address === undefined || address === '' || !address.includes(':'))
+        return undefined;
+    const scheme = https === undefined ? 'http' : 'https';
+    return `${scheme}://${address}`;
+}
+/**
+ * The system proxy Windows already has configured, when it is enabled and
+ * points somewhere usable; undefined otherwise (off Windows, disabled, empty,
+ * or unparseable). Read-only: nothing here changes the machine's settings.
+ * @param exec - executor seam.
+ * @param cwd - directory for the `reg` calls.
+ */
+export async function systemProxyUrl(exec, cwd) {
+    if (process.platform !== 'win32')
+        return undefined;
+    const enabled = await exec('reg', ['query', INTERNET_SETTINGS, '/v', 'ProxyEnable'], { cwd, timeoutMs: SYSTEM_PROXY_TIMEOUT_MS });
+    if (enabled.code !== 0 || !/ProxyEnable\s+REG_DWORD\s+0x1\b/i.test(enabled.stdout))
+        return undefined;
+    const server = await exec('reg', ['query', INTERNET_SETTINGS, '/v', 'ProxyServer'], { cwd, timeoutMs: SYSTEM_PROXY_TIMEOUT_MS });
+    if (server.code !== 0)
+        return undefined;
+    const url = parseProxyServer(server.stdout);
+    if (url === undefined)
+        return undefined;
+    return proxyUrlError(url) === undefined ? url : undefined;
+}

package/lib/network-tool.js

@@ -18,7 +18,8 @@
  */
 import { isAbsolute } from 'node:path';
 import { basicUsername, createLocalCredentialStore, } from './credentials.js';
-import { childProcessExec, NETWORK_TIMEOUT_MS } from './git.js';
+import { childProcessExec } from './git.js';
+import { FETCH_TIMEOUT_MS } from './network.js';
 /** Model-facing tool name. */
 export const GIT_NETWORK_TOOL_NAME = 'git_network';
 /** The only git subcommands this tool will run. */
@@ -224,7 +225,7 @@ export function gitNetworkTool(deps) {
             // the same token serves this command and a plain shell `git push`.
             const result = await exec('git', request.args, {
                 cwd: request.repoPath,
-                timeoutMs: NETWORK_TIMEOUT_MS,
+                timeoutMs: FETCH_TIMEOUT_MS,
             });
             const stdout = cap(redactSecrets(result.stdout, entries));
             const stderrSource = result.stderr.trim() === '' && result.errorMessage !== undefined

package/lib/network.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Network policy for the host half: how long each remote operation may take,
+ * what a failed one actually means, and how a push that timed out is
+ * reconciled with the remote afterwards. Nothing here spawns a process — the
+ * budgets and the classifier are plain data so both the git wrapper and the
+ * routes can use them without a second seam.
+ */
+/**
+ * Budget for one reachability probe (`ls-remote`): a probe exists to fail
+ * FAST, so a dead host costs seconds, not the minutes a real transfer gets.
+ */
+export declare const PROBE_TIMEOUT_MS = 10000;
+/**
+ * Budget for the READ half of the network (fetch/update): a slow link with a
+ * real pack transfer outruns the local default, so this is deliberately wide.
+ */
+export declare const FETCH_TIMEOUT_MS = 300000;
+/**
+ * Budget for the WRITE half (push/push-tag). Wider than fetch: a push that
+ * is killed mid-transfer may already have updated the remote refs, and the
+ * caller pays for that ambiguity with a verification round-trip.
+ */
+export declare const PUSH_TIMEOUT_MS = 600000;
+/** Budget for the post-timeout reconciliation (`ls-remote` after a push). */
+export declare const VERIFY_TIMEOUT_MS = 10000;
+/** What a failed git network command most likely means. */
+export type GitFailureKind = 'timeout' | 'unreachable' | 'reset' | 'proxy' | 'tls' | 'credentials' | 'diverged' | 'protected' | 'unknown';
+/** Diagnosis of one failed remote command. */
+export interface GitFailure {
+    /** The shape of the failure; the UI may key wording off it later. */
+    kind: GitFailureKind;
+    /**
+     * Whether another network channel (a pinned IP, a proxy) could plausibly
+     * make the SAME command succeed. Credential, TLS, divergence and hook
+     * failures are about state, not reachability, so they never retry.
+     */
+    retryable: boolean;
+    /** One sentence the caller may append to the toast; undefined = say nothing. */
+    hint: string | undefined;
+}
+/**
+ * Classify one failed git network command from its diagnostic text.
+ * @param stderr - git's diagnostic (stderr, or the executor's fallback text).
+ * @param options - `timedOut` when the executor killed the process at its
+ * budget; that outranks the text, because a killed push carries no verdict.
+ * @returns the kind, whether another channel may help, and a one-line hint.
+ */
+export declare function classifyGitFailure(stderr: string, options?: {
+    timedOut?: boolean;
+}): GitFailure;
+/**
+ * Append a classified hint to git's own message, once: the raw diagnostic
+ * stays first so the user can still copy it into a bug report.
+ * @param message - the existing error text.
+ * @param failure - classifier output.
+ * @returns the message with the hint appended, unchanged when there is none.
+ */
+export declare function withHint(message: string, failure: GitFailure): string;