@davesheffer/hunch 1.40.0 → 1.41.0

package/dist/integrations/team.js

@@ -19,15 +19,25 @@ import { installMergeDriver } from "./mergeDriver.js";
 import { ensureGitignore } from "./gitignore.js";
 import { resolveInvocation } from "../cli/invocation.js";
 export const DEFAULT_TEAM_REF = "refs/heads/main";
+// check-ref-format without --branch checks syntax only, independent of the
+// repository, ref existence, or remote state. Retain just its last successful
+// input: one shared sync can otherwise spawn Git dozens of times for the same
+// name. Route/remote validation still runs afresh, and failed invocations retry.
+let lastValidTeamRef;
 export function safeTeamRef(value) {
     const ref = value.trim();
     if (!ref.startsWith("refs/heads/") || ref === "refs/heads/")
         return null;
+    if (ref === lastValidTeamRef)
+        return ref;
     const checked = spawnSync("git", ["check-ref-format", ref], {
         stdio: "ignore",
         env: { ...process.env, GIT_CONFIG_NOSYSTEM: "1" },
     });
-    return checked.status === 0 ? ref : null;
+    if (checked.status !== 0)
+        return null;
+    lastValidTeamRef = ref;
+    return ref;
 }
 export function teamSharedRef(team) {
     return team.shared_ref ?? DEFAULT_TEAM_REF;

package/dist/mcp/server.d.ts

@@ -8,8 +8,133 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HunchStore } from "../store/hunchStore.js";
+import { type StateFacet } from "../core/stateContract.js";
 import type { Symbol } from "../core/types.js";
 export declare const publicationVocabulary: (hunchDir: string) => RegExp[];
