dsh-git-branch-manage 1.2.0 → 1.3.1

package/lib/network.js

@@ -0,0 +1,128 @@
+/**
+ * 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 const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * 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 const FETCH_TIMEOUT_MS = 300_000;
+/**
+ * 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 const PUSH_TIMEOUT_MS = 600_000;
+/** Budget for the post-timeout reconciliation (`ls-remote` after a push). */
+export const VERIFY_TIMEOUT_MS = 10_000;
+/** Patterns are matched in order: the first hit wins. */
+const RULES = [
+    {
+        kind: 'proxy',
+        retryable: false,
+        hint: 'The configured proxy refused or failed the CONNECT tunnel; check the proxy address or turn it off.',
+        test: text => /over proxy/i.test(text)
+            || /Proxy CONNECT aborted/i.test(text)
+            || /CONNECT tunnel failed/i.test(text)
+            || /Received HTTP code 407/i.test(text),
+    },
+    {
+        kind: 'credentials',
+        retryable: false,
+        hint: 'Git could not read usable credentials; sign in for this host in the credentials panel, then retry.',
+        test: text => /terminal prompts disabled/i.test(text)
+            || /could not read Username/i.test(text)
+            || /Authentication failed/i.test(text)
+            || /Permission denied \(publickey/i.test(text)
+            || /HTTP 40[13]\b/.test(text),
+    },
+    {
+        kind: 'unreachable',
+        retryable: true,
+        hint: 'The host could not be reached; retry, then pin an IP or use a proxy.',
+        test: text => /Could not resolve host/i.test(text)
+            || /Failed to connect/i.test(text)
+            || /Could not connect to server/i.test(text)
+            || /Connection refused/i.test(text)
+            || /Network is unreachable/i.test(text),
+    },
+    {
+        kind: 'reset',
+        retryable: true,
+        hint: 'The connection was reset mid-transfer; retry, then pin an IP or use a proxy.',
+        test: text => /Connection was reset/i.test(text)
+            || /Recv failure/i.test(text)
+            || /RPC failed/i.test(text)
+            || /early EOF/i.test(text)
+            || /remote end hung up unexpectedly/i.test(text)
+            || /unexpected disconnect/i.test(text),
+    },
+    {
+        kind: 'tls',
+        retryable: false,
+        hint: 'TLS negotiation failed; the network is intercepting the connection or the certificate is untrusted.',
+        test: text => /SSL certificate problem/i.test(text)
+            || /schannel/i.test(text)
+            || /SSL_ERROR/i.test(text)
+            || /tlsv1 alert/i.test(text),
+    },
+    {
+        kind: 'diverged',
+        retryable: false,
+        hint: 'The remote has commits you do not have; pull or rebase before pushing (the plugin never forces).',
+        test: text => /non-fast-forward/i.test(text)
+            || /fetch first/i.test(text)
+            || /Not possible to fast-forward/i.test(text)
+            || /\[rejected\]/i.test(text),
+    },
+    {
+        kind: 'protected',
+        retryable: false,
+        hint: 'A server-side rule refused the update (protected branch or hook); resolve it on the host, not in the network.',
+        test: text => /protected branch/i.test(text)
+            || /hook declined/i.test(text)
+            || /pre-receive hook/i.test(text),
+    },
+];
+/**
+ * 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 function classifyGitFailure(stderr, options = {}) {
+    if (options.timedOut === true) {
+        return {
+            kind: 'timeout',
+            retryable: true,
+            hint: 'The command did not finish within its time budget; the remote may still be applying it — verify before retrying a push.',
+        };
+    }
+    const text = stderr.trim();
+    for (const rule of RULES) {
+        if (rule.test(text))
+            return { kind: rule.kind, retryable: rule.retryable, hint: rule.hint };
+    }
+    return { kind: 'unknown', retryable: false, hint: undefined };
+}
+/**
+ * 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 function withHint(message, failure) {
+    if (failure.hint === undefined || message.includes(failure.hint))
+        return message;
+    return `${message}\n\n${failure.hint}`;
+}

package/lib/normalize.d.ts

@@ -75,8 +75,8 @@ export type AccelerateUrlIssue = 'empty' | 'invalid';
 export declare function accelerateUrlError(value: string): AccelerateUrlIssue | undefined;
 /**
  * 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 `/`.
  */
@@ -105,3 +105,15 @@ export type RemoteUrlIssue = 'empty' | 'whitespace' | 'invalid';
  * @returns the issue kind, or undefined when acceptable.
  */
 export declare function remoteUrlIssue(url: string): RemoteUrlIssue | undefined;
+/** Schemes git's libcurl accepts for an HTTP(S) remote. */
+export declare const PROXY_SCHEMES: readonly string[];
+/**
+ * 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.
+ */
+export declare function proxyUrlError(value: string): string | undefined;

package/lib/normalize.js

@@ -117,8 +117,8 @@ export function accelerateUrlError(value) {
 }
 /**
  * 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 `/`.
  */
@@ -173,3 +173,39 @@ export function remoteUrlIssue(url) {
         return undefined;
     return 'invalid';
 }
+/** Schemes git's libcurl accepts for an HTTP(S) remote. */
+export 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.
+ */
+export 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 > 65_535)
+        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';
+    }
+    return undefined;
+}

