@davesheffer/hunch 1.45.1 → 1.46.0

package/dist/extractors/git.js

@@ -7,6 +7,7 @@ import { isAbsolute, resolve, join, basename, dirname, relative, sep, posix } fr
 import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
+import { boundedExecFileSync } from "../core/boundedSpawn.js";
 import { writeFileAtomic } from "../core/io.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
 import { createRepoFileReader } from "../core/safeRepoFile.js";
@@ -154,10 +155,11 @@ function headShaWithEnv(cwd, env) {
 function gitSafeWithEnv(args, cwd, env) {
     try {
         return execFileSync("git", ["-C", cwd, ...args], {
-            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: pullLocalGitTimeoutMs(),
         }).trim();
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return "";
     }
 }
@@ -223,6 +225,60 @@ function clearStrandedIndexLock(repoDir, env, sinceMs, error) {
         return false; // no lock present, or git itself unavailable — nothing to heal
     }
 }
+/** Why the last pull-path git call failed (issue #482). The bounded helpers swallow
+ *  their errors into booleans; they also note the error here so mergeRemote can attach
+ *  it to the failing step. Synchronous code only, so a module slot is race-free. */
+let lastPullGitError;
+function notePullGitError(error) { lastPullGitError = error; }
+/** Captured git stderr can echo a remote URL with embedded credentials; strip the
+ *  userinfo (`://user:pass@`, `://token@`) before it is stored or printed. */
+export function redactUrlUserinfo(text) {
+    return text.replace(/:\/\/[^\s/@'"]+@/g, "://***@");
+}
+function pullFailureDetail(step, error) {
+    const detail = { step };
+    if (!error || typeof error !== "object")
+        return detail;
+    const err = error;
+    if (typeof err.code === "string" && err.code)
+        detail.code = err.code;
+    else if (typeof err.signal === "string" && err.signal)
+        detail.code = err.signal;
+    else if (typeof err.status === "number")
+        detail.code = `exit ${err.status}`;
+    const stderr = (typeof err.stderr === "string" ? err.stderr : Buffer.isBuffer(err.stderr) ? err.stderr.toString("utf8") : "").trim();
+    if (stderr)
+        detail.stderr = redactUrlUserinfo(stderr).slice(-400);
+    return detail;
+}
+/** One-line rendering for logs and refusal messages: `step: fetch, ETIMEDOUT, fatal: ...`. */
+export function describePullFailure(detail) {
+    if (!detail)
+        return "";
+    const firstLine = detail.stderr?.split(/\r?\n/).find((line) => line.trim())?.trim();
+    return [`step: ${detail.step}`, detail.code, firstLine].filter(Boolean).join(", ");
+}
+/** HUNCH_PULL_GIT_TIMEOUT_MS: per-process override of the read-side pull's DEFAULT
+ *  remote budget (ls-remote/fetch/merge) for slow runners — a caller's explicit
+ *  timeoutMs still wins; ignored unless a positive integer. */
+export function pullGitTimeoutOverride() {
+    const raw = process.env.HUNCH_PULL_GIT_TIMEOUT_MS?.trim();
+    if (!raw || !/^\d+$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    return value > 0 ? Math.min(600_000, value) : undefined;
+}
+/** Remote budget for one read-side pull: an explicit caller budget always wins;
+ *  HUNCH_PULL_GIT_TIMEOUT_MS only replaces the 5s default. */
+export function pullRemoteTimeoutMs(callerMs) {
+    return callerMs ?? pullGitTimeoutOverride() ?? DEFAULT_READ_REMOTE_TIMEOUT_MS;
+}
+/** Budget for the bounded local git helpers (status, rev-parse, ls-tree): 2s by
+ *  default, scaled with HUNCH_PULL_GIT_TIMEOUT_MS to max(2s, override / 2.5). */
+export function pullLocalGitTimeoutMs() {
+    const override = pullGitTimeoutOverride();
+    return override === undefined ? 2_000 : Math.max(2_000, Math.round(override / 2.5));
+}
 /** Compare physical directory identity before path text. Git for Windows can
  * return an 8.3/short or differently-cased spelling for the same top-level
  * directory that Node reached through its long path. A nonzero file ID keeps
@@ -525,7 +581,9 @@ function observeGit(observer, event) {
     catch { /* observation cannot change a Git outcome */ }
 }
 const CAPTURE_REMOTE_TIMEOUT_MS = 15_000;
-const READ_REMOTE_TIMEOUT_MS = 5_000;
+/** A user's whole branch can be large, so `hunch push` gets far longer than a memory capture push. */
+const BRANCH_PUSH_TIMEOUT_MS = 300_000;
+export const DEFAULT_READ_REMOTE_TIMEOUT_MS = 5_000;
 // A capture can spend roughly 90s in commit + bounded merge/push/retry seams.
 // A contending writer waits beyond that proven ceiling, then takes the lock and
 // drains every already-durable JSON write itself. This removes the old "maybe a
@@ -950,10 +1008,11 @@ function hunchWorktreeClean(hunchDir, env) {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
             env,
-            timeout: 2_000,
+            timeout: pullLocalGitTimeoutMs(),
         }).trim() === "";
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return false;
     }
 }
