@davesheffer/hunch 1.45.0 → 1.45.2

package/dist/extractors/git.js

@@ -154,10 +154,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 +224,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 +580,7 @@ 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;
+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 +1005,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 +1021,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 +1030,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;
     }
 }
@@ -1141,7 +1199,7 @@ function contractRemoteHeads(hunchDir, contract, direction, env, timeoutMs) {
             "ls-remote", "--refs", "--heads", "--upload-pack=git-upload-pack", url,
         ], {
             encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
+            stdio: ["ignore", "pipe", "pipe"],
             env: boundedTeamEnv(env),
             timeout: timeoutMs,
         });
@@ -1156,7 +1214,8 @@ function contractRemoteHeads(hunchDir, contract, direction, env, timeoutMs) {
         }
         return heads;
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return null;
     }
 }
@@ -1172,22 +1231,23 @@ function fetchContractRef(hunchDir, contract, env, timeoutMs) {
             "-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 });
+        ], { stdio: ["ignore", "ignore", "pipe"], 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,29 +1346,51 @@ 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;
         try {
             execFileSync("git", [
                 "-C", hunchDir,
@@ -1315,11 +1400,12 @@ function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories
                 "-c", "commit.gpgsign=false",
                 ...args,
             ], {
-                stdio: "ignore", env, timeout,
+                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 +1414,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 +1482,11 @@ function upstreamSha(hunchDir, env) {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
             env,
-            timeout: 2_000,
+            timeout: pullLocalGitTimeoutMs(),
         }).trim();
     }
-    catch {
+    catch (error) {
+        notePullGitError(error);
         return "";
     }
 }
@@ -1614,6 +1717,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 +1732,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 {

package/dist/integrations/hooks.d.ts

@@ -61,6 +61,11 @@ export declare const PORTABLE_HOOK_INVOCATION: string;
  *  or a trailing top-level `if … else … fi` whose every branch ends in
  *  `exec`/`exit` — the shape of the pre-commit framework's generated hook. */
 export declare function terminalExitLine(content: string): string | null;
+export declare function isInside(parent: string, child: string): boolean;
+export declare function gitRun(args: string[], cwd: string): {
+    status: number | null;
+    stdout: string;
+};
 type BlockState = "installed" | "unreachable" | "stale" | "missing";
 /** The result of inspecting the command a managed block actually runs (issue #315). */
 export type HookInvocationHealth = {
@@ -78,6 +83,21 @@ export type HookInvocationHealth = {
  *  the subcommand; env assignments and a leading `(` belong to the block's own
  *  shape and are stripped. Never spawns anything, never touches the network. */
 export declare function hookInvocationHealth(command: string, root: string): HookInvocationHealth;
+/** The repo's worktree tops as `git worktree list --porcelain` reports them:
+ *  `linked` is every entry AFTER the first (the first is always the main
+ *  worktree, or the bare repo) that is not the bare entry, and `count` is how
+ *  many non-bare worktrees the repo has — the number the shared-hooks note
+ *  quotes, which must not include a bare repo's phantom entry. `main` is the
+ *  first entry when it is a checkout, null when the common dir is bare (no
+ *  main checkout exists). Entries are
+ *  separated by blank lines and each starts with a `worktree <path>` line.
+ *  Read straight from git rather than the workspace ledger: this runs during
+ *  `hunch init`, before any ledger exists. */
+export declare function worktreeTops(root: string): {
+    linked: string[];
+    count: number;
+    main: string | null;
+};
 export declare function installPostCommitHook(root: string, invocation: string, opts?: {
     private?: boolean;
     commit?: boolean;

package/dist/integrations/hooks.js

@@ -139,12 +139,12 @@ function realish(p) {
         return resolve(p);
     }
 }
-function isInside(parent, child) {
+export function isInside(parent, child) {
     const norm = (p) => (process.platform === "win32" ? realish(p).toLowerCase() : realish(p));
     const rel = relative(norm(parent), norm(child));
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-function gitRun(args, cwd) {
+export function gitRun(args, cwd) {
     const p = spawnSync("git", args, { cwd, encoding: "utf8", env: initiatorChildEnv(), stdio: ["ignore", "pipe", "ignore"] });
     return { status: p.status, stdout: (p.stdout ?? "").trim() };
 }
@@ -504,14 +504,16 @@ function snippetFor(t, mark, build, localInvocation) {
  *  `linked` is every entry AFTER the first (the first is always the main
  *  worktree, or the bare repo) that is not the bare entry, and `count` is how
  *  many non-bare worktrees the repo has — the number the shared-hooks note
- *  quotes, which must not include a bare repo's phantom entry. Entries are
+ *  quotes, which must not include a bare repo's phantom entry. `main` is the
+ *  first entry when it is a checkout, null when the common dir is bare (no
+ *  main checkout exists). Entries are
  *  separated by blank lines and each starts with a `worktree <path>` line.
  *  Read straight from git rather than the workspace ledger: this runs during
  *  `hunch init`, before any ledger exists. */
-function worktreeTops(root) {
+export function worktreeTops(root) {
     const out = gitRun(["worktree", "list", "--porcelain"], root).stdout;
     if (!out)
-        return { linked: [], count: 0 };
+        return { linked: [], count: 0, main: null };
     const entries = normalizeEol(out).split(/\n\s*\n/).map((e) => e.split("\n"));
     const parsed = entries
         .map((lines) => ({
@@ -519,7 +521,12 @@ function worktreeTops(root) {
         bare: lines.some((l) => l.trim() === "bare"),
     }))
         .filter((e) => e.path !== "");
-    return { linked: parsed.slice(1).filter((e) => !e.bare).map((e) => e.path), count: parsed.filter((e) => !e.bare).length };
+    const first = parsed[0];
+    return {
+        linked: parsed.slice(1).filter((e) => !e.bare).map((e) => e.path),
+        count: parsed.filter((e) => !e.bare).length,
+        main: first && !first.bare ? first.path : null,
+    };
 }
 /** The LINKED worktree an invocation is bound to — one it can only work from
  *  inside, because some token is an absolute path under it (that worktree's own

package/dist/integrations/providers.js

@@ -26,6 +26,7 @@ import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd,
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 import { parseJsonc } from "../core/jsonc.js";
 import { parse as parseToml } from "smol-toml";
+import { publishedMcpInvocation } from "../cli/invocation.js";
 /** JSONC comments are user prose. A parsed object cannot retain their position,
  * so refuse a write rather than reserialize the file without them. */
 function hasJsoncComments(raw) {
@@ -388,18 +389,52 @@ export function writeVscodeHooks(root, inv) {
         Stop: [{ type: "command", command }],
     });
 }
+const WINDSURF_EVENTS = ["pre_user_prompt", "pre_write_code", "post_write_code", "post_run_command"];
+/** The published npx pin (any version), in the current spelling and in the fully
+ * quoted one written before v1.21.1 (`"npx" "-y" "--package=…" …`). */
+const PUBLISHED_PIN = /^\s*"?npx(?:\.cmd)?"?\s+"?-y"?\s+"?--package=(?:hunch-exact@npm:)?@davesheffer\/hunch/;
+/** The events of `file` holding a Hunch hook entry, when it has at least one and
+ * every one of them runs the published pin; null otherwise. Throws, like every
+ * writer, on a file it cannot parse. */
+function publishedPinEvents(file) {
+    const hooks = objectField(readJsonObj(file), "hooks", file);
+    const events = new Set();
+    let onlyPins = true;
+    const collect = (event) => (entry) => {
+        const e = entry && typeof entry === "object" ? entry : null;
+        if (Array.isArray(e?.hooks) && typeof e.command !== "string")
+            e.hooks.forEach(collect(event));
+        else if (typeof e?.command === "string") {
+            if (PUBLISHED_PIN.test(e.command))
+                events.add(event);
+            else
+                onlyPins = false;
+        }
+    };
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (Array.isArray(entries))
+            entries.filter(isHunchProviderHook).forEach(collect(event));
+    }
+    return onlyPins && events.size > 0 ? events : null;
+}
 /** Windsurf's documented workspace hooks. It only supports deterministic
  * pre-hook blocking via exit code 2, so Hunch uses rules + MCP for context and
  * reserves the hook for strict edit protection and pipeline observation. */
 export function writeWindsurfHooks(root, inv) {
     const file = join(root, ".windsurf", "hooks.json");
-    const command = hookCommand(inv, "windsurf");
-    return writeHookConfig(file, {
-        pre_user_prompt: [{ command, show_output: false }],
-        pre_write_code: [{ command, show_output: false }],
-        post_write_code: [{ command, show_output: false }],
-        post_run_command: [{ command, show_output: false }],
-    });
+    const published = hookCommand(publishedMcpInvocation(), "windsurf");
+    let command = hookCommand(inv, "windsurf");
+    // A source-checkout run (tsx / local dist) must never replace a tracked
+    // published pin with a machine-local path (#466): a complete pinned file is
+    // kept as is, and a partial one is completed with the published pin.
+    if (command !== published) {
+        const pinned = publishedPinEvents(file);
+        if (pinned && WINDSURF_EVENTS.every((event) => pinned.has(event)))
+            return file;
+        if (pinned)
+            command = published;
+    }
+    return writeHookConfig(file, Object.fromEntries(WINDSURF_EVENTS.map((event) => [event, [{ command, show_output: false }]])));
 }
 function antigravityHandler(command) {
     return { type: "command", command, timeout: 15 };

package/dist/integrations/team.js

@@ -12,7 +12,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { machineFile } from "../core/machine.js";
 import { hunchTreeAttributesAreSafe, safeOverlayGitTreeListing, safeOverlayTree } from "../core/overlaySafety.js";
 import { hunchPaths, hunchPathsForDir } from "../core/paths.js";
-import { canonicalRemoteUrl, checkoutCommonDir, gitNullDevice, mainWorktreeRoot, sameFilesystemEntry, sameRemoteUrl } from "../extractors/git.js";
+import { canonicalRemoteUrl, checkoutCommonDir, gitNullDevice, mainWorktreeRoot, pullRemoteTimeoutMs, sameFilesystemEntry, sameRemoteUrl } from "../extractors/git.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
 import { ensureSharedOverlayPointer } from "./worktree.js";
@@ -854,7 +854,7 @@ export function ensureTeamOverlay(root) {
         if (!existsSync(dest)) {
             const cloned = cloneValidatedTeamOverlay(team.shared_repo, root, dest, {
                 sharedRef: team.shared_ref,
-                timeoutMs: 5_000,
+                timeoutMs: pullRemoteTimeoutMs(),
             });
             if (!cloned || !overlayMatchesTeamRemote(root, dest)) {
                 if (cloned)

package/dist/integrations/uninstall.d.ts

@@ -1,6 +1,13 @@
 /** The opt-out marker, at the repository root. Commit it so every clone stays opted out. */
 export declare const OPT_OUT_FILE = ".hunch-removed";
 export declare function isOptedOut(root: string): boolean;
+/** Whether `start`, or the repository containing it, opted out: walks up through
+ *  `start`'s ancestors (which need not exist yet), stopping after the first one holding
+ *  `.git` or at the filesystem root, so a path inside an opted-out repository (`serve
+ *  init --root ./partitions/x`) is gated like the repository itself (#458). A `.hunch`
+ *  store is deliberately not a boundary: a partition store nested in an opted-out
+ *  repository stays gated (fail closed). */
+export declare function optedOutAt(start: string): boolean;
 export declare function optOutMessage(): string;
 export interface UninstallStep {
     /** Repo-relative (POSIX) where possible, else absolute. */
@@ -17,6 +24,8 @@ export interface UninstallPlan {
         path: string;
         reason: string;
     }>;
+    /** Consequences beyond this checkout (other worktrees, other branches); printed, never refused over. */
+    warnings?: string[];
 }
 /** Read-only: everything `hunch uninstall` would do in `root`. */
 export declare function planUninstall(root: string, opts?: {