dsh-git-branch-manage 1.1.0 → 1.3.0

package/lib/git.d.ts

@@ -11,6 +11,8 @@ export interface ExecResult {
     stderr: string;
     /** Node-level failure text when the process never produced stderr. */
     errorMessage?: string;
+    /** True when the executor killed the process at its timeout budget. */
+    timedOut?: boolean;
 }
 /**
  * Process executor seam. Runs `file args` with cwd set, captures output as
@@ -19,14 +21,25 @@ export interface ExecResult {
 export type Exec = (file: string, args: readonly string[], options: {
     cwd: string;
     timeoutMs?: number;
+    env?: Record<string, string | undefined>;
 }) => Promise<ExecResult>;
 /** Failure of one git invocation: non-zero exit with the stderr text. */
 export declare class GitError extends Error {
     readonly args: readonly string[];
     readonly code: number;
     readonly stderr: string;
-    constructor(args: readonly string[], code: number, stderr: string);
+    /** True when the executor killed the command at its budget — no verdict. */
+    readonly timedOut: boolean;
+    constructor(args: readonly string[], code: number, stderr: string, 
+    /** True when the executor killed the command at its budget — no verdict. */
+    timedOut?: boolean);
 }
+/**
+ * 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 declare function isSshEndpoint(url: string | undefined): boolean;
 /** Facts the status route assembles: branches, worktrees, repo identity. */
 export interface RepoFacts {
     /** Absolute main worktree path (`dirname` of `--git-common-dir`, not the
@@ -58,15 +71,15 @@ export interface RepoFacts {
 /** Default hard timeout for one git call: generous for every LOCAL
  * operation (status/log/commit/worktree) while still bounding hangs. */
 export declare const GIT_TIMEOUT_MS = 20000;
-/** 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 declare const NETWORK_TIMEOUT_MS = 120000;
+/** 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 declare function childProcessExec(file: string, args: readonly string[], options: {
     cwd: string;
     timeoutMs?: number;
+    env?: Record<string, string | undefined>;
 }): Promise<ExecResult>;
 /** Directory-existence seam over the parsed worktree registrations. */
 export type DirExists = (path: string) => boolean;
@@ -256,7 +269,7 @@ export declare function accelArgs(prefix: string | undefined): readonly string[]
  * @param authArgs - optional per-host credential `-c` pairs (see
  * `credentials.ts`); prepended before the subcommand like the accel rewrite.
  */
-export declare function fetchAll(exec: Exec, repoRoot: string, accelPrefix?: string, authArgs?: readonly string[]): Promise<void>;
+export declare function fetchAll(exec: Exec, repoRoot: string, accelPrefix?: string, authArgs?: readonly string[], options?: NetworkOptions): Promise<void>;
 /** Outcome of {@link updateBranch}: the branch touched and whether it moved. */
 export interface UpdateOutcome {
     branch: string;
@@ -283,7 +296,62 @@ export declare function updateBranch(exec: Exec, cwd: string, accelPrefix?: stri
 export interface PushOutcome {
     branch: string;
     pushed: boolean;
+    /** Set when the push ran out of time but the remote ref already matches
+     * the local HEAD — the push landed, the connection just did not say so. */
+    note?: 'timed-out-but-landed';
+}
+/** The endpoint a write would use, resolved so it can be probed first. */
+export interface PushTarget {
+    /** Remote name taken from the upstream (`origin`). */
+    remote: string;
+    /** The URL `git push` uses (a separate `pushurl` is respected); absent
+     * when git could not name one, in which case the remote name is the
+     * endpoint and the probe resolves it the same way push does. */
+    url?: string;
+}
+/** Per-command routing for a network command (a proxy's `-c` pairs). */
+export interface NetworkOptions {
+    /** Argv placed before the subcommand that selects a network channel;
+     * empty/absent = the direct connection. */
+    channelArgs?: readonly string[];
+    /**
+     * Consulted ONLY after the direct channel's probe failed in a way another
+     * channel could plausibly fix (unreachable/reset/timeout), in order, until
+     * one of them answers argv that ALSO passes its own probe. Each provider
+     * answers undefined when it does not apply (a mirror URL, an unconfigured
+     * proxy) — that is a skip, not a failure. Empty/absent = direct only.
+     */
+    fallbackChannels?: readonly ChannelProvider[];
 }
+/** Answers the argv for one replacement channel, or undefined when it does not apply. */
+export type ChannelProvider = (endpoint: string) => Promise<readonly string[] | undefined>;
+/**
+ * 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 declare function resolvePushTarget(exec: Exec, cwd: string, authArgs?: readonly string[]): Promise<PushTarget | undefined>;
+/**
+ * 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 declare function probePushTarget(exec: Exec, cwd: string, target: PushTarget, options?: NetworkOptions, authArgs?: readonly string[]): Promise<void>;
 /**
  * Push the branch checked out by `cwd` to its upstream (`@{u}`) — the
  * counterpart of {@link updateBranch}. Deliberately a bare `git push`: the
@@ -298,11 +366,13 @@ export interface PushOutcome {
  * 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 declare function pushBranch(exec: Exec, cwd: string, authArgs?: readonly string[]): Promise<PushOutcome>;
+export declare function pushBranch(exec: Exec, cwd: string, authArgs?: readonly string[], options?: NetworkOptions): Promise<PushOutcome>;
 /** Every LOCAL tag name of the repository, in git's own sort order. */
 export declare function listTagNames(exec: Exec, cwd: string): Promise<string[]>;
 /** Where a one-off push should go, or why no remote could be picked. */
@@ -328,6 +398,9 @@ export interface TagPushOutcome {
     tag: string;
     remote: string;
     pushed: boolean;
+    /** Set when the push timed out but the remote tag already names the local
+     * object — landed, with the connection gone before it could say so. */
+    note?: 'timed-out-but-landed';
 }
 /**
  * Push ONE existing local tag to `remote` (`git push <remote>
@@ -353,7 +426,7 @@ export interface TagPushOutcome {
  * @param remote - the remote to publish to (see {@link resolvePushRemote}).
  * @returns the tag, the remote, and whether the push had to run.
  */
-export declare function pushTag(exec: Exec, cwd: string, name: string, remote: string, authArgs?: readonly string[]): Promise<TagPushOutcome>;
+export declare function pushTag(exec: Exec, cwd: string, name: string, remote: string, authArgs?: readonly string[], options?: NetworkOptions): Promise<TagPushOutcome>;
 /** Guard for route inputs: a non-empty absolute directory path. */
 export declare function isAbsoluteDir(value: string): boolean;
 /**

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