@@ -965,7 +1024,7 @@ function overlayGitTreeIsSafe(hunchDir, revision, env) {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
             env,
-            timeout: 2_000,
+            timeout: pullLocalGitTimeoutMs(),
             maxBuffer: 64 * 1024 * 1024,
         });
         return hunchTreeAttributesAreSafe(listing, (oid) => {
@@ -974,16 +1033,18 @@ function overlayGitTreeIsSafe(hunchDir, revision, env) {
                     encoding: "utf8",
                     stdio: ["ignore", "pipe", "ignore"],
                     env,
-                    timeout: 2_000,
+                    timeout: pullLocalGitTimeoutMs(),
                     maxBuffer: 4 * 1024 * 1024,
                 });
             }
-            catch {
+            catch (error) {
+                notePullGitError(error);
                 return null;
             }
         });
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return false;
     }
 }
@@ -1135,16 +1196,13 @@ function contractRemoteHeads(hunchDir, contract, direction, env, timeoutMs) {
     if (!hooksDir)
         return null;
     try {
-        const out = execFileSync("git", [
+        // Network git runs under boundedExecFileSync: execFileSync's timeout kills only
+        // the root, orphaning git-remote-https.exe on Windows (issue #498).
+        const out = boundedExecFileSync("git", [
             "-C", hunchDir,
             "-c", `core.hooksPath=${hooksDir}`,
             "ls-remote", "--refs", "--heads", "--upload-pack=git-upload-pack", url,
-        ], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            env: boundedTeamEnv(env),
-            timeout: timeoutMs,
-        });
+        ], { env: boundedTeamEnv(env), timeout: timeoutMs });
         if (!contractReady(contract))
             return null;
         const heads = [];
@@ -1156,7 +1214,8 @@ function contractRemoteHeads(hunchDir, contract, direction, env, timeoutMs) {
         }
         return heads;
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return null;
     }
 }
@@ -1167,27 +1226,28 @@ function fetchContractRef(hunchDir, contract, env, timeoutMs) {
     if (!hooksDir)
         return "";
     try {
-        execFileSync("git", [
+        boundedExecFileSync("git", [
             "-C", hunchDir,
             "-c", `core.hooksPath=${hooksDir}`,
             "fetch", "--no-tags", "--no-write-fetch-head", "--upload-pack=git-upload-pack",
             contract.fetchUrl, `+${contract.ref}:${TEAM_FETCH_REF}`,
-        ], { stdio: "ignore", env: boundedTeamEnv(env), timeout: timeoutMs });
+        ], { stdout: "ignore", env: boundedTeamEnv(env), timeout: timeoutMs });
         if (!contractReady(contract))
             return "";
         const oid = execFileSync("git", ["-C", hunchDir, "rev-parse", "--verify", TEAM_FETCH_REF], {
-            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: pullLocalGitTimeoutMs(),
         }).trim();
         return /^[0-9a-f]{40,64}$/i.test(oid) ? oid : "";
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return "";
     }
 }
 function setContractUpstream(hunchDir, contract, env) {
     try {
         const branch = execFileSync("git", ["-C", hunchDir, "symbolic-ref", "--quiet", "--short", "HEAD"], {
-            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: pullLocalGitTimeoutMs(),
         }).trim();
         if (!branch)
             return false;
@@ -1198,13 +1258,14 @@ function setContractUpstream(hunchDir, contract, env) {
         if (!oid || !remoteBranch)
             return false;
         execFileSync("git", ["-C", hunchDir, "update-ref", `refs/remotes/origin/${remoteBranch}`, oid], {
-            stdio: "ignore", env, timeout: 2_000,
+            stdio: "ignore", env, timeout: pullLocalGitTimeoutMs(),
         });
-        execFileSync("git", ["-C", hunchDir, "config", `branch.${branch}.remote`, "origin"], { stdio: "ignore", env, timeout: 2_000 });
-        execFileSync("git", ["-C", hunchDir, "config", `branch.${branch}.merge`, contract.ref], { stdio: "ignore", env, timeout: 2_000 });
+        execFileSync("git", ["-C", hunchDir, "config", `branch.${branch}.remote`, "origin"], { stdio: "ignore", env, timeout: pullLocalGitTimeoutMs() });
+        execFileSync("git", ["-C", hunchDir, "config", `branch.${branch}.merge`, contract.ref], { stdio: "ignore", env, timeout: pullLocalGitTimeoutMs() });
         return contractReady(contract);
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return false;
     }
 }
@@ -1215,7 +1276,7 @@ function setContractUpstream(hunchDir, contract, env) {
 function unbornBootstrapFingerprint(hunchDir, env) {
     try {
         const status = execFileSync("git", ["-C", hunchDir, "status", "--porcelain=v1", "--untracked-files=all", "--", "."], {
-            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: pullLocalGitTimeoutMs(),
         }).trim();
         const lines = status ? status.split(/\r?\n/) : [];
         if (lines.some((line) => !/^\?\? (?:\.hunch\/)?manifest\.json$/.test(line.trim())))
@@ -1235,7 +1296,8 @@ function unbornBootstrapFingerprint(hunchDir, env) {
         }
         return createHash("sha256").update(status).update("\0").update(manifest).digest("hex");
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return null;
     }
 }
@@ -1261,12 +1323,13 @@ function adoptContractHead(hunchDir, fetchedHead, contract, env, fingerprint) {
             "-c", "core.autocrlf=false",
             "reset", "--hard", fetchedHead,
         ], {
-            stdio: "ignore", env, timeout: 5_000,
+            stdio: ["ignore", "ignore", "pipe"], env, timeout: 5_000,
         });
         return overlayGitTreeIsSafe(hunchDir, headShaWithEnv(hunchDir, env), env)
             && overlayAttributeSourcesAreSafe(hunchDir, env);
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         if (moved) {
             try {
                 renameSync(backup, manifest);
@@ -1283,43 +1346,70 @@ function adoptContractHead(hunchDir, fetchedHead, contract, env, fingerprint) {
             catch { /* lock cleanup is the final backstop */ }
     }
 }
-function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories = false) {
+function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories = false, diag) {
     env = machineCommitEnv(hunchDir, env);
     env.GIT_ATTR_NOSYSTEM = "1";
+    const failed = (step, error = lastPullGitError) => {
+        if (diag)
+            diag.detail = pullFailureDetail(step, error);
+        return "failed";
+    };
+    // First failing step of an ordered conjunction; each check starts from a clean
+    // error slot so the noted git error belongs to the step that failed.
+    const firstFailure = (checks) => {
+        for (const [step, ok] of checks) {
+            lastPullGitError = undefined;
+            if (!ok())
+                return step;
+        }
+        return null;
+    };
     let overlayRoot = "";
     try {
         overlayRoot = dirname(realpathSync(hunchDir));
     }
-    catch {
-        return "failed";
-    }
-    if (!isGitRepoRoot(overlayRoot) || !safeOverlayTree(overlayRoot)
-        || !overlayAttributeSourcesAreSafe(hunchDir, env) || !contractReady(contract)) {
-        return "failed";
+    catch (error) {
+        return failed("resolve-overlay", error);
     }
+    let bad = firstFailure([
+        ["overlay-repo-root", () => isGitRepoRoot(overlayRoot)],
+        ["overlay-tree-safe", () => safeOverlayTree(overlayRoot)],
+        ["overlay-attributes-safe", () => overlayAttributeSourcesAreSafe(hunchDir, env)],
+        ["remote-contract", () => contractReady(contract)],
+    ]);
+    if (bad)
+        return failed(bad);
+    lastPullGitError = undefined;
     const localHead = headShaWithEnv(hunchDir, env);
     const unbornFingerprint = localHead ? null : unbornBootstrapFingerprint(hunchDir, env);
-    if (localHead ? !hunchWorktreeClean(hunchDir, env) : !unbornFingerprint)
-        return "failed";
+    if (localHead ? !hunchWorktreeClean(hunchDir, env) : !unbornFingerprint) {
+        return failed(localHead ? "worktree-clean" : "unborn-bootstrap");
+    }
     const hooksDir = disabledHooksDir(hunchDir);
     if (!hooksDir)
-        return "failed";
+        return failed("hooks-dir");
     const tryGit = (args, timeout = timeoutMs) => {
         const startedAt = Date.now();
+        lastPullGitError = undefined;
+        const argv = [
+            "-C", hunchDir,
+            "-c", `core.hooksPath=${hooksDir}`,
+            "-c", `core.attributesFile=${gitNullDevice()}`,
+            "-c", "core.autocrlf=false",
+            "-c", "commit.gpgsign=false",
+            ...args,
+        ];
         try {
-            execFileSync("git", [
-                "-C", hunchDir,
-                "-c", `core.hooksPath=${hooksDir}`,
-                "-c", `core.attributesFile=${gitNullDevice()}`,
-                "-c", "core.autocrlf=false",
-                "-c", "commit.gpgsign=false",
-                ...args,
-            ], {
-                stdio: "ignore", env, timeout,
-            });
+            // Only the network call pays for the tree-killing supervisor (#498); the
+            // merge of an already-fetched sha and rev-parse/abort stay local.
+            if (args[0] === "fetch")
+                boundedExecFileSync("git", argv, { stdout: "ignore", env, timeout });
+            else
+                execFileSync("git", argv, { stdio: ["ignore", "ignore", "pipe"], env, timeout });
             return true;
         }
         catch (error) {
+            notePullGitError(error);
             // Same stranding class as the commit path: a timeout-killed merge/fetch
             // leaves index.lock behind and wedges every later sync (issue #53).
             clearStrandedIndexLock(hunchDir, env, startedAt, error);
@@ -1328,51 +1418,67 @@ function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories
     };
     let fetchedHead = "";
     if (contract) {
+        lastPullGitError = undefined;
         const heads = contractRemoteHeads(hunchDir, contract, "fetch", env, timeoutMs);
         if (!heads)
-            return "failed";
+            return failed("ls-remote");
         if (heads.length === 0)
             return "unconfigured";
         if (heads.length !== 1 || heads[0].ref !== contract.ref)
-            return "failed";
+            return failed("remote-heads", null);
+        lastPullGitError = undefined;
         fetchedHead = fetchContractRef(hunchDir, contract, env, timeoutMs);
+        if (!fetchedHead)
+            return failed("fetch");
     }
     else {
-        if (!tryGit(["rev-parse", "--abbrev-ref", "@{upstream}"], 2_000))
+        if (!tryGit(["rev-parse", "--abbrev-ref", "@{upstream}"], pullLocalGitTimeoutMs()))
             return "unconfigured";
         if (!tryGit(["fetch", "--no-tags"]))
-            return "failed";
+            return failed("fetch");
+        lastPullGitError = undefined;
         fetchedHead = upstreamSha(hunchDir, env);
+        if (!fetchedHead)
+            return failed("upstream-sha");
     }
-    if (!fetchedHead || !overlayGitTreeIsSafe(hunchDir, fetchedHead, env))
-        return "failed";
+    bad = firstFailure([["fetched-tree-safe", () => overlayGitTreeIsSafe(hunchDir, fetchedHead, env)]]);
+    if (bad)
+        return failed(bad);
     // Another process need not honor Hunch's lock. Re-prove both the exact local
     // revision and the filesystem boundary after the network operation, before
     // Git is permitted to materialize the already-validated fetched tree.
-    if (headShaWithEnv(hunchDir, env) !== localHead
-        || !safeOverlayTree(overlayRoot)
-        || !overlayAttributeSourcesAreSafe(hunchDir, env)
-        || (localHead ? !hunchWorktreeClean(hunchDir, env) : unbornBootstrapFingerprint(hunchDir, env) !== unbornFingerprint)
-        || (localHead && !overlayGitTreeIsSafe(hunchDir, localHead, env))
-        || !contractReady(contract))
-        return "failed";
+    bad = firstFailure([
+        ["local-head-unchanged", () => headShaWithEnv(hunchDir, env) === localHead],
+        ["overlay-tree-safe-after-fetch", () => safeOverlayTree(overlayRoot)],
+        ["overlay-attributes-safe-after-fetch", () => overlayAttributeSourcesAreSafe(hunchDir, env)],
+        [localHead ? "worktree-clean-after-fetch" : "unborn-bootstrap-after-fetch",
+            () => (localHead ? hunchWorktreeClean(hunchDir, env) : unbornBootstrapFingerprint(hunchDir, env) === unbornFingerprint)],
+        ["local-tree-safe", () => !localHead || overlayGitTreeIsSafe(hunchDir, localHead, env)],
+        ["remote-contract-after-fetch", () => contractReady(contract)],
+    ]);
+    if (bad)
+        return failed(bad);
     // Canonicalize local branch/upstream metadata before the worktree mutation.
     // If this fails, the exact fetched tree has not been materialized yet.
+    lastPullGitError = undefined;
     if (contract && !setContractUpstream(hunchDir, contract, env))
-        return "failed";
+        return failed("set-upstream");
     if (!localHead && contract && unbornFingerprint) {
-        return adoptContractHead(hunchDir, fetchedHead, contract, env, unbornFingerprint) ? "merged" : "failed";
+        lastPullGitError = undefined;
+        return adoptContractHead(hunchDir, fetchedHead, contract, env, unbornFingerprint) ? "merged" : failed("adopt-remote-head");
     }
     if (tryGit(["merge", "--no-edit", ...(allowUnrelatedHistories ? ["--allow-unrelated-histories"] : []), fetchedHead])) {
-        return safeOverlayTree(overlayRoot)
-            && overlayAttributeSourcesAreSafe(hunchDir, env)
-            && contractReady(contract)
-            && overlayGitTreeIsSafe(hunchDir, headShaWithEnv(hunchDir, env), env)
-            ? "merged"
-            : "failed";
-    }
-    tryGit(["merge", "--abort"], 2_000); // conflict/timeout → restore a clean tree
-    return "failed";
+        bad = firstFailure([
+            ["overlay-tree-safe-after-merge", () => safeOverlayTree(overlayRoot)],
+            ["overlay-attributes-safe-after-merge", () => overlayAttributeSourcesAreSafe(hunchDir, env)],
+            ["remote-contract-after-merge", () => contractReady(contract)],
+            ["merged-tree-safe", () => overlayGitTreeIsSafe(hunchDir, headShaWithEnv(hunchDir, env), env)],
+        ]);
+        return bad ? failed(bad) : "merged";
+    }
+    const mergeError = lastPullGitError;
+    tryGit(["merge", "--abort"], pullLocalGitTimeoutMs()); // conflict/timeout → restore a clean tree
+    return failed("merge", mergeError);
 }
 function upstreamSha(hunchDir, env) {
     try {
@@ -1380,10 +1486,11 @@ function upstreamSha(hunchDir, env) {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
             env,
-            timeout: 2_000,
+            timeout: pullLocalGitTimeoutMs(),
         }).trim();
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return "";
     }
 }
@@ -1393,7 +1500,7 @@ function upstreamSha(hunchDir, env) {
  * and discard oversized/unavailable output without changing its exit result. */
 function runObservedPush(args, env, timeoutMs, observe) {
     if (!observe) {
-        execFileSync("git", args, { stdio: "ignore", env, timeout: timeoutMs });
+        boundedExecFileSync("git", args, { stdout: "ignore", env, timeout: timeoutMs });
         return null;
     }
     let directory, descriptor;
@@ -1408,11 +1515,11 @@ function runObservedPush(args, env, timeoutMs, observe) {
             }
             catch { }
         }
-        execFileSync("git", args, { stdio: "ignore", env, timeout: timeoutMs });
+        boundedExecFileSync("git", args, { stdout: "ignore", env, timeout: timeoutMs });
         return null;
     }
     try {
-        execFileSync("git", args, { stdio: ["ignore", descriptor, "ignore"], env, timeout: timeoutMs });
+        boundedExecFileSync("git", args, { stdout: descriptor, env, timeout: timeoutMs });
         try {
             const buffer = Buffer.alloc(1_000_001);
             const bytes = readSync(descriptor, buffer, 0, buffer.length, 0);
@@ -1460,8 +1567,8 @@ function observePushResult(hunchDir, env, output, observer) {
         if (!destination || /[\x00-\x1f\x7f]/.test(destination) || Date.now() >= deadline)
             continue;
         try {
-            const result = execFileSync("git", ["-C", hunchDir, "ls-remote", "--refs", "--exit-code", "--", destination, ref], {
-                env, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: Math.max(1, deadline - Date.now()), maxBuffer: 16_384,
+            const result = boundedExecFileSync("git", ["-C", hunchDir, "ls-remote", "--refs", "--exit-code", "--", destination, ref], {
+                env, timeout: Math.max(1, deadline - Date.now()), maxBuffer: 16_384,
             }).trim();
             const rows = result.split("\n").filter(row => row.split("\t")[1] === ref);
             const commitSha = rows.length === 1 ? rows[0].split("\t")[0] : "";
@@ -1553,12 +1660,7 @@ function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutM
     if (!before)
         return false;
     try {
-        const refs = execFileSync("git", ["-C", hunchDir, "ls-remote", "--refs", remote], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            env,
-            timeout: timeoutMs,
-        }).trim();
+        const refs = boundedExecFileSync("git", ["-C", hunchDir, "ls-remote", "--refs", remote], { env, timeout: timeoutMs }).trim();
         if (refs)
             return false;
     }
@@ -1614,6 +1716,11 @@ export function teamPullIsFresh(status) {
     return status === "updated" || status === "current" || status === "empty";
 }
 export function pullHunchStatus(hunchDir, opts = {}) {
+    return pullHunchStatusDetailed(hunchDir, opts).status;
+}
+/** pullHunchStatus plus a diagnosable reason for a "failed" pull. The remote budget is
+ *  the caller's (default 5s) unless HUNCH_PULL_GIT_TIMEOUT_MS overrides it. */
+export function pullHunchStatusDetailed(hunchDir, opts = {}) {
     const env = foreignRepoEnv({
         ...process.env,
         ...opts.env,
@@ -1624,19 +1731,22 @@ export function pullHunchStatus(hunchDir, opts = {}) {
     const before = headShaWithEnv(hunchDir, env);
     const lock = join(hunchDir, ".hunch-commit.lock");
     if (acquireCommitLock(lock).state !== "acquired")
-        return "busy";
+        return { status: "busy" };
+    const diag = {};
     try {
-        const merged = mergeRemote(hunchDir, env, opts.timeoutMs ?? READ_REMOTE_TIMEOUT_MS, opts.remote, opts.allowUnrelatedHistories ?? false);
+        const timeoutMs = pullRemoteTimeoutMs(opts.timeoutMs);
+        const merged = mergeRemote(hunchDir, env, timeoutMs, opts.remote, opts.allowUnrelatedHistories ?? false, diag);
         if (merged === "failed" || merged === "unconfigured" || !contractReady(opts.remote)) {
-            if (merged !== "unconfigured" || !contractReady(opts.remote))
-                return "failed";
+            if (merged !== "unconfigured" || !contractReady(opts.remote)) {
+                return { status: "failed", detail: merged === "failed" ? diag.detail ?? { step: "merge-remote" } : { step: "remote-contract-after-pull" } };
+            }
             // The advertised remote has no branch yet AND this clone never committed memory:
             // both sides are empty, so there is nothing to be stale against (#427). A clone
             // WITH memory against an empty remote stays "unconfigured" (unpublished, or the
             // remote lost its history) so strict guards keep failing closed on it.
-            return opts.remote && !before && !headShaWithEnv(hunchDir, env) ? "empty" : merged;
+            return { status: opts.remote && !before && !headShaWithEnv(hunchDir, env) ? "empty" : merged };
         }
-        return headShaWithEnv(hunchDir, env) !== before ? "updated" : "current";
+        return { status: headShaWithEnv(hunchDir, env) !== before ? "updated" : "current" };
     }
     finally {
         try {
@@ -2221,7 +2331,9 @@ export function memoryMoveDiff(sha, root) {
  *  false when there is no upstream / offline / not a repo. */
 export function pushCurrentBranch(root) {
     try {
-        execFileSync("git", ["-C", root, "push"], { stdio: "ignore" });
+        // Bounded so an unreachable remote can't hang the caller, and a timeout
+        // kills git's whole tree, not just the root (#498).
+        boundedExecFileSync("git", ["-C", root, "push"], { stdout: "ignore", timeout: BRANCH_PUSH_TIMEOUT_MS });
         return true;
     }
     catch {

package/dist/extractors/indexer.js

@@ -10,7 +10,7 @@
  */
 import { readFileSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
-import { parseSource, attributeCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
+import { parseSource, attributeCalls, attributeQualifiedCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
 import { isParserLoadError } from "./nativeTreeSitter.js";
 import { extractHelmDirectives } from "./helm.js";
 import { extractK8sManifest, extractKustomization, isKustomizationFile, kustomizeNamespaces, namespacesCompatible } from "./k8sManifest.js";
@@ -332,7 +332,7 @@ export function scanRepo(store, root, opts = {}) {
         }
         fileSymbols.set(rel, idsInFile);
         fileSymbolIndexId.set(rel, symbolIndexId);
-        perFileCalls.push({ file: rel, bySym: attributeCalls(parsed) });
+        perFileCalls.push({ file: rel, bySym: attributeCalls(parsed), qualified: attributeQualifiedCalls(parsed) });
         perFileImports.push({ file: rel, imports: parsed.imports });
         perFileRelations.push({ file: rel, bySym: attributeRelations(parsed) });
         if (languageFor(rel)?.id === "php") {
@@ -359,7 +359,7 @@ export function scanRepo(store, root, opts = {}) {
         if (langId === "php") {
             return resolvePhpImportTargets(file, spec, phpNamespaces.get(file) ?? null, phpUseDeclarations.get(file) ?? [], phpPsr4, trackedFiles);
         }
-        return [resolveImport(file, spec, fileSymbols)].filter((target) => !!target);
+        return [resolveImport(file, spec, trackedFiles)].filter((target) => !!target);
     };
     const importedFiles = new Map(perFileImports.map(({ file, imports }) => {
         const targets = new Set(imports.flatMap((specifier) => resolveImportTargets(file, specifier)));
@@ -381,7 +381,7 @@ export function scanRepo(store, root, opts = {}) {
         edgeSeen.add(e.id);
         edges.push(e);
     };
-    for (const { file, bySym } of perFileCalls) {
+    for (const { file, bySym, qualified } of perFileCalls) {
         // Most languages leave this unset and get "calls" — YAML's alias->anchor
         // references aren't function calls, so its LanguageSpec declares "references".
         const edgeType = languageFor(file)?.referenceEdgeType ?? "calls";
@@ -423,6 +423,42 @@ export function scanRepo(store, root, opts = {}) {
                 });
             }
         }
+        // Calls pinned to one imported module (`ns.fn()`, aliased `g()`): the member
+        // gate above drops them, so resolve the name ONLY inside that module's files —
+        // a unique match there is the binding; zero or several -> no edge.
+        // A module binding exposes top-level exports, so `U.helper()` prefers a function
+        // `helper` over a same-named class method `Foo.helper`; a sole method match still
+        // binds, since `module.exports = { helper() {} }` parses as a method too.
+        const moduleFiles = new Map(); // resolve each module once per file
+        for (const [callerIndex, targets] of qualified) {
+            const callerId = indexToId.get(callerIndex);
+            if (!callerId)
+                continue;
+            const callerName = byId.get(callerId)?.name ?? "?";
+            for (const { callee, module } of targets) {
+                let files = moduleFiles.get(module);
+                if (!files)
+                    moduleFiles.set(module, files = new Set(resolveImportTargets(file, module)));
+                const inModule = (nameIndex.get(callee) ?? []).filter((id) => {
+                    const sym = byId.get(id);
+                    return !!sym && files.has(sym.file);
+                });
+                const nonMethods = inModule.filter((id) => byId.get(id).kind !== "method");
+                const matches = nonMethods.length > 0 ? nonMethods : inModule;
+                if (matches.length !== 1 || matches[0] === callerId)
+                    continue;
+                const calleeId = matches[0];
+                addEdge({
+                    schema: "hunch.edge/1",
+                    id: edgeId(callerId, calleeId, edgeType),
+                    from: callerId, to: calleeId, type: edgeType,
+                    reason: `${callerName} ${edgeType} ${callee}`, strength: 0.8,
+                    provenance: extracted(0.8, [file]),
+                    environment: null,
+                    metadata: {},
+                });
+            }
+        }
     }
     // ---- K8s manifest cross-resource references (Phase 1: name-keyed) --------
     // Own resolver, not resolveName(): resolveName() indexes by bare symbol name
@@ -747,8 +783,8 @@ function resolveName(name, file, importedFiles, nameIndex, byId) {
     return imported.length === 1 ? imported[0] : null;
 }
 /** Resolve a relative import specifier to a concrete tracked file path. */
-function resolveImport(fromFile, spec, fileSymbols) {
-    return resolveRelativeImport(fromFile, spec, fileSymbols.keys()).path;
+function resolveImport(fromFile, spec, trackedFiles) {
+    return resolveRelativeImport(fromFile, spec, trackedFiles).path;
 }
 /** First of `${modulePath}.py` / `${modulePath}/__init__.py` that's a tracked file,
  *  or null — the shared "module file vs. package __init__" candidate check used by

package/dist/extractors/languages.d.ts

@@ -17,6 +17,15 @@ export interface LanguageSpec {
     defKindOf: Record<string, ParsedSymbolKind>;
     /** Query capture-name (ending in ".name") -> the matching ".def" capture-name. */
     nameToDef: Record<string, string>;
+    /** Optional query binding a local name to an imported module, run with
+     *  matches() so captures pair up: @bind.src (module specifier), @bind.local
+     *  (local name), @bind.name (an imported member, `from X import name`). Feeds
+     *  qualified calls (`ns.fn()`), resolved only inside the bound module's files. */
+    bindingQuery?: string;
+    /** Local name an import binds when @bind.local is absent (Go `"a/geo"` -> geo). */
+    defaultBindingLocal?(src: string): string | null;
+    /** Module path of `from <src> import <name>` when name is itself a submodule. */
+    joinSubmodule?(src: string, name: string): string;
     /** Optional semantic relationship captures. The generic parser/indexer emit
      * these through the normal graph path; languages only describe syntax. */
     relationKindOf?: Record<string, {