+/** The cwd-hint fallback (see `cwdHintField` above) only helps when the CALLER
+ *  remembers to pass it — a subagent spawned straight into its own linked
+ *  worktree has no reason to think of the session's "starting directory" as
+ *  different from its own, so the hint is silently omitted and an auto-committing
+ *  write lands wherever `root` last was (often the primary checkout, on its
+ *  default branch). This is a backstop, NOT a complete fix: it only catches a
+ *  related file that's new/untracked at the resolved root but already exists in
+ *  a sibling worktree — the common "edited an existing tracked file" case is
+ *  invisible to a pure existence check (the file exists at every worktree, just
+ *  with different content).
+ *
+ *  Used by `misrouteGuard` below to cover every auto-committing write tool that
+ *  names files: hunch_record_decision's related_files, hunch_record_correction's
+ *  scope_hint_file, hunch_record_finding's affected_files, and nuryel_write's
+ *  decisions/findings/bugs/constraints facets via `fileEvidenceFor`. Every
+ *  matching sibling is named as a candidate `cwd` and the write is refused
+ *  rather than risked; it returns every match rather than the first, since
+ *  confidently naming just one would let a caller that blindly retries as
+ *  instructed land in the WRONG worktree — the same failure mode one level
+ *  removed.
+ *
+ *  Two false-positive guards, both required, not optional hardening:
+ *  - Empty related_files, or no sibling worktree doing any better, is silent — a
+ *    decision that legitimately precedes its code (no files yet) is unaffected.
+ *  - A related_files entry ABSENT at the root is not automatically suspicious: an
+ *    ordinary delete/rename recorded correctly at the resolved root produces the
+ *    exact same shape (file gone here, still present in whichever sibling
+ *    worktree branched before the change) as a genuine misroute.
+ *    `pathKnownToHistory` distinguishes them — a path this checkout's own HEAD
+ *    has ever tracked explains its absence without invoking a worktree guess.
+ *
+ *  Coverage boundary: only checks the file evidence passed in THIS call (related_files
+ *  / scope_hint_file / affected_files), not values inherited from an existing record
+ *  on re-record/supersede — a call that omits its file field to rely on inheritance
+ *  won't trip this guard even if it's happening in the wrong worktree. That's a
+ *  deliberate tradeoff against false positives on stale evidence, not full coverage
+ *  of every misrouted write.
+ *
+ *  Absolute paths: agents naturally send them (edit-tool payloads and MCP roots
+ *  are absolute), and a NAIVE `join(dir, "/abs/path")` produces a nonsense
+ *  concatenated path that exists nowhere — the guard would find nothing to
+ *  compare against ANY directory and stay silent, reproducing the exact bug the
+ *  guard exists to catch. `existsUnder` checks an absolute entry AS ITSELF,
+ *  scoped to whichever directory is under test (root, or each candidate worktree
+ *  in turn) via `deepestContainer`, not `join()` — so an absolute path naming a
+ *  file that exists only under a worktree's own tree is direct positive evidence
+ *  for that worktree specifically, no existence heuristic required. Relativizing
+ *  it against `root` alone can't represent a SIBLING worktree's absolute path at
+ *  all: it's never under root's tree, so it relativizes to "../…" and gets
+ *  dropped — silently reintroducing the bypass one level removed. A NESTED
+ *  worktree (`root/.worktrees/x`) is the opposite trap: it IS lexically under
+ *  root's own tree, so a plain "is this path under root" check wrongly
+ *  attributes it to root — `deepestContainer` picks the MOST SPECIFIC
+ *  (longest-path) containing worktree, not just any containing ancestor, so root
+ *  never swallows a worktree nested inside it. An absolute path outside every
+ *  known worktree matches none and correctly contributes nothing: not "absent
+ *  here, check the siblings", just nothing to compare. Canonicalized
+ *  (`canonicalRootPath`, the same symlink/case resolution `resolveActiveRoot`
+ *  uses above) on both sides before comparing, so a worktree reached through a
+ *  symlink or a case-different spelling isn't silently missed, and compared by
+ *  exact path SEGMENT, not string prefix, so a real sibling `foo-other` doesn't
+ *  false-match `foo` and a file genuinely named `..odd.ts` isn't mistaken for a
+ *  `..` traversal. A DIRECTORY entry (or the empty-string/"." an agent might
+ *  send meaning "the repo itself") contributes nothing either: `existsUnder`
+ *  checks `isFile`, never mere existence, since a directory match would silently
+ *  disable the guard for every OTHER entry in the same call — and
+ *  `pathKnownToHistory` (below) confirms a git pathspec matched the EXACT entry,
+ *  not merely something under/matching it, for the identical reason.
+ *
+ *  A RELATIVE entry containing a ".." segment that escapes root's own tree when
+ *  resolved against root is the same misroute as a worktree-rooted absolute
+ *  path, merely spelled relatively — resolved against ROOT specifically (the
+ *  only base the server actually has; never re-resolved per candidate in the
+ *  loop below, which would answer a different, meaningless question) and then
+ *  run through the identical absolute-path containment logic. A relative entry
+ *  that does NOT escape root's tree keeps the original, intentional
+ *  multi-location check instead: the SAME relative suffix tried against every
+ *  candidate directory in turn — that's how a plain "this file's name" evidence
+ *  has always found a sibling worktree holding a file by that name, and it must
+ *  keep doing so for a NESTED worktree reached by a non-escaping relative path,
+ *  whose containing worktree this does not (yet) distinguish from root itself —
+ *  that residual gap fails OPEN (silently uncaught), never toward a false
+ *  positive.
+ *
+ *  Exported for direct unit testing — the candidate logic is otherwise reachable
+ *  only through a full MCP client/server integration test. */
+export declare const misroutedWorktreeCandidates: (root: string, relatedFiles: readonly string[]) => string[];
+/** Normalizes file evidence for the misroute guard specifically. A literal
+ *  backslash byte is a legal POSIX filename character, not a path separator,
+ *  so blindly running every entry through `toPosixTarget` before
+ *  `misroutedWorktreeCandidates` sees it can rewrite a real file's name into a
+ *  fake extra path segment. The string alone can't disambiguate "Windows
+ *  separator" from "literal POSIX byte", so this asks the filesystem AND git
+ *  history instead (`namesRealEvidence`): when the RAW, un-normalized entry
+ *  already names a real file, or is a relative path git knows was tracked at
+ *  `root` (possibly since deleted/renamed), that settles it — the byte was
+ *  literal — and the raw string is kept as-is, bypassing `toPosixTarget`
+ *  entirely. Otherwise it normalizes through `toPosixTarget` exactly as
+ *  before, preserving the legitimate Windows-separator case (a Windows-style
+ *  path can never collide with a real or once-tracked POSIX file, since `\`
+ *  cannot appear in a Windows filename to begin with). Scoped to the
+ *  misroute-guard call sites only — the stored related_files/affected_files
+ *  fields are still normalized separately, unaffected by this.
+ *
+ *  Known accepted gap: a contrived collision — a file legitimately deleted
+ *  from `root`'s history AND a genuine Windows-style path meaning something
+ *  else present in a sibling worktree — resolves in favor of history and
+ *  fails OPEN (no misroute reported), the same fail-open tradeoff
+ *  `misroutedWorktreeCandidates` itself already documents elsewhere. */
+export declare function guardEvidence(root: string, files: readonly string[]): string[];
+/** The file-evidence field, if any, each nuryel_write facet carries: related_files
+ *  for decisions, affected_files for findings/bugs, and scope (the glob list a
+ *  constraint applies to — the same role hunch_record_correction's
+ *  scope_hint_file plays) for constraints. A TOTAL map over StateFacet, not an
+ *  open-ended ternary chain: adding a facet to STATE_FACETS without adding it
+ *  here is a compile error, not a silent gap. null means the facet carries no
+ *  comparable field and is left unguarded rather than inventing one. Exported so
+ *  tests can assert the mapping directly instead of only probing it through live
+ *  misroute behavior. */
+export declare const FILE_EVIDENCE_FIELD: Record<StateFacet, string | null>;
+/** `record` is caller-supplied z.record(string, unknown) — defensive by
+ *  construction, so anything other than an array of strings reads as no
+ *  evidence instead of throwing. */
+export declare function fileEvidenceFor(facet: StateFacet, record: Record<string, unknown>): string[];
 /** Resolve a free-form target (symbol id / name / file path) to symbol records.
  *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
  *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift