dsh-git-branch-manage 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 本文件记录 `dsh-git-branch-manage` 的重要变更。版本号遵循语义化版本。
 
+## [1.3.0] - 2026-11-04
+
+### 新增
+
+- **网络备用通道与代理配置**（决策 0042、0043）：直连发生可重试网络故障时，对 GitHub 地址使用运行时 DoH 查询和真实 Git 请求竞速选择可用 IP；支持显式配置 HTTP(S)/SOCKS 代理，并提供只读系统代理探测建议与「检测网络」诊断。
+- **网络操作状态诊断**（决策 0041）：按探测、读取、写入和超时核验分别设置预算；推送前探测远端，推送超时后核验远端 ref，并按失败类型给出建议。
+
+### 变更
+
+- **镜像仅作为读取加速**（决策 0044）：镜像 fetch/update 失败后自动恢复原始 URL 回直连，再按备用通道链尝试；推送不走镜像，避免将写入交给第三方。
+- SSH 远端不再进行无效的 HTTP 代理/IP 通道探测，错误信息改为提示可执行的 HTTPS 方案。
+- 加速前缀改为拼接完整 GitHub URL（决策 0040），并用真实 Git URL 解析与提取覆盖回归场景。
+
+### 修复
+
+- **CI 在非 Windows 上失败**（决策 0046）：系统代理探测的用例此前无条件假设 Windows 注册表，在 ubuntu-latest 上必然失败；现按平台分派，Windows 侧保留注册表行为覆盖，非 Windows 侧断言不读取注册表。
+
 ## [1.2.0] - 2026-11-02
 
 ### 新增

package/lib/client.js

@@ -65,8 +65,8 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* Normalize an accepted accelerate URL: trim, and append the trailing `/`
-		* the prefix concatenation requires (`https://gh-proxy.com/` + `o/r.git`
-		* must stay one valid URL). Callers pass the result to `url.<base>.insteadOf`.
+		* the prefix concatenation requires (`https://gh-proxy.com/` + the complete
+		* `https://github.com/o/r.git` URL). accelArgs builds the Git rewrite base.
 		* @param value - an accepted (non-empty, http(s), whitespace-free) URL.
 		* @returns the prefix ending in `/`.
 		*/