package/lib/routes.d.ts

@@ -6,13 +6,21 @@ import { type CopyFilesSeams } from './copy-files.js';
 import { type CredentialStore } from './credentials.js';
 import type { CredentialService } from './credential-service.js';
 import { type LocalImportReport } from './local-import.js';
-import { type DirExists, type ExcludeSeams, type Exec } from './git.js';
-import type { AiCommitMessageResult, ChangesResult, CommitFilesResult, CommitResult, CreateBranchResult, CreateTagResult, CreateWorktreeResult, CredentialOAuthPollResult, CredentialOAuthStartResult, CredentialImportResult, CredentialsResult, EnsureDirectoryResult, FetchResult, GroupWorkspacesResult, InspectWorktreeResult, LogResult, PathExistsResult, PurgeDirectoryResult, PushTagResult, RemoveWorktreeResult, RemotesResult, RepoStatus, RouteError, StageResult, SwitchResult, UpdateResult, WorktreesAllResult } from './wire.js';
+import { type ChannelProvider, type DirExists, type ExcludeSeams, type Exec } from './git.js';
+import type { NetworkProbeResult, AiCommitMessageResult, ChangesResult, CommitFilesResult, CommitResult, CreateBranchResult, CreateTagResult, CreateWorktreeResult, CredentialOAuthPollResult, CredentialOAuthStartResult, CredentialImportResult, CredentialsResult, EnsureDirectoryResult, FetchResult, GroupWorkspacesResult, InspectWorktreeResult, LogResult, PathExistsResult, PurgeDirectoryResult, PushTagResult, RemoveWorktreeResult, RemotesResult, RepoStatus, RouteError, StageResult, SwitchResult, UpdateResult, WorktreesAllResult } from './wire.js';
 /** Everything the handlers need from the host half. */
 export interface RouteDeps {
     exec: Exec;
+    /** Fallback channels for a network command, in priority order: the
+     * explicit proxy first, then the IP-optimized channel (absent = direct only; tests leave
+     * it out so no real lookup, race, or proxy argv ever runs). */
+    networkChannels?: (exec: Exec, cwd: string, authArgs: readonly string[]) => readonly ChannelProvider[];
     /** The settings-resolved rootDir (absent/blank = the default location). */
     sectionRootDir: () => string | undefined;
+    /** Explicit proxy URL for the proxy channel; absent/blank = none. */
+    sectionNetworkProxy?: () => string | undefined;
+    /** The proxy Windows itself has enabled (read-only WinINET probe); absent = not looked up. */
+    sectionSystemProxy?: () => Promise<string | undefined>;
     /** Whether a worktree creation syncs the remotes first (absent = off). */
     sectionFetchBeforeCreate: () => boolean | undefined;
     /** Post-create configuration files to copy when .worktreeinclude is absent. */
@@ -68,7 +76,7 @@ export declare function fsMkdirRecursive(path: string): Promise<void>;
 /** One route outcome: HTTP status plus the JSON body. */
 export interface RouteOutcome {
     status: number;
-    body: RepoStatus | CreateWorktreeResult | SwitchResult | CreateBranchResult | FetchResult | UpdateResult | GroupWorkspacesResult | InspectWorktreeResult | RemoveWorktreeResult | PathExistsResult | EnsureDirectoryResult | WorktreesAllResult | PurgeDirectoryResult | ChangesResult | StageResult | CommitResult | LogResult | CommitFilesResult | CreateTagResult | PushTagResult | AiCommitMessageResult | CredentialsResult | CredentialOAuthStartResult | CredentialOAuthPollResult | CredentialImportResult | RemotesResult | RouteError;
+    body: RepoStatus | CreateWorktreeResult | SwitchResult | CreateBranchResult | FetchResult | UpdateResult | GroupWorkspacesResult | InspectWorktreeResult | RemoveWorktreeResult | PathExistsResult | EnsureDirectoryResult | WorktreesAllResult | PurgeDirectoryResult | ChangesResult | StageResult | CommitResult | LogResult | CommitFilesResult | CreateTagResult | PushTagResult | AiCommitMessageResult | CredentialsResult | CredentialOAuthStartResult | CredentialOAuthPollResult | CredentialImportResult | RemotesResult | NetworkProbeResult | RouteError;
 }
 /**
  * POST /group — git belonging facts for a batch of workspace directories.
@@ -440,3 +448,16 @@ export declare function handleRemotes(deps: RouteDeps, body: unknown): Promise<R
  * @param body - parsed request body: `{ repoPath, action, name, url? }`.
  */
 export declare function handleRemote(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;
+/**
+ * Report which network channel can read the repository's endpoint right now.
+ *
+ * Diagnostics only: nothing here writes to git or to the config. Each
+ * channel gets its own budget (PROBE_TIMEOUT_MS), so a dead proxy costs one
+ * timeout and the answer still names the channels that work. The system
+ * proxy is reported when the plugin has none of its own — git ignores
+ * WinINET, so a value here is a suggestion the user must opt into (0043).
+ * @param deps - route dependencies (exec, channel providers, config readers).
+ * @param body - `{ repoPath }`.
+ * @returns one report per channel, in the order the write path would try them.
+ */
+export declare function handleNetworkProbe(deps: RouteDeps, body: unknown): Promise<RouteOutcome>;

package/lib/routes.js

@@ -7,7 +7,9 @@ import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { runPostCreateCopy } from './copy-files.js';
 import { credentialHostIssue, credentialSecretIssue, credentialUsernameIssue, createLocalCredentialStore, maskSecret, normalizeCredentialHost, removeCredential, sortCredentials, upsertCredential } from './credentials.js';
 import { importLocalCredentials as runLocalImport } from './local-import.js';
-import { appendWorktreeExclude, fsExcludeSeams, GitError, addRemote, addWorktree, addWorktreeCutout, collectAiDiff, commitFiles, commitIndex, createBranch, createTag, cutoutBranchName, deleteBranch, fetchAll, fsDirExists, inspectWorktree, isAbsoluteDir, isStageablePath, listRemotes, listTagNames, logHistory, probeRepo, probeWorkspaceGit, pushTag, removeRemote, removeWorktree, renameBranch, resolveBranch, resolvePushRemote, pushBranch, setRemoteUrl, stagePaths, switchBranch, updateBranch, workingChanges } from './git.js';
+import { appendWorktreeExclude, fsExcludeSeams, GitError, addRemote, addWorktree, addWorktreeCutout, collectAiDiff, commitFiles, commitIndex, createBranch, createTag, cutoutBranchName, deleteBranch, fetchAll, fsDirExists, inspectWorktree, isAbsoluteDir, isStageablePath, listRemotes, listTagNames, logHistory, probeRepo, probeWorkspaceGit, pushTag, removeRemote, removeWorktree, renameBranch, resolveBranch, resolvePushRemote, resolvePushTarget, pushBranch, setRemoteUrl, stagePaths, switchBranch, updateBranch, workingChanges } from './git.js';
+import { classifyGitFailure, withHint } from './network.js';
+import { channelReport } from './network-probe.js';
 import { ACCEL_DEFAULT_URL, accelerateUrlError, isAbsoluteConfigPath, normalizeAccelerateUrl, remoteNameIssue, remoteUrlIssue, sanitizeBranchDir } from './normalize.js';
 import { deviceFlowClientId, isDeviceFlowHost, pollDeviceFlow, startDeviceFlow } from './oauth.js';
 import { resolveRootDir } from './settings.js';
@@ -54,6 +56,11 @@ function accelPrefix(deps) {
     const url = deps.sectionCnAccelerateUrl?.() ?? ACCEL_DEFAULT_URL;
     return accelerateUrlError(url) === undefined ? normalizeAccelerateUrl(url) : undefined;
 }
+/** The fallback chain for one command: the host's providers, or none at all. */
+function networkOptions(deps, cwd, authArgs) {
+    const channels = deps.networkChannels?.(deps.exec, cwd, authArgs) ?? [];
+    return channels.length === 0 ? {} : { fallbackChannels: channels };
+}
 /** The global credential store: the service's shared instance (decision 0037),
  * else the wired store, else the local `~/.git-credentials`-backed store. */
 function credentialStore(deps) {
@@ -313,6 +320,10 @@ export async function handlePurgeDirectory(deps, body) {
 }
 /** GitError to outcome: usage-shaped failures are 400, the rest 500. */
 function gitFailure(error) {
+    // Every git failure the routes surface passes through one classifier so
+    // the toast explains WHAT broke (host, credentials, divergence) instead of
+    // repeating git's raw text alone.
+    const failure = classifyGitFailure(error.stderr, { timedOut: error.timedOut });
     const usage = error.stderr.includes('usage:')
         || error.stderr.includes('fatal: invalid')
         // A user-typed branch name git refuses (`'bad..name' is not a valid
@@ -347,7 +358,7 @@ function gitFailure(error) {
         // (a stale sidebar row racing a terminal-side removal).
         || error.stderr.includes('cannot remove the main worktree')
         || error.stderr.includes('is not a registered worktree');
-    return fail(usage ? 400 : 500, error.message);
+    return fail(usage ? 400 : 500, withHint(error.message, failure));
 }
 /**
  * GET /status 鈥?repository facts for one directory.
@@ -462,7 +473,10 @@ export async function handleCreateWorktree(deps, body) {
             const resolved = await resolveBranch(deps.exec, facts.repoRoot, branch);
             if (resolved?.remote !== undefined) {
                 try {
-                    await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps), await authArgsFor(deps));
+                    {
+                        const authArgs = await authArgsFor(deps);
+                        await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps), authArgs, networkOptions(deps, facts.repoRoot, authArgs));
+                    }
                 }
                 catch (error) {
                     fetchWarning = error instanceof GitError ? error.stderr.trim() : error instanceof Error ? error.message : String(error);
@@ -697,7 +711,10 @@ export async function handleFetch(deps, body) {
         const facts = await probeRepo(deps.exec, repoPath, deps.dirExists);
         if (facts === undefined)
             return fail(400, `"${repoPath}" is not inside a git repository`);
-        await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps), await authArgsFor(deps));
+        {
+            const authArgs = await authArgsFor(deps);
+            await fetchAll(deps.exec, facts.repoRoot, accelPrefix(deps), authArgs, networkOptions(deps, facts.repoRoot, authArgs));
+        }
         const result = { remote: 'all' };
         return { status: 200, body: result };
     }
@@ -760,8 +777,9 @@ export async function handlePush(deps, body) {
             return fail(400, `"${repoPath}" is not inside a git repository`);
         // The session's OWN worktree, not the main checkout: in a linked-worktree
         // session "push current branch" means the branch that worktree holds.
-        const outcome = await pushBranch(deps.exec, facts.toplevel, await authArgsFor(deps));
-        const result = { branch: outcome.branch, pushed: outcome.pushed };
+        const authArgs = await authArgsFor(deps);
+        const outcome = await pushBranch(deps.exec, facts.toplevel, authArgs, networkOptions(deps, facts.toplevel, authArgs));
+        const result = { branch: outcome.branch, pushed: outcome.pushed, ...(outcome.note === undefined ? {} : { note: outcome.note }) };
         return { status: 200, body: result };
     }
     catch (error) {
@@ -1192,8 +1210,9 @@ export async function handlePushTag(deps, body) {
         const choice = await resolvePushRemote(deps.exec, facts.toplevel);
         if (!choice.ok)
             return fail(400, choice.message);
-        const result = await pushTag(deps.exec, facts.toplevel, name, choice.remote, await authArgsFor(deps));
-        const body = result;
+        const authArgs = await authArgsFor(deps);
+        const result = await pushTag(deps.exec, facts.toplevel, name, choice.remote, authArgs, networkOptions(deps, facts.toplevel, authArgs));
+        const body = { ...result, ...(result.note === undefined ? {} : { note: result.note }) };
         return { status: 200, body };
     }
     catch (error) {
@@ -1671,3 +1690,73 @@ export async function handleRemote(deps, body) {
         return fail(500, error instanceof Error ? error.message : String(error));
     }
 }
+/**
+ * Report which network channel can read the repository's endpoint right now.
+ *
+ * Diagnostics only: nothing here writes to git or to the config. Each
+ * channel gets its own budget (PROBE_TIMEOUT_MS), so a dead proxy costs one
+ * timeout and the answer still names the channels that work. The system
+ * proxy is reported when the plugin has none of its own — git ignores
+ * WinINET, so a value here is a suggestion the user must opt into (0043).
+ * @param deps - route dependencies (exec, channel providers, config readers).
+ * @param body - `{ repoPath }`.
+ * @returns one report per channel, in the order the write path would try them.
+ */
+export async function handleNetworkProbe(deps, body) {
+    const parsed = readBody(body, ['repoPath']);
+    if (isOutcome(parsed))
+        return parsed;
+    const { repoPath } = parsed;
+    if (!isAbsoluteDir(repoPath))
+        return fail(400, '"repoPath" must be an absolute directory');
+    try {
+        const facts = await probeRepo(deps.exec, repoPath, deps.dirExists);
+        if (facts === undefined)
+            return fail(400, JSON.stringify(repoPath) + " is not inside a git repository");
+        const authArgs = await authArgsFor(deps);
+        const url = await probeEndpoint(deps.exec, facts.repoRoot, authArgs);
+        if (url === undefined)
+            return fail(400, '"repoPath" has no remote to probe');
+        const channels = [await channelReport(deps.exec, facts.repoRoot, 'direct', url, [], authArgs)];
+        for (const provider of deps.networkChannels?.(deps.exec, facts.repoRoot, authArgs) ?? []) {
+            const argv = await provider(url);
+            if (argv === undefined || argv.length === 0)
+                continue;
+            const channel = argv.some(item => item.startsWith('http.proxy=')) ? 'proxy' : 'ip';
+            if (channels.some(report => report.channel === channel))
+                continue;
+            channels.push(await channelReport(deps.exec, facts.repoRoot, channel, url, argv, authArgs));
+        }
+        const systemProxy = await deps.sectionSystemProxy?.();
+        const result = {
+            url,
+            channels,
+            ...(systemProxy === undefined || systemProxy === '' ? {} : { systemProxy }),
+        };
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        if (error instanceof GitError)
+            return gitFailure(error);
+        throw error;
+    }
+}
+/**
+ * The endpoint a probe should read: the upstream's push URL when the branch
+ * tracks one, otherwise the push URL of `origin` (or the first remote).
+ * @param exec - executor seam.
+ * @param cwd - any directory inside the repository.
+ * @param authArgs - credential argv for the host.
+ * @returns the URL, or undefined when the repository has no remote at all.
+ */
+async function probeEndpoint(exec, cwd, authArgs) {
+    const target = await resolvePushTarget(exec, cwd, authArgs);
+    if (target?.url !== undefined && target.url !== '')
+        return target.url;
+    const remotes = await listRemotes(exec, cwd);
+    const chosen = remotes.find(remote => remote.name === 'origin') ?? remotes[0];
+    if (chosen === undefined)
+        return undefined;
+    const url = chosen.pushUrl !== '' ? chosen.pushUrl : chosen.fetchUrl;
+    return url === '' ? undefined : url;
+}

package/lib/wire.d.ts

@@ -57,6 +57,8 @@ export declare const ROUTE_COMMIT_FILES = "/plugin/git-worktree/commit-files";
 export declare const ROUTE_TAG = "/plugin/git-worktree/tag";
 /** POST ROUTE_PREFIX/tag-push — push ONE existing local tag to its remote. */
 export declare const ROUTE_TAG_PUSH = "/plugin/git-worktree/tag-push";
+/** POST ROUTE_PREFIX/network-probe — read the endpoint through every configured channel (diagnostics; no state change). */
+export declare const ROUTE_NETWORK_PROBE = "/plugin/git-worktree/network-probe";
 /** POST ROUTE_PREFIX/credentials — the global per-host credentials, secrets
  * masked (the stored secret never leaves the host). */
 export declare const ROUTE_CREDENTIALS = "/plugin/git-worktree/credentials";
@@ -270,6 +272,9 @@ export interface PushResult {
     branch: string;
     /** False when the upstream already contained the branch (nothing moved). */
     pushed: boolean;
+    /** Set when the push timed out but the remote ref already matched HEAD:
+     * the push landed and only the confirmation was lost. */
+    note?: 'timed-out-but-landed';
 }
 /** Error envelope every non-2xx response carries. */
 export interface RouteError {
@@ -546,6 +551,9 @@ export interface PushTagResult {
     /** False when the remote already carried this exact tag object — nothing
      * was sent. True once the push command actually ran. */
     pushed: boolean;
+    /** Set when the push timed out but the remote tag already named the local
+     * object: the tag landed and only the confirmation was lost. */
+    note?: 'timed-out-but-landed';
 }
 /** One file row of POST commit-files. */
 export interface CommitFileEntry {
@@ -731,3 +739,30 @@ export interface RemoteMutationBody {
 }
 /** POST remote response body: the repository's remotes after the change. */
 export type RemoteMutationResult = RemotesResult;
+/** The network channels a probe can report, in the order they are tried. */
+export type NetworkChannelId = 'direct' | 'proxy' | 'ip';
+/** One channel's verdict from ROUTE_NETWORK_PROBE. */
+export interface NetworkChannelReport {
+    /** Which channel was attempted. */
+    channel: NetworkChannelId;
+    /** Whether an ls-remote answered within the probe budget. */
+    ok: boolean;
+    /** Wall-clock milliseconds the attempt took. */
+    elapsedMs: number;
+    /** Why it failed, trimmed for display; absent when ok. */
+    detail?: string;
+}
+/** POST network-probe request body. */
+export interface NetworkProbeBody {
+    /** Any directory inside the repository. */
+    repoPath: string;
+}
+/** POST network-probe response body: one verdict per configured channel. */
+export interface NetworkProbeResult {
+    /** The endpoint that was probed (the push URL when the branch has one). */
+    url: string;
+    /** One entry per configured channel. */
+    channels: NetworkChannelReport[];
+    /** The WinINET proxy when one is enabled but not configured in the plugin. */
+    systemProxy?: string;
+}

package/lib/wire.js

@@ -57,6 +57,8 @@ export const ROUTE_COMMIT_FILES = `${ROUTE_PREFIX}/commit-files`;
 export const ROUTE_TAG = `${ROUTE_PREFIX}/tag`;
 /** POST ROUTE_PREFIX/tag-push — push ONE existing local tag to its remote. */
 export const ROUTE_TAG_PUSH = `${ROUTE_PREFIX}/tag-push`;
+/** POST ROUTE_PREFIX/network-probe — read the endpoint through every configured channel (diagnostics; no state change). */
+export 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). */
 export const ROUTE_CREDENTIALS = `${ROUTE_PREFIX}/credentials`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-git-branch-manage",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "提供 git 分支与 worktree 管理：输入框工具栏显示当前分支、可原地切换；支持 IDEA 风格分支选择器、远程分支检出、右键操作菜单（新建/重命名/删除/复制）、推送与更新当前分支，以及把分支隔离到独立 worktree 工作区，并管理其创建与删除。",
   "keywords": [
     "dsh",