@@ -74,6 +74,37 @@ window.__ModuleLoader__.load({
 			const trimmed = value.trim();
 			return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
 		}
+		/** Schemes git's libcurl accepts for an HTTP(S) remote. */
+		const PROXY_SCHEMES = [
+			"http",
+			"https",
+			"socks5",
+			"socks5h"
+		];
+		/**
+		* Why this proxy value cannot be used, or undefined when it can.
+		*
+		* Credentials are rejected on purpose: the value is stored in the plugin
+		* config and passed as one `-c` argument, so `user:pass@` would be readable
+		* in the settings UI and in any diagnostics (0043).
+		* @param value - candidate proxy URL.
+		* @returns the user-facing reason, or undefined.
+		*/
+		function proxyUrlError(value) {
+			let url;
+			try {
+				url = new URL(value);
+			} catch {
+				return "must be an absolute proxy URL such as http://127.0.0.1:7890";
+			}
+			if (!PROXY_SCHEMES.includes(url.protocol.replace(":", ""))) return `scheme must be one of ${PROXY_SCHEMES.join(", ")}`;
+			if (url.hostname === "") return "must name a proxy host";
+			if (url.port === "") return "must name a proxy port";
+			const port = Number(url.port);
+			if (!Number.isInteger(port) || port < 1 || port > 65535) return "proxy port must be 1-65535";
+			if (url.username !== "" || url.password !== "") return "credentials in the proxy URL are not supported";
+			if (url.pathname !== "" && url.pathname !== "/" || url.search !== "" || url.hash !== "") return "must not carry a path, query, or fragment";
+		}
 		//#endregion
 		//#region src/wire.ts
 		/**
@@ -131,6 +162,8 @@ window.__ModuleLoader__.load({
 		const ROUTE_TAG = `${ROUTE_PREFIX}/tag`;
 		/** POST ROUTE_PREFIX/tag-push — push ONE existing local tag to its remote. */
 		const ROUTE_TAG_PUSH = `${ROUTE_PREFIX}/tag-push`;
+		/** POST ROUTE_PREFIX/network-probe — read the endpoint through every configured channel (diagnostics; no state change). */
+		const ROUTE_NETWORK_PROBE = `${ROUTE_PREFIX}/network-probe`;
 		/** POST ROUTE_PREFIX/credentials — the global per-host credentials, secrets
 		* masked (the stored secret never leaves the host). */
 		const ROUTE_CREDENTIALS = `${ROUTE_PREFIX}/credentials`;
@@ -223,6 +256,15 @@ window.__ModuleLoader__.load({
 			}
 		}
 		/**
+		* Probe every network channel (direct, proxy, pinned IP) against the
+		* repository's push URL; failures come back per channel rather than as one
+		* error, so the popover can show which route works right now (0043).
+		* @param repoPath - absolute directory inside the repository.
+		*/
+		function requestNetworkProbe(repoPath) {
+			return post(ROUTE_NETWORK_PROBE, { repoPath });
+		}
+		/**
 		* Create or reuse the worktree for a branch.
 		* @param repoPath - absolute directory inside the repository.
 		* @param branch - branch display name.
@@ -3558,6 +3600,8 @@ window.__ModuleLoader__.load({
 		/** The fields this form edits. */
 		const ACCEL_ENABLED_FIELD = "cnAccelerate";
 		const ACCEL_URL_FIELD = "cnAccelerateUrl";
+		/** The proxy channel's config key (0043); blank = no proxy channel. */
+		const NETWORK_PROXY_FIELD = "networkProxy";
 		/**
 		* Stages the cn-accelerate edits over the `dsh-git-branch` Host entry.
 		*
@@ -3571,6 +3615,7 @@ window.__ModuleLoader__.load({
 			listeners = /* @__PURE__ */ new Set();
 			enabledDraft;
 			urlDraft;
+			proxyDraft;
 			saving = false;
 			failed = false;
 			/**
@@ -3611,6 +3656,11 @@ window.__ModuleLoader__.load({
 						this.failed = false;
 						this.publish();
 					},
+					editNetworkProxy: (text) => {
+						this.proxyDraft = text;
+						this.failed = false;
+						this.publish();
+					},
 					restoreAccelDefault: () => {
 						this.urlDraft = ACCEL_DEFAULT_URL;
 						this.failed = false;
@@ -3618,9 +3668,10 @@ window.__ModuleLoader__.load({
 					},
 					saveAccel: () => this.save(),
 					discardAccel: () => {
-						if (this.enabledDraft === void 0 && this.urlDraft === void 0 && !this.failed) return;
+						if (this.enabledDraft === void 0 && this.urlDraft === void 0 && this.proxyDraft === void 0 && !this.failed) return;
 						this.enabledDraft = void 0;
 						this.urlDraft = void 0;
+						this.proxyDraft = void 0;
 						this.failed = false;
 						this.publish();
 					}
@@ -3632,6 +3683,11 @@ window.__ModuleLoader__.load({
 				const value = this.scope.getSnapshot().value?.[ACCEL_URL_FIELD];
 				return this.urlDraft ?? value ?? "https://gh-proxy.com/";
 			}
+			/** The proxy as the user sees it: the live draft, else the stored value. */
+			effectiveProxyText() {
+				const value = this.scope.getSnapshot().value?.[NETWORK_PROXY_FIELD];
+				return this.proxyDraft ?? (typeof value === "string" ? value : "");
+			}
 			/**
 			* Write the switch and the normalized URL TOGETHER, then re-seed from what
 			* the Host accepted. The URL is validated first — an unusable draft blocks
@@ -3640,11 +3696,14 @@ window.__ModuleLoader__.load({
 			* A save that did not land keeps its drafts so the user can correct them.
 			*/
 			async save() {
-				if (this.enabledDraft === void 0 && this.urlDraft === void 0 || this.saving) return;
+				if (this.enabledDraft === void 0 && this.urlDraft === void 0 && this.proxyDraft === void 0 || this.saving) return;
 				const urlText = this.effectiveUrlText();
 				if (accelerateUrlError(urlText) !== void 0) return;
+				const proxyText = this.effectiveProxyText().trim();
+				if (proxyText !== "" && proxyUrlError(proxyText) !== void 0) return;
 				const intendedEnabled = this.enabledDraft ?? this.scope.getSnapshot().value?.["cnAccelerate"] ?? false;
 				const intendedUrl = normalizeAccelerateUrl(urlText);
+				const writeProxy = this.proxyDraft !== void 0;
 				this.saving = true;
 				this.failed = false;
 				this.publish();
@@ -3652,14 +3711,16 @@ window.__ModuleLoader__.load({
 				try {
 					await this.scope.set(ACCEL_ENABLED_FIELD, intendedEnabled);
 					await this.scope.set(ACCEL_URL_FIELD, intendedUrl);
+					if (writeProxy) await this.scope.set(NETWORK_PROXY_FIELD, proxyText);
 					const user = this.userLayer();
-					if (user?.["cnAccelerate"] !== intendedEnabled || user?.["cnAccelerateUrl"] !== intendedUrl) landed = false;
+					if (user?.["cnAccelerate"] !== intendedEnabled || user?.["cnAccelerateUrl"] !== intendedUrl || writeProxy && (user?.["networkProxy"] ?? "") !== proxyText) landed = false;
 				} catch (_settingsWriteFailure) {
 					landed = false;
 				}
 				if (landed) {
 					this.enabledDraft = void 0;
 					this.urlDraft = void 0;
+					this.proxyDraft = void 0;
 				}
 				this.saving = false;
 				this.failed = !landed;
@@ -3675,17 +3736,22 @@ window.__ModuleLoader__.load({
 				const storedEnabled = snapshot.value?.["cnAccelerate"] ?? false;
 				const storedUrl = snapshot.value?.["cnAccelerateUrl"] ?? "https://gh-proxy.com/";
 				const urlText = this.effectiveUrlText();
+				const storedProxy = typeof snapshot.value?.["networkProxy"] === "string" ? snapshot.value[NETWORK_PROXY_FIELD] : "";
+				const proxyText = this.effectiveProxyText();
 				const enabledDirty = this.enabledDraft !== void 0 && this.enabledDraft !== storedEnabled;
 				const urlDirty = this.urlDraft !== void 0 && this.urlDraft !== storedUrl;
+				const proxyDirty = this.proxyDraft !== void 0 && this.proxyDraft !== storedProxy;
 				return {
 					available: snapshot.status === "ready",
 					writable: snapshot.writable,
 					enabled: this.enabledDraft ?? storedEnabled,
 					urlText,
-					dirty: enabledDirty || urlDirty,
+					dirty: enabledDirty || urlDirty || proxyDirty,
 					saving: this.saving,
 					failed: this.failed,
-					urlError: accelerateUrlError(urlText) ?? null
+					urlError: accelerateUrlError(urlText) ?? null,
+					proxyText,
+					proxyError: proxyText.trim() === "" ? null : proxyUrlError(proxyText.trim()) ?? null
 				};
 			}
 			/** Replace the snapshot reference and notify, only when the fact moved. */
@@ -4620,8 +4686,17 @@ window.__ModuleLoader__.load({
 		*
 		* @module git-worktree/client/panel/CnAcceleratePopover
 		*/
+		/** Channel id → its display name; the probe rows stay in host order. */
+		const CHANNEL_LABELS = {
+			direct: (t) => t("accel.channel.direct"),
+			proxy: (t) => t("accel.channel.proxy"),
+			ip: (t) => t("accel.channel.ip")
+		};
 		function CnAcceleratePopover(props) {
-			const { accel, t, pushToast, onClose } = props;
+			const { accel, t, pushToast, cwd, onClose } = props;
+			const [probe, setProbe] = (0, react.useState)(null);
+			const [probing, setProbing] = (0, react.useState)(false);
+			const [probeError, setProbeError] = (0, react.useState)(null);
 			const rootRef = (0, react.useRef)(null);
 			const state = (0, react.useSyncExternalStore)(accel.store.subscribe, accel.store.getSnapshot);
 			(0, react.useEffect)(() => {
@@ -4640,7 +4715,7 @@ window.__ModuleLoader__.load({
 			}, [onClose]);
 			const locked = state.saving || !state.writable;
 			const onSave = (0, react.useCallback)(() => {
-				if (state.saving || state.urlError !== null || !state.writable) return;
+				if (state.saving || state.urlError !== null || state.proxyError !== null || !state.writable) return;
 				(async () => {
 					await accel.saveAccel();
 					const after = accel.store.getSnapshot();
@@ -4660,6 +4735,25 @@ window.__ModuleLoader__.load({
 				state.writable,
 				t
 			]);
+			const onProbe = (0, react.useCallback)(() => {
+				if (cwd === void 0 || probing) return;
+				setProbing(true);
+				setProbeError(null);
+				(async () => {
+					const result = await requestNetworkProbe(cwd);
+					setProbing(false);
+					if (!result.ok) {
+						setProbe(null);
+						setProbeError(result.error);
+						return;
+					}
+					setProbe({
+						url: result.url,
+						channels: result.channels,
+						...result.systemProxy === void 0 ? {} : { systemProxy: result.systemProxy }
+					});
+				})();
+			}, [cwd, probing]);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: GitHistoryPanel_module_default.cnPop,
 				ref: rootRef,
@@ -4715,6 +4809,46 @@ window.__ModuleLoader__.load({
 						className: GitHistoryPanel_module_default.cnError,
 						children: state.urlError === "empty" ? t("accel.urlEmpty") : t("accel.urlInvalid")
 					}) : null,
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: GitHistoryPanel_module_default.cnFieldHead,
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: GitHistoryPanel_module_default.cnFieldLabel,
+							children: t("accel.proxyLabel")
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: GitHistoryPanel_module_default.cnLink,
+							disabled: locked || cwd === void 0 || probing,
+							onClick: onProbe,
+							children: probing ? t("accel.probing") : t("accel.probe")
+						})]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+						type: "text",
+						className: state.proxyError !== null ? GitHistoryPanel_module_default.cnInputBad : GitHistoryPanel_module_default.cnInput,
+						value: state.proxyText,
+						spellCheck: false,
+						disabled: locked,
+						placeholder: "http://127.0.0.1:7890",
+						"aria-invalid": state.proxyError !== null,
+						onChange: (event) => accel.editNetworkProxy(event.target.value)
+					}),
+					state.proxyError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: GitHistoryPanel_module_default.cnError,
+						children: t("accel.proxyInvalid")
+					}) : null,
+					probe !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: GitHistoryPanel_module_default.cnHint,
+						children: probe.channels.map((channel) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", { children: [
+							channel.ok ? "✓ " : "✗ ",
+							CHANNEL_LABELS[channel.channel](t),
+							` \u00b7 ${String(channel.elapsedMs)} ms`,
+							channel.detail === void 0 ? null : ` \u00b7 ${channel.detail}`
+						] }, channel.channel))
+					}) : null,
+					probeError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: GitHistoryPanel_module_default.cnError,
+						children: probeError
+					}) : null,
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: GitHistoryPanel_module_default.cnFooter,
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
@@ -4725,7 +4859,7 @@ window.__ModuleLoader__.load({
 						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 							type: "button",
 							className: GitHistoryPanel_module_default.cnSave,
-							disabled: state.saving || state.urlError !== null || !state.writable,
+							disabled: state.saving || state.urlError !== null || state.proxyError !== null || !state.writable,
 							onClick: onSave,
 							children: t("cardSave")
 						})]
@@ -7125,6 +7259,7 @@ window.__ModuleLoader__.load({
 										accel,
 										t,
 										pushToast,
+										cwd,
 										onClose: closeAccel
 									}) : null]
 								}),
@@ -7946,7 +8081,7 @@ window.__ModuleLoader__.load({
 				children: t("cardDescription")
 			});
 			const lockInput = !state.writable;
-			const lockActions = !state.dirty && !accelState.dirty || state.saving || accelState.saving || !state.keepWorktreesValid || accelState.urlError !== null;
+			const lockActions = !state.dirty && !accelState.dirty || state.saving || accelState.saving || !state.keepWorktreesValid || accelState.urlError !== null || accelState.proxyError !== null;
 			const legacyRootText = storage?.legacyRoot ?? (state.rootDir === "" ? "—" : state.rootDir);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: GitWorktreeCard_module_default.page,
@@ -8170,6 +8305,33 @@ window.__ModuleLoader__.load({
 							}) : null
 						]
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+						className: `${GitWorktreeCard_module_default.field} ${GitWorktreeCard_module_default.copyFilesRow}`,
+						htmlFor: "git-worktree-card-network-proxy",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: GitWorktreeCard_module_default.fieldLabel,
+								children: t("accel.proxyLabel")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+								id: "git-worktree-card-network-proxy",
+								className: GitWorktreeCard_module_default.accelInput,
+								type: "text",
+								spellCheck: false,
+								placeholder: "http://127.0.0.1:7890",
+								disabled: lockInput || accelState.saving,
+								value: accelState.proxyText,
+								onChange: (event) => {
+									props.editNetworkProxy(event.target.value);
+								}
+							}),
+							accelState.proxyError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: GitWorktreeCard_module_default.keepBad,
+								role: "alert",
+								children: t("accel.proxyInvalid")
+							}) : null
+						]
+					}),
 					history.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: `${GitWorktreeCard_module_default.field} ${GitWorktreeCard_module_default.historyRow}`,
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -8479,11 +8641,18 @@ window.__ModuleLoader__.load({
 			"panel.stUnmerged": "conflict",
 			"panel.cnAccelerate": "China acceleration",
 			"accel.enable": "Enable acceleration",
-			"accel.hint": "Accelerates https github.com remotes for fetch/update only; push is never proxied. The mirror sees repository content — do not use it for private or sensitive repositories.",
+			"accel.hint": "Enter a proxy prefix (e.g. https://gh-proxy.com/); fetch/update appends the complete GitHub URL. Push stays direct. The mirror sees repository content — do not use it for private or sensitive repositories.",
 			"accel.urlLabel": "Acceleration URL",
 			"accel.restoreDefault": "Restore default",
 			"accel.urlInvalid": "Enter an http(s):// URL",
 			"accel.urlEmpty": "Enter an acceleration URL",
+			"accel.proxyLabel": "Proxy (optional)",
+			"accel.proxyInvalid": "Enter an http(s)/socks5 proxy URL as host:port, without credentials",
+			"accel.probe": "Test network",
+			"accel.probing": "Testing...",
+			"accel.channel.direct": "Direct",
+			"accel.channel.proxy": "Proxy",
+			"accel.channel.ip": "Pinned IP",
 			"accel.saveFailed": "The change did not save. Try again.",
 			"accel.savedOn": "China acceleration enabled: {url}",
 			"accel.savedOff": "China acceleration disabled",
@@ -8769,11 +8938,18 @@ window.__ModuleLoader__.load({
 			"panel.stUnmerged": "冲突",
 			"panel.cnAccelerate": "国内加速",
 			"accel.enable": "启用加速",
-			"accel.hint": "仅加速 https 的 github.com 仓库地址，作用于提取/更新；推送不走加速。第三方加速站可看到仓库内容，请勿用于私有/敏感仓库。",
+			"accel.hint": "填写加速站前缀（如 https://gh-proxy.com/），提取/更新时会在其后拼接完整 GitHub 地址；推送不走加速。第三方加速站可看到仓库内容，请勿用于私有/敏感仓库。",
 			"accel.urlLabel": "加速地址",
 			"accel.restoreDefault": "恢复默认",
 			"accel.urlInvalid": "请输入以 http(s):// 开头的地址",
 			"accel.urlEmpty": "请输入加速地址",
+			"accel.proxyLabel": "代理（可选）",
+			"accel.proxyInvalid": "请输入 主机:端口 形式的 http(s)/socks5 代理地址，且不带账号密码",
+			"accel.probe": "检测网络",
+			"accel.probing": "检测中...",
+			"accel.channel.direct": "直连",
+			"accel.channel.proxy": "代理",
+			"accel.channel.ip": "固定 IP",
 			"accel.saveFailed": "保存未生效，请重试。",
 			"accel.savedOn": "已启用国内加速：{url}",
 			"accel.savedOff": "已关闭国内加速",

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;
 /**