@saasontools/strauss-kb 0.1.13 → 0.1.15

package/dist/index.cjs

@@ -99,6 +99,7 @@ __export(index_exports, {
   impact: () => impact,
   inboundIndex: () => inboundIndex,
   indexIsStale: () => indexIsStale,
+  isCanonicalRepoUrl: () => isCanonicalRepoUrl,
   isKbLinkRel: () => isKbLinkRel,
   isKbRecordType: () => isKbRecordType,
   isNoDecisionRecord: () => isNoDecisionRecord,
@@ -122,11 +123,13 @@ __export(index_exports, {
   pinBase: () => pinBase,
   readMergedPins: () => readMergedPins,
   readPinsLayer: () => readPinsLayer,
+  readRemoteAnchors: () => readRemoteAnchors,
   regexResolver: () => regexResolver,
   renderCatalogLine: () => renderCatalogLine,
   renderIndex: () => renderIndex,
   renderIndexLine: () => renderIndexLine,
   renderLogEntry: () => renderLogEntry,
+  repoCacheDir: () => repoCacheDir,
   resolveAnchor: () => resolveAnchor,
   resolveHeads: () => resolveHeads,
   resolveHits: () => resolveHits,
@@ -147,8 +150,8 @@ module.exports = __toCommonJS(index_exports);
 
 // src/kb-store.ts
 var import_node_crypto2 = require("crypto");
-var import_promises3 = require("fs/promises");
-var import_node_path3 = require("path");
+var import_promises4 = require("fs/promises");
+var import_node_path4 = require("path");
 
 // src/concurrency.ts
 var DEFAULT_IO_CONCURRENCY = 16;
@@ -230,16 +233,17 @@ var kbAnchorSchema = import_zod.z.object({
    * (`https://github.com/org/name`) or a short name. Absent means the base's
    * own repository, which is what nearly every anchor means.
    *
-   * Unvalidated beyond not-blank: one repository has many spellings.
-   * Matched after normalisation; see ARCHITECTURE.
+   * Unvalidated beyond not-blank: one repository has many spellings, matched
+   * after normalisation. Only a full URL can be fetched from, so `validate`
+   * warns on a short one; see ARCHITECTURE.
    */
   repo: import_zod.z.string().trim().min(1).optional(),
   /**
    * The git rev the evidence was taken at. Prefer a commit SHA: a branch
    * name is a moving pointer, so an anchor pinned to one says the evidence
    * came from wherever that branch happens to be now, which is not a
-   * baseline. Recorded and preserved in v1; ref-pinned reads land with
-   * SAA-709.
+   * baseline. A foreign anchor is checked at this rev, and compared against
+   * the remote's default branch on top of it.
    */
   ref: import_zod.z.string().trim().min(1).optional(),
   hash: import_zod.z.string().regex(/^sha256:[0-9a-f]{64}$/, {
@@ -517,6 +521,436 @@ function indexIsStale(stored, expected) {
   return stored !== expected;
 }
 
+// src/remote-repo/cache.ts
+var import_node_os = require("os");
+var import_node_path = require("path");
+
+// src/anchor-resolver/repo-identity.ts
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+function normalizeRepoUrl(value) {
+  let url = value.trim().replace(/^git\+/, "");
+  const scp = /^[\w.-]+@([\w.-]+):(.+)$/.exec(url);
+  if (scp) url = `https://${scp[1]}/${scp[2]}`;
+  url = url.replace(/^ssh:\/\/(?:[^@/]+@)?/, "https://");
+  url = trimTrailingSlashes(url);
+  if (url.endsWith(".git")) url = url.slice(0, -4);
+  return trimTrailingSlashes(url).toLowerCase();
+}
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}
+function isCanonicalRepoUrl(value) {
+  return /^[a-z0-9+.-]+:\/\//.test(normalizeRepoUrl(value));
+}
+function repoPath(normalized) {
+  const withoutScheme = normalized.replace(/^[a-z0-9+.-]+:\/\//, "");
+  const segments = withoutScheme.split("/").filter(Boolean);
+  return segments.length > 1 ? segments.slice(1).join("/") : "";
+}
+function repoIdentifies(declared, originUrl) {
+  if (!originUrl) return false;
+  const origin = normalizeRepoUrl(originUrl);
+  const want = normalizeRepoUrl(declared);
+  if (!want || !origin) return false;
+  if (want === origin) return true;
+  const path = repoPath(origin);
+  if (!path) return false;
+  return want === path || want === (path.split("/").pop() ?? "");
+}
+async function repoOriginUrl(repoRoot) {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", repoRoot, "config", "--get", "remote.origin.url"],
+      { timeout: 5e3 }
+    );
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+var LazyOrigin = class {
+  constructor(repoRoot) {
+    this.repoRoot = repoRoot;
+  }
+  repoRoot;
+  url = null;
+  asked = false;
+  /** Asks git once, so later `isForeign` calls need no await. */
+  async prime() {
+    if (this.asked) return;
+    this.url = await repoOriginUrl(this.repoRoot);
+    this.asked = true;
+  }
+  /** Only meaningful after `prime`; an unprimed origin identifies nothing. */
+  isForeign(anchor) {
+    if (!anchor.repo) return false;
+    return !repoIdentifies(anchor.repo, this.url);
+  }
+  async foreign(anchor) {
+    if (!anchor.repo) return false;
+    await this.prime();
+    return this.isForeign(anchor);
+  }
+};
+
+// src/remote-repo/cache.ts
+function repoCacheDir(override) {
+  return override ?? process.env["STRAUSS_KB_REPO_CACHE"] ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".strauss", "repo-cache");
+}
+var DEFAULT_FETCH_TIMEOUT_MS = 3e4;
+function fetchTimeoutMs(override) {
+  if (override !== void 0) return override;
+  const fromEnv = Number(process.env["STRAUSS_KB_FETCH_TIMEOUT_MS"]);
+  return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : DEFAULT_FETCH_TIMEOUT_MS;
+}
+function cachePathFor(repo, cacheDir) {
+  const normalized = normalizeRepoUrl(repo);
+  const scheme = /^[a-z0-9+.-]+:\/\//.exec(normalized);
+  if (!scheme) return null;
+  const segments = normalized.slice(scheme[0].length).split("/").filter(Boolean).map((segment) => safeSegment(segment));
+  if (segments.length < 2 || segments.some((segment) => segment === null)) {
+    return null;
+  }
+  const path = segments;
+  return (0, import_node_path.join)(cacheDir, ...path.slice(0, -1), `${path[path.length - 1]}.git`);
+}
+function safeSegment(value) {
+  return value === "." || value === ".." || value.includes("\0") ? null : value.replace(/[/\\:]/g, "-");
+}
+function revRef(rev) {
+  const safe = rev.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 64);
+  let hash = 5381;
+  for (let at = 0; at < rev.length; at++) {
+    hash = (hash * 33 ^ rev.charCodeAt(at)) >>> 0;
+  }
+  return `refs/strauss/${safe}-${hash.toString(16)}`;
+}
+
+// src/remote-repo/model.ts
+var UNCHECKED_REASONS = [
+  "remote-unreachable",
+  "repo-unauthorized",
+  "default-branch-unknown"
+];
+function isUncheckedReason(reason) {
+  return reason !== void 0 && UNCHECKED_REASONS.includes(reason);
+}
+function wantKey(repo, ref, file) {
+  return `${repo}\0${ref ?? ""}\0${file}`;
+}
+
+// src/remote-repo/read.ts
+var import_promises = require("fs/promises");
+
+// src/remote-repo/git.ts
+var import_node_child_process2 = require("child_process");
+var import_node_util2 = require("util");
+
+// src/anchor-resolver/model.ts
+var MAX_ANCHOR_FILE_BYTES = 1048576;
+
+// src/remote-repo/git.ts
+var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+function childEnv() {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+  for (const name of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"]) {
+    delete env[name];
+  }
+  return env;
+}
+async function git(args, options = {}) {
+  try {
+    const { stdout, stderr } = await execFileAsync2("git", args, {
+      ...options.cwd ? { cwd: options.cwd } : {},
+      timeout: options.timeoutMs ?? 3e4,
+      maxBuffer: options.maxBytes ?? MAX_ANCHOR_FILE_BYTES,
+      encoding: "utf8",
+      windowsHide: true,
+      env: childEnv()
+    });
+    return { ok: true, stdout, stderr, overflowed: false };
+  } catch (error) {
+    const failure = error;
+    return {
+      ok: false,
+      stdout: failure.stdout ?? "",
+      stderr: failure.stderr ?? "",
+      overflowed: failure.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+    };
+  }
+}
+function transportReason(stderr) {
+  const text = stderr.toLowerCase();
+  if (text.includes("authentication failed") || text.includes("permission denied") || text.includes("could not read username") || text.includes("403 forbidden") || text.includes("access denied")) {
+    return "repo-unauthorized";
+  }
+  if (text.includes("couldn't find remote ref") || text.includes("unadvertised object") || text.includes("not our ref")) {
+    return "ref-not-found";
+  }
+  return "remote-unreachable";
+}
+
+// src/remote-repo/validate.ts
+var MAX_REF_LENGTH = 200;
+var REF_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+function refShapeIsSafe(ref) {
+  if (!ref || ref.length > MAX_REF_LENGTH) return false;
+  if (ref.includes("..")) return false;
+  return REF_SHAPE.test(ref);
+}
+async function refIsWellFormed(ref) {
+  if (!refShapeIsSafe(ref)) return false;
+  const checked = await git(["check-ref-format", "--allow-onelevel", ref]);
+  return checked.ok;
+}
+function filePathIsSafe(file) {
+  const path = file.replace(/^\.\//, "");
+  if (!path || path.startsWith("-") || path.includes("\0")) return false;
+  return !path.split("/").includes("..");
+}
+var DEFAULT_PROTOCOLS = ["https", "ssh", "git"];
+function allowedProtocols() {
+  const raw = process.env["STRAUSS_KB_REPO_PROTOCOLS"];
+  if (raw === void 0) return [...DEFAULT_PROTOCOLS];
+  const listed = raw.split(",").map((entry) => entry.trim().toLowerCase()).filter(Boolean);
+  return listed.length ? listed : [...DEFAULT_PROTOCOLS];
+}
+function isShortRepoName(repo) {
+  return /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(repo.trim());
+}
+var SCP_LIKE = /^[\w.-]+@[\w.-]+:(?!\/)\S+$/;
+var URL_SCHEME = /^([A-Za-z0-9+.-]+):\/\//;
+var CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+function repoUrlIsSafe(repo) {
+  const url = repo.trim();
+  if (!url || url.startsWith("-") || CONTROL_CHARS.test(url)) return false;
+  const allowed = allowedProtocols();
+  if (SCP_LIKE.test(url)) return allowed.includes("ssh");
+  const scheme = URL_SCHEME.exec(url);
+  if (!scheme?.[1]) return false;
+  if (!allowed.includes(scheme[1].toLowerCase())) return false;
+  const authority = url.slice(scheme[0].length).split("/")[0] ?? "";
+  const at = authority.lastIndexOf("@");
+  return at < 0 || !authority.slice(0, at).includes(":");
+}
+function protocolArgs() {
+  const allowed = allowedProtocols();
+  return [
+    "-c",
+    "protocol.ext.allow=never",
+    "-c",
+    `protocol.file.allow=${allowed.includes("file") ? "user" : "never"}`
+  ];
+}
+
+// src/remote-repo/read.ts
+var DEFAULT_REPO_CONCURRENCY = 4;
+var IMMUTABLE_REV = /^[0-9a-f]{40}$/;
+async function readRemoteAnchors(wants, options = {}) {
+  const out = /* @__PURE__ */ new Map();
+  if (!wants.length) return out;
+  const cacheDir = repoCacheDir(options.cacheDir);
+  const timeoutMs = fetchTimeoutMs(options.fetchTimeoutMs);
+  const byRepo = /* @__PURE__ */ new Map();
+  for (const want of wants) {
+    const key2 = normalizeRepoUrl(want.repo);
+    const group2 = byRepo.get(key2) ?? { url: want.repo.trim(), wants: [] };
+    group2.wants.push(want);
+    byRepo.set(key2, group2);
+  }
+  const groups = [...byRepo.entries()];
+  const results = await mapLimit(
+    groups,
+    Math.max(1, options.concurrency ?? DEFAULT_REPO_CONCURRENCY),
+    ([repo, group2]) => readOneRepo(repo, group2.url, group2.wants, {
+      cacheDir,
+      timeoutMs,
+      offline: options.offline === true
+    })
+  );
+  for (const result of results) {
+    for (const [key2, read] of result) out.set(key2, read);
+  }
+  return out;
+}
+async function readOneRepo(repo, url, declared, context) {
+  let wants = declared;
+  const all = (read) => new Map(wants.map((want) => [wantKey(repo, want.ref, want.file), read]));
+  if (isShortRepoName(url)) {
+    return all({ ok: false, reason: "remote-unreachable" });
+  }
+  if (!repoUrlIsSafe(url)) return all({ ok: false, reason: "repo-invalid" });
+  const cache = cachePathFor(repo, context.cacheDir);
+  if (!cache) return all({ ok: false, reason: "remote-unreachable" });
+  const rejected = /* @__PURE__ */ new Map();
+  const usable = [];
+  for (const want of wants) {
+    const reason = wantReason(want);
+    if (reason)
+      rejected.set(wantKey(repo, want.ref, want.file), { ok: false, reason });
+    else usable.push(want);
+  }
+  if (!usable.length) return rejected;
+  wants = usable;
+  const opened = await openCache(cache, url, context);
+  if (opened) return new Map([...rejected, ...all(opened)]);
+  const wantsDefault = wants.some((want) => want.ref === void 0);
+  const branch = wantsDefault ? await defaultBranch(cache, context) : {};
+  const revs = /* @__PURE__ */ new Map();
+  for (const rev of distinctRevs(wants, branch.name)) {
+    revs.set(
+      rev,
+      await refIsWellFormed(rev) ? await ensureRev(cache, rev, context) : { ok: false, reason: "ref-invalid" }
+    );
+  }
+  const reads = await mapLimit(
+    wants,
+    DEFAULT_IO_CONCURRENCY,
+    async (want) => {
+      const rev = want.ref ?? branch.name;
+      if (rev === void 0) {
+        return {
+          ok: false,
+          reason: branch.reason ?? "default-branch-unknown"
+        };
+      }
+      const failed = revs.get(rev);
+      if (failed) return failed;
+      return readBlob(cache, rev, want.file, context);
+    }
+  );
+  return new Map([
+    ...rejected,
+    ...wants.map(
+      (want, at) => [wantKey(repo, want.ref, want.file), reads[at]]
+    )
+  ]);
+}
+function wantReason(want) {
+  if (want.ref !== void 0 && !refShapeIsSafe(want.ref)) return "ref-invalid";
+  return filePathIsSafe(want.file) ? void 0 : "outside-repo";
+}
+function distinctRevs(wants, branch) {
+  const revs = /* @__PURE__ */ new Set();
+  for (const want of wants) {
+    if (want.ref !== void 0) revs.add(want.ref);
+    else if (branch) revs.add(branch);
+  }
+  return [...revs];
+}
+async function openCache(cache, url, context) {
+  try {
+    await (0, import_promises.mkdir)(cache, { recursive: true });
+  } catch {
+    return { ok: false, reason: "remote-unreachable" };
+  }
+  const init = await git(["init", "--bare", "--quiet", cache], {
+    timeoutMs: context.timeoutMs
+  });
+  if (!init.ok) return { ok: false, reason: "remote-unreachable" };
+  const remote = await git(["config", "remote.origin.url", url], {
+    cwd: cache,
+    timeoutMs: context.timeoutMs
+  });
+  return remote.ok ? void 0 : { ok: false, reason: "remote-unreachable" };
+}
+async function defaultBranch(cache, context) {
+  if (!context.offline) {
+    const listed = await git(
+      [...protocolArgs(), "ls-remote", "--symref", "origin", "HEAD"],
+      {
+        cwd: cache,
+        timeoutMs: context.timeoutMs
+      }
+    );
+    const found = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m.exec(listed.stdout);
+    if (listed.ok && found?.[1]) {
+      const name = found[1];
+      await git(["config", "strauss.defaultBranch", name], { cwd: cache });
+      return { name };
+    }
+    if (!listed.ok) {
+      const reason = transportReason(listed.stderr);
+      if (reason !== "ref-not-found") {
+        const cached2 = await cachedBranch(cache);
+        return cached2 ? { name: cached2 } : { reason };
+      }
+    }
+  }
+  const cached = await cachedBranch(cache);
+  if (cached) return { name: cached };
+  return {
+    reason: context.offline ? "remote-unreachable" : "default-branch-unknown"
+  };
+}
+async function cachedBranch(cache) {
+  const stored = await git(["config", "--get", "strauss.defaultBranch"], {
+    cwd: cache
+  });
+  if (stored.ok && stored.stdout.trim()) return stored.stdout.trim();
+  const head = await git(
+    ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+    {
+      cwd: cache
+    }
+  );
+  const name = head.stdout.trim().replace(/^origin\//, "");
+  return head.ok && name ? name : void 0;
+}
+async function ensureRev(cache, rev, context) {
+  const ref = revRef(rev);
+  const have = await git(
+    ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`],
+    {
+      cwd: cache
+    }
+  );
+  const cached = have.ok && have.stdout.trim().length > 0;
+  if (cached && (context.offline || IMMUTABLE_REV.test(rev))) return void 0;
+  if (context.offline) return { ok: false, reason: "remote-unreachable" };
+  const fetched = await git(
+    [
+      ...protocolArgs(),
+      "fetch",
+      "--depth",
+      "1",
+      "origin",
+      "--end-of-options",
+      rev
+    ],
+    { cwd: cache, timeoutMs: context.timeoutMs }
+  );
+  if (!fetched.ok) {
+    const reason = transportReason(fetched.stderr);
+    if (cached && reason !== "ref-not-found") return void 0;
+    return { ok: false, reason };
+  }
+  const head = await git(["rev-parse", "FETCH_HEAD"], { cwd: cache });
+  const sha = head.stdout.trim();
+  if (!head.ok || !sha) return { ok: false, reason: "remote-unreachable" };
+  const updated = await git(["update-ref", ref, sha], { cwd: cache });
+  return updated.ok ? void 0 : { ok: false, reason: "remote-unreachable" };
+}
+async function readBlob(cache, rev, file, context) {
+  const path = file.replace(/^\.\//, "");
+  const blob = await git(
+    ["cat-file", "blob", "--end-of-options", `${revRef(rev)}:${path}`],
+    {
+      cwd: cache,
+      timeoutMs: context.timeoutMs
+    }
+  );
+  if (blob.ok) return { ok: true, source: blob.stdout };
+  if (blob.overflowed) return { ok: false, reason: "file-too-large" };
+  const text = blob.stderr.toLowerCase();
+  return text.includes("does not exist") || text.includes("not a valid object") ? { ok: false, reason: "file-missing" } : { ok: false, reason: "file-unreadable" };
+}
+
 // src/adjudicate.ts
 var STANDING = {
   accepted: "current",
@@ -557,23 +991,34 @@ function adjudicate(hits, bundle, now = /* @__PURE__ */ new Date(), anchorDrift)
     if (!record.frontmatter.verified?.length) {
       warnings.push({ kind: "unverified" });
     }
-    const moved = (anchorDrift?.get(record.conceptId) ?? []).filter(
-      (entry) => entry.state !== "match" && entry.reason !== "foreign-repo"
+    const found = (anchorDrift?.get(record.conceptId) ?? []).filter(
+      (entry) => entry.state !== "match"
     );
+    const unchecked2 = found.filter((entry) => isUncheckedReason(entry.reason));
+    const moved = found.filter((entry) => !isUncheckedReason(entry.reason));
     if (moved.length) {
+      warnings.push({ kind: "drifted", anchors: moved.map(warningAnchor) });
+    }
+    if (unchecked2.length) {
       warnings.push({
-        kind: "drifted",
-        anchors: moved.map(({ file, symbol, diffSize, reason }) => ({
-          file,
-          ...symbol !== void 0 ? { symbol } : {},
-          diffSize,
-          ...reason !== void 0 ? { reason } : {}
-        }))
+        kind: "unchecked",
+        anchors: unchecked2.map(warningAnchor)
       });
     }
     return { record, standing: STANDING[status], heads, warnings };
   });
 }
+function warningAnchor(entry) {
+  const { file, symbol, diffSize, reason, repo, remoteState } = entry;
+  return {
+    file,
+    ...symbol !== void 0 ? { symbol } : {},
+    diffSize,
+    ...reason !== void 0 ? { reason } : {},
+    ...repo !== void 0 ? { repo } : {},
+    ...remoteState !== void 0 ? { remoteState } : {}
+  };
+}
 function resolveHeads(from, byId) {
   const warnings = [];
   const heads = /* @__PURE__ */ new Map();
@@ -623,14 +1068,98 @@ function successors(record, byId) {
   return { records, missing };
 }
 
-// src/anchor-resolver.ts
-var import_node_child_process = require("child_process");
+// src/anchor-resolver/read.ts
+var import_promises2 = require("fs/promises");
+var import_node_path2 = require("path");
+function anchorFilePath(repoRoot, file) {
+  const path = (0, import_node_path2.resolve)(repoRoot, file.replace(/^\.\//, ""));
+  const rel = (0, import_node_path2.relative)((0, import_node_path2.resolve)(repoRoot), path);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${import_node_path2.sep}`) || (0, import_node_path2.isAbsolute)(rel)) {
+    return null;
+  }
+  return path;
+}
+function contains(root, path) {
+  const rel = (0, import_node_path2.relative)(root, path);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${import_node_path2.sep}`) && !(0, import_node_path2.isAbsolute)(rel);
+}
+function errorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+function anchorFileReader(repoRoot) {
+  let rootOnce;
+  const realRoot = () => {
+    rootOnce ??= (0, import_promises2.realpath)((0, import_node_path2.resolve)(repoRoot)).catch((error) => {
+      rootOnce = void 0;
+      throw error;
+    });
+    return rootOnce;
+  };
+  return (file) => readAnchorFileWithRoot(repoRoot, file, realRoot);
+}
+async function readAnchorFileWithRoot(repoRoot, file, realRoot) {
+  const lexical = anchorFilePath(repoRoot, file);
+  if (lexical === null) return { ok: false, reason: "outside-repo" };
+  let root;
+  let path;
+  try {
+    root = await realRoot();
+    path = await (0, import_promises2.realpath)(lexical);
+  } catch (error) {
+    const code = errorCode(error);
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { ok: false, reason: "file-missing" };
+    }
+    return { ok: false, reason: "file-unreadable" };
+  }
+  if (!contains(root, path)) return { ok: false, reason: "outside-repo" };
+  try {
+    const stats = await (0, import_promises2.stat)(path);
+    if (!stats.isFile()) return { ok: false, reason: "file-unreadable" };
+    if (stats.size > MAX_ANCHOR_FILE_BYTES) {
+      return { ok: false, reason: "file-too-large" };
+    }
+    return { ok: true, source: await (0, import_promises2.readFile)(path, "utf8") };
+  } catch (error) {
+    const code = errorCode(error);
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { ok: false, reason: "file-missing" };
+    }
+    return { ok: false, reason: "file-unreadable" };
+  }
+}
+function looksLikeWrongRepoRoot(drift) {
+  let checked = 0;
+  for (const entries of drift.values()) {
+    for (const entry of entries) {
+      if (entry.repo !== void 0) continue;
+      checked += 1;
+      if (entry.state !== "unresolved" || entry.reason !== "file-missing") {
+        return false;
+      }
+    }
+  }
+  return checked > 0;
+}
+async function readAnchorFiles(files, read, concurrency = DEFAULT_IO_CONCURRENCY) {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new RangeError(
+      `readAnchorFiles: option "concurrency" must be a positive integer, got ${concurrency}`
+    );
+  }
+  const wanted = [...new Set(files)];
+  const results = await mapLimit(wanted, concurrency, async (file) => {
+    try {
+      return await read(file);
+    } catch {
+      return { ok: false, reason: "file-unreadable" };
+    }
+  });
+  return new Map(wanted.map((file, at) => [file, results[at]]));
+}
+
+// src/anchor-resolver/resolver.ts
 var import_node_crypto = require("crypto");
-var import_promises = require("fs/promises");
-var import_node_path = require("path");
-var import_node_util = require("util");
-var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
-var MAX_ANCHOR_FILE_BYTES = 1048576;
 var PARENT_SCOPE_LINES = 50;
 var CLEAN_STATE = { blockComment: false, template: false };
 function stripLine(line, state) {
@@ -806,157 +1335,8 @@ function resolveAnchor(source, anchor, resolver = regexResolver) {
   }
   return resolver.resolve(normalized, anchor.symbol);
 }
-function anchorFilePath(repoRoot, file) {
-  const path = (0, import_node_path.resolve)(repoRoot, file.replace(/^\.\//, ""));
-  const rel = (0, import_node_path.relative)((0, import_node_path.resolve)(repoRoot), path);
-  if (rel === "" || rel === ".." || rel.startsWith(`..${import_node_path.sep}`) || (0, import_node_path.isAbsolute)(rel)) {
-    return null;
-  }
-  return path;
-}
-function contains(root, path) {
-  const rel = (0, import_node_path.relative)(root, path);
-  return rel !== "" && rel !== ".." && !rel.startsWith(`..${import_node_path.sep}`) && !(0, import_node_path.isAbsolute)(rel);
-}
-function normalizeRepoUrl(value) {
-  let url = value.trim().replace(/^git\+/, "");
-  const scp = /^[\w.-]+@([\w.-]+):(.+)$/.exec(url);
-  if (scp) url = `https://${scp[1]}/${scp[2]}`;
-  url = url.replace(/^ssh:\/\/(?:[^@/]+@)?/, "https://");
-  url = trimTrailingSlashes(url);
-  if (url.endsWith(".git")) url = url.slice(0, -4);
-  return trimTrailingSlashes(url).toLowerCase();
-}
-function trimTrailingSlashes(value) {
-  let end = value.length;
-  while (end > 0 && value[end - 1] === "/") end -= 1;
-  return value.slice(0, end);
-}
-function repoPath(normalized) {
-  const withoutScheme = normalized.replace(/^[a-z0-9+.-]+:\/\//, "");
-  const segments = withoutScheme.split("/").filter(Boolean);
-  return segments.length > 1 ? segments.slice(1).join("/") : "";
-}
-function repoIdentifies(declared, originUrl) {
-  if (!originUrl) return false;
-  const origin = normalizeRepoUrl(originUrl);
-  const want = normalizeRepoUrl(declared);
-  if (!want || !origin) return false;
-  if (want === origin) return true;
-  const path = repoPath(origin);
-  if (!path) return false;
-  return want === path || want === (path.split("/").pop() ?? "");
-}
-async function repoOriginUrl(repoRoot) {
-  try {
-    const { stdout } = await execFileAsync(
-      "git",
-      ["-C", repoRoot, "config", "--get", "remote.origin.url"],
-      { timeout: 5e3 }
-    );
-    return stdout.trim() || null;
-  } catch {
-    return null;
-  }
-}
-var LazyOrigin = class {
-  constructor(repoRoot) {
-    this.repoRoot = repoRoot;
-  }
-  repoRoot;
-  url = null;
-  asked = false;
-  /** Asks git once, so later `isForeign` calls need no await. */
-  async prime() {
-    if (this.asked) return;
-    this.url = await repoOriginUrl(this.repoRoot);
-    this.asked = true;
-  }
-  /** Only meaningful after `prime`; an unprimed origin identifies nothing. */
-  isForeign(anchor) {
-    if (!anchor.repo) return false;
-    return !repoIdentifies(anchor.repo, this.url);
-  }
-  async foreign(anchor) {
-    if (!anchor.repo) return false;
-    await this.prime();
-    return this.isForeign(anchor);
-  }
-};
-function errorCode(error) {
-  return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
-}
-function anchorFileReader(repoRoot) {
-  let rootOnce;
-  const realRoot = () => {
-    rootOnce ??= (0, import_promises.realpath)((0, import_node_path.resolve)(repoRoot)).catch((error) => {
-      rootOnce = void 0;
-      throw error;
-    });
-    return rootOnce;
-  };
-  return (file) => readAnchorFileWithRoot(repoRoot, file, realRoot);
-}
-async function readAnchorFileWithRoot(repoRoot, file, realRoot) {
-  const lexical = anchorFilePath(repoRoot, file);
-  if (lexical === null) return { ok: false, reason: "outside-repo" };
-  let root;
-  let path;
-  try {
-    root = await realRoot();
-    path = await (0, import_promises.realpath)(lexical);
-  } catch (error) {
-    const code = errorCode(error);
-    if (code === "ENOENT" || code === "ENOTDIR") {
-      return { ok: false, reason: "file-missing" };
-    }
-    return { ok: false, reason: "file-unreadable" };
-  }
-  if (!contains(root, path)) return { ok: false, reason: "outside-repo" };
-  try {
-    const stats = await (0, import_promises.stat)(path);
-    if (!stats.isFile()) return { ok: false, reason: "file-unreadable" };
-    if (stats.size > MAX_ANCHOR_FILE_BYTES) {
-      return { ok: false, reason: "file-too-large" };
-    }
-    return { ok: true, source: await (0, import_promises.readFile)(path, "utf8") };
-  } catch (error) {
-    const code = errorCode(error);
-    if (code === "ENOENT" || code === "ENOTDIR") {
-      return { ok: false, reason: "file-missing" };
-    }
-    return { ok: false, reason: "file-unreadable" };
-  }
-}
-function looksLikeWrongRepoRoot(drift) {
-  let checked = 0;
-  for (const entries of drift.values()) {
-    for (const entry of entries) {
-      if (entry.reason === "foreign-repo") continue;
-      checked += 1;
-      if (entry.state !== "unresolved" || entry.reason !== "file-missing") {
-        return false;
-      }
-    }
-  }
-  return checked > 0;
-}
-async function readAnchorFiles(files, read, concurrency = DEFAULT_IO_CONCURRENCY) {
-  if (!Number.isInteger(concurrency) || concurrency < 1) {
-    throw new RangeError(
-      `readAnchorFiles: option "concurrency" must be a positive integer, got ${concurrency}`
-    );
-  }
-  const wanted = [...new Set(files)];
-  const results = await mapLimit(wanted, concurrency, async (file) => {
-    try {
-      return await read(file);
-    } catch {
-      return { ok: false, reason: "file-unreadable" };
-    }
-  });
-  return new Map(wanted.map((file, at) => [file, results[at]]));
-}
+
+// src/anchor-resolver/drift.ts
 async function detectAnchorDrift(records, options = {}) {
   const repoRoot = options.repoRoot ?? process.cwd();
   const resolver = options.resolver ?? regexResolver;
@@ -982,71 +1362,101 @@ async function detectAnchorDrift(records, options = {}) {
     }
   }
   const files = [];
+  const wants = [];
   for (const entries of planned.values()) {
-    for (const entry of entries) {
-      if (!entry.foreign) files.push(entry.anchor.file);
+    for (const { anchor, foreign } of entries) {
+      if (!foreign) files.push(anchor.file);
+      else wants.push(...remoteWants(anchor));
     }
   }
-  const reads = await readAnchorFiles(
-    files,
-    options.reader ?? anchorFileReader(repoRoot),
-    options.concurrency ?? DEFAULT_IO_CONCURRENCY
-  );
+  const [reads, remote] = await Promise.all([
+    readAnchorFiles(
+      files,
+      options.reader ?? anchorFileReader(repoRoot),
+      options.concurrency ?? DEFAULT_IO_CONCURRENCY
+    ),
+    (options.readRemote ?? readRemoteAnchors)(wants, options.remote ?? {})
+  ]);
   const drift = /* @__PURE__ */ new Map();
   for (const record of records) {
     const entries = [];
     for (const { anchor, foreign } of planned.get(record.conceptId) ?? []) {
-      const base = {
-        file: anchor.file,
-        ...anchor.symbol ? { symbol: anchor.symbol } : {},
-        storedHash: anchor.hash
-      };
-      if (foreign) {
-        entries.push({
-          ...base,
-          state: "unresolved",
-          diffSize: null,
-          reason: "foreign-repo"
-        });
-        continue;
-      }
-      const read = reads.get(anchor.file);
-      if (!read.ok) {
-        entries.push({
-          ...base,
-          state: "unresolved",
-          diffSize: null,
-          reason: read.reason
-        });
-        continue;
-      }
-      const resolved = resolveAnchor(read.source, anchor, resolver);
-      if (!resolved) {
-        entries.push({
-          ...base,
-          state: "unresolved",
-          diffSize: null,
-          reason: "symbol-not-found"
-        });
-        continue;
-      }
-      const currentHash = hashAnchorText(resolved.text);
-      const currentLines = resolved.endLine - resolved.startLine + 1;
-      entries.push({
-        ...base,
-        state: currentHash === anchor.hash ? "match" : "drifted",
-        currentHash,
-        diffSize: anchor.lines === void 0 ? null : Math.abs(currentLines - anchor.lines)
-      });
+      entries.push(
+        foreign ? remoteEntry(anchor, remote, resolver) : localEntry(anchor, reads.get(anchor.file), resolver)
+      );
     }
     if (entries.length) drift.set(record.conceptId, entries);
   }
   return drift;
 }
+function remoteWants(anchor) {
+  const repo = anchor.repo;
+  const wants = [{ repo, file: anchor.file }];
+  if (anchor.ref) wants.unshift({ repo, ref: anchor.ref, file: anchor.file });
+  return wants;
+}
+function base(anchor) {
+  return {
+    file: anchor.file,
+    ...anchor.symbol ? { symbol: anchor.symbol } : {},
+    storedHash: anchor.hash
+  };
+}
+function unresolved(anchor, reason, repo) {
+  return {
+    ...base(anchor),
+    state: "unresolved",
+    diffSize: null,
+    ...reason ? { reason } : {},
+    ...repo ? { repo } : {}
+  };
+}
+function hashIn(source, anchor, resolver) {
+  const resolved = resolveAnchor(source, anchor, resolver);
+  if (!resolved) return null;
+  return {
+    hash: hashAnchorText(resolved.text),
+    lines: resolved.endLine - resolved.startLine + 1
+  };
+}
+function compared(anchor, current, extra = {}) {
+  return {
+    ...base(anchor),
+    state: current.hash === anchor.hash ? "match" : "drifted",
+    currentHash: current.hash,
+    diffSize: anchor.lines === void 0 ? null : Math.abs(current.lines - anchor.lines),
+    ...extra
+  };
+}
+function localEntry(anchor, read, resolver) {
+  if (!read.ok) return unresolved(anchor, read.reason);
+  const current = hashIn(read.source, anchor, resolver);
+  return current ? compared(anchor, current) : unresolved(anchor, "symbol-not-found");
+}
+function remoteEntry(anchor, remote, resolver) {
+  const repo = anchor.repo;
+  const key2 = normalizeRepoUrl(repo);
+  const atDefault = remote.get(wantKey(key2, void 0, anchor.file));
+  const primary = anchor.ref ? remote.get(wantKey(key2, anchor.ref, anchor.file)) : atDefault;
+  if (!primary) return unresolved(anchor, "remote-unreachable", repo);
+  if (!primary.ok) return unresolved(anchor, primary.reason, repo);
+  const current = hashIn(primary.source, anchor, resolver);
+  if (!current) return unresolved(anchor, "symbol-not-found", repo);
+  if (!anchor.ref) return compared(anchor, current, { repo });
+  if (current.hash !== anchor.hash) {
+    return compared(anchor, current, { repo, remoteState: "drifted-from-ref" });
+  }
+  const head = atDefault?.ok ? hashIn(atDefault.source, anchor, resolver) : null;
+  return head && head.hash !== anchor.hash ? {
+    ...compared(anchor, head, { repo }),
+    state: "drifted",
+    remoteState: "drifted-on-default"
+  } : compared(anchor, current, { repo, remoteState: "matches-ref" });
+}
 
 // src/search-index.ts
-var import_promises2 = require("fs/promises");
-var import_node_path2 = require("path");
+var import_promises3 = require("fs/promises");
+var import_node_path3 = require("path");
 
 // src/kb-log.ts
 var import_zod2 = require("zod");
@@ -1109,7 +1519,7 @@ async function searchBase(bundlePath2, query, options = {}) {
   let store = null;
   try {
     store = await qmd.createStore({
-      dbPath: (0, import_node_path2.join)(bundlePath2, SEARCH_INDEX_FILE),
+      dbPath: (0, import_node_path3.join)(bundlePath2, SEARCH_INDEX_FILE),
       config: {
         collections: {
           [COLLECTION]: {
@@ -1144,7 +1554,7 @@ async function searchBase(bundlePath2, query, options = {}) {
   }
 }
 async function isStale(bundlePath2) {
-  const indexAt = await (0, import_promises2.stat)((0, import_node_path2.join)(bundlePath2, SEARCH_INDEX_FILE)).then((s) => s.mtimeMs).catch(() => 0);
+  const indexAt = await (0, import_promises3.stat)((0, import_node_path3.join)(bundlePath2, SEARCH_INDEX_FILE)).then((s) => s.mtimeMs).catch(() => 0);
   if (!indexAt) return true;
   const { readdir: readdir2 } = await import("fs/promises");
   const names = (await readdir2(bundlePath2).catch(() => [])).filter(
@@ -1153,7 +1563,7 @@ async function isStale(bundlePath2) {
   let stale = false;
   await mapLimit(names, DEFAULT_IO_CONCURRENCY, async (name) => {
     if (stale) return;
-    const at = await (0, import_promises2.stat)((0, import_node_path2.join)(bundlePath2, name)).then((s) => s.mtimeMs).catch(() => 0);
+    const at = await (0, import_promises3.stat)((0, import_node_path3.join)(bundlePath2, name)).then((s) => s.mtimeMs).catch(() => 0);
     if (at > indexAt) stale = true;
   });
   return stale;
@@ -1743,7 +2153,7 @@ function appendUnionMergeLine(contents) {
 }
 
 // src/kb-store.ts
-var KB_DIR = (0, import_node_path3.join)(".strauss", "kb");
+var KB_DIR = (0, import_node_path4.join)(".strauss", "kb");
 var STORE_OWNED = /* @__PURE__ */ new Set([INDEX_FILE, LOG_FILE, SEARCH_INDEX_FILE]);
 var DEFAULT_LOAD_BUDGET = 25e3;
 var KbStore = class {
@@ -1774,7 +2184,7 @@ var KbStore = class {
     const conceptId2 = `${input.type}.${input.slug}`;
     const root = this.root(bundlePath2);
     const target = this.recordPath(bundlePath2, conceptId2);
-    await (0, import_promises3.mkdir)(root, { recursive: true });
+    await (0, import_promises4.mkdir)(root, { recursive: true });
     await this.publish(
       target,
       stringifyMarkdownWithFrontmatter(input.body, frontmatter),
@@ -1813,7 +2223,7 @@ var KbStore = class {
     const target = this.recordPath(bundlePath2, conceptId2);
     let raw;
     try {
-      raw = await (0, import_promises3.readFile)(target, "utf8");
+      raw = await (0, import_promises4.readFile)(target, "utf8");
     } catch {
       return null;
     }
@@ -1830,7 +2240,7 @@ var KbStore = class {
     const root = this.root(bundlePath2);
     let names;
     try {
-      names = await (0, import_promises3.readdir)(root);
+      names = await (0, import_promises4.readdir)(root);
     } catch {
       return [];
     }
@@ -1838,7 +2248,7 @@ var KbStore = class {
     const records = await mapLimit(
       wanted,
       DEFAULT_IO_CONCURRENCY,
-      async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await (0, import_promises3.readFile)((0, import_node_path3.join)(root, name), "utf8"))
+      async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await (0, import_promises4.readFile)((0, import_node_path4.join)(root, name), "utf8"))
     );
     return records.filter((record) => record !== null);
   }
@@ -2006,7 +2416,8 @@ ${answer}
    * at the repo root, and the MCP server's cwd is the workspace.
    *
    * Public because `doctor` needs the same map with the same degradation: a
-   * sweep that failed to read the tree should report no drift, not fail.
+   * sweep that failed to read the tree should report no drift, not fail — and
+   * `offline: false` there, because a sweep is worth a fetch.
    *
    * When no root was given and not one anchored file was found, the finding is
    * discarded. A base read from somewhere other than the tree it describes
@@ -2018,10 +2429,13 @@ ${answer}
    * plausible, and the misses become findings again; an explicit `repoRoot` is
    * taken at its word either way.
    */
-  async detectDrift(records, repoRoot) {
+  async detectDrift(records, repoRoot, options = {}) {
     try {
       const drift = await detectAnchorDrift(records, {
-        repoRoot: repoRoot ?? process.cwd()
+        repoRoot: repoRoot ?? process.cwd(),
+        // Offline by default: a read path must never spend a network fetch per
+        // call. `doctor` and `anchor-resolve` are the verbs that go get it.
+        remote: { offline: options.offline !== false }
       });
       if (repoRoot === void 0 && looksLikeWrongRepoRoot(drift)) {
         this.logger.warn?.({
@@ -2139,11 +2553,11 @@ ${answer}
   async readIndex(bundlePath2) {
     const root = this.root(bundlePath2);
     const expected = renderIndex(await this.list(bundlePath2));
-    const stored = await (0, import_promises3.readFile)((0, import_node_path3.join)(root, INDEX_FILE), "utf8").catch(
+    const stored = await (0, import_promises4.readFile)((0, import_node_path4.join)(root, INDEX_FILE), "utf8").catch(
       () => null
     );
     if (indexIsStale(stored, expected)) {
-      await this.publish((0, import_node_path3.join)(root, INDEX_FILE), expected, true, INDEX_FILE);
+      await this.publish((0, import_node_path4.join)(root, INDEX_FILE), expected, true, INDEX_FILE);
       this.logger.info?.({
         operation: "kb.index.repair",
         bundlePath: root,
@@ -2160,8 +2574,8 @@ ${answer}
    * knows which agent touched what. So a bad line is surfaced and left alone.
    */
   async readLog(bundlePath2) {
-    const raw = await (0, import_promises3.readFile)(
-      (0, import_node_path3.join)(this.root(bundlePath2), LOG_FILE),
+    const raw = await (0, import_promises4.readFile)(
+      (0, import_node_path4.join)(this.root(bundlePath2), LOG_FILE),
       "utf8"
     ).catch(() => "");
     const result = parseLog(raw);
@@ -2212,14 +2626,14 @@ ${answer}
   }
   async mutate(bundlePath2, conceptId2, change, entry, changeBody = (body) => body) {
     const target = this.recordPath(bundlePath2, conceptId2);
-    const before = await (0, import_promises3.readFile)(target, "utf8").catch(() => null);
+    const before = await (0, import_promises4.readFile)(target, "utf8").catch(() => null);
     if (before === null) throw new KbRecordNotFoundError(conceptId2);
     const parsed = this.parse(conceptId2, before);
     if (!parsed) throw new KbRecordNotFoundError(conceptId2);
     const frontmatter = change(parsed.frontmatter);
     const body = changeBody(parsed.body);
     const contents = stringifyMarkdownWithFrontmatter(body, frontmatter);
-    const witness = await (0, import_promises3.readFile)(target, "utf8").catch(() => null);
+    const witness = await (0, import_promises4.readFile)(target, "utf8").catch(() => null);
     if (witness === null || digest(witness) !== digest(before)) {
       throw new KbWriteConflictError(conceptId2);
     }
@@ -2245,20 +2659,20 @@ ${answer}
    */
   async publish(target, contents, overwrite, conceptId2) {
     const staging = `${target}.${process.pid}.tmp`;
-    await (0, import_promises3.writeFile)(staging, contents, "utf8");
+    await (0, import_promises4.writeFile)(staging, contents, "utf8");
     try {
       if (overwrite) {
-        await (0, import_promises3.rename)(staging, target);
+        await (0, import_promises4.rename)(staging, target);
         return;
       }
-      await (0, import_promises3.link)(staging, target);
+      await (0, import_promises4.link)(staging, target);
     } catch (error) {
       if (error.code === "EEXIST") {
         throw new KbRecordAlreadyExistsError(conceptId2);
       }
       throw error;
     } finally {
-      await (0, import_promises3.unlink)(staging).catch(() => void 0);
+      await (0, import_promises4.unlink)(staging).catch(() => void 0);
     }
   }
   /**
@@ -2302,18 +2716,18 @@ ${answer}
    * file must not fail the mutation it guards.
    */
   async ensureGitattributes(root) {
-    const target = (0, import_node_path3.join)(root, GITATTRIBUTES_FILE);
+    const target = (0, import_node_path4.join)(root, GITATTRIBUTES_FILE);
     try {
       let existing;
       try {
-        existing = await (0, import_promises3.readFile)(target, "utf8");
+        existing = await (0, import_promises4.readFile)(target, "utf8");
       } catch (error) {
         if (error.code !== "ENOENT") throw error;
         existing = null;
       }
       if (existing === null) {
         try {
-          await (0, import_promises3.writeFile)(target, appendUnionMergeLine(""), {
+          await (0, import_promises4.writeFile)(target, appendUnionMergeLine(""), {
             encoding: "utf8",
             flag: "wx"
           });
@@ -2334,7 +2748,7 @@ ${answer}
         return;
       }
       if (!hasMergeDeclaration(existing)) {
-        await (0, import_promises3.appendFile)(target, appendUnionMergeLine(existing), "utf8");
+        await (0, import_promises4.appendFile)(target, appendUnionMergeLine(existing), "utf8");
         this.logger.info?.({
           operation: "kb.gitattributes.ensure",
           bundlePath: root,
@@ -2353,7 +2767,7 @@ ${answer}
   async record(root, entry) {
     await this.ensureGitattributes(root);
     const line = renderLogEntry({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry });
-    await (0, import_promises3.appendFile)((0, import_node_path3.join)(root, LOG_FILE), line, "utf8").catch((error) => {
+    await (0, import_promises4.appendFile)((0, import_node_path4.join)(root, LOG_FILE), line, "utf8").catch((error) => {
       this.logger.warn?.({
         operation: "kb.log.append",
         outcome: "failed",
@@ -2379,18 +2793,18 @@ ${answer}
     };
   }
   root(bundlePath2) {
-    return (0, import_node_path3.resolve)(bundlePath2);
+    return (0, import_node_path4.resolve)(bundlePath2);
   }
   // Concept ids are `<type>.<slug>` and map to a single file directly under the
   // bundle root; anything carrying a separator would escape it.
   recordPath(bundlePath2, conceptId2) {
-    if (conceptId2.includes(import_node_path3.sep) || conceptId2.includes("/")) {
+    if (conceptId2.includes(import_node_path4.sep) || conceptId2.includes("/")) {
       throw new KbInvalidConceptIdError(
         "concept id must not contain a path separator",
         { conceptId: conceptId2 }
       );
     }
-    return (0, import_node_path3.join)(this.root(bundlePath2), `${conceptId2}.md`);
+    return (0, import_node_path4.join)(this.root(bundlePath2), `${conceptId2}.md`);
   }
 };
 function estimateTokens(record) {
@@ -2619,18 +3033,18 @@ var KbBaseFrozenError = class extends Error {
 };
 
 // src/kb-pins/frozen.ts
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 
 // src/kb-pins/layers.ts
-var import_promises4 = require("fs/promises");
-var import_node_os = require("os");
-var import_node_path5 = require("path");
+var import_promises5 = require("fs/promises");
+var import_node_os2 = require("os");
+var import_node_path6 = require("path");
 
 // src/kb-pins/model.ts
-var import_node_path4 = require("path");
+var import_node_path5 = require("path");
 var import_zod4 = require("zod");
-var PINS_FILE = (0, import_node_path4.join)(".strauss", "kb-pins.json");
-var PINS_LOCAL_FILE = (0, import_node_path4.join)(".strauss", "kb-pins.local.json");
+var PINS_FILE = (0, import_node_path5.join)(".strauss", "kb-pins.json");
+var PINS_LOCAL_FILE = (0, import_node_path5.join)(".strauss", "kb-pins.local.json");
 var PIN_LAYERS = ["project", "local", "user"];
 var pinSchema = import_zod4.z.object({
   /** Relative to the manifest's root, so the file is committable. */
@@ -2677,13 +3091,13 @@ var pinsManifestSchema = import_zod4.z.object({
 
 // src/kb-pins/layers.ts
 function userRoot() {
-  return process.env.STRAUSS_KB_USER_ROOT || (0, import_node_os.homedir)();
+  return process.env.STRAUSS_KB_USER_ROOT || (0, import_node_os2.homedir)();
 }
 function layerRoot(workspaceDir, layer) {
-  return layer === "user" ? userRoot() : (0, import_node_path5.resolve)(workspaceDir);
+  return layer === "user" ? userRoot() : (0, import_node_path6.resolve)(workspaceDir);
 }
 function layerFile(workspaceDir, layer) {
-  return (0, import_node_path5.join)(
+  return (0, import_node_path6.join)(
     layerRoot(workspaceDir, layer),
     layer === "local" ? PINS_LOCAL_FILE : PINS_FILE
   );
@@ -2692,7 +3106,7 @@ async function readPinsLayer(workspaceDir, layer) {
   const file = layerFile(workspaceDir, layer);
   let raw;
   try {
-    raw = await (0, import_promises4.readFile)(file, "utf8");
+    raw = await (0, import_promises5.readFile)(file, "utf8");
   } catch {
     return { pins: [] };
   }
@@ -2716,16 +3130,16 @@ async function readPinsLayer(workspaceDir, layer) {
 }
 async function writePinsLayer(workspaceDir, layer, manifest) {
   const file = layerFile(workspaceDir, layer);
-  await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(file), { recursive: true });
-  await (0, import_promises4.writeFile)(file, `${JSON.stringify(manifest, null, 2)}
+  await (0, import_promises5.mkdir)((0, import_node_path6.dirname)(file), { recursive: true });
+  await (0, import_promises5.writeFile)(file, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
 }
 function resolvePinPath(rootDir, path) {
-  return (0, import_node_path5.isAbsolute)(path) ? (0, import_node_path5.resolve)(path) : (0, import_node_path5.resolve)(rootDir, path.split("/").join(import_node_path5.sep));
+  return (0, import_node_path6.isAbsolute)(path) ? (0, import_node_path6.resolve)(path) : (0, import_node_path6.resolve)(rootDir, path.split("/").join(import_node_path6.sep));
 }
 function storablePath(rootDir, bundlePath2) {
-  const rel = (0, import_node_path5.relative)((0, import_node_path5.resolve)(rootDir), (0, import_node_path5.resolve)(bundlePath2));
-  return (rel === "" ? "." : rel).split(import_node_path5.sep).join("/");
+  const rel = (0, import_node_path6.relative)((0, import_node_path6.resolve)(rootDir), (0, import_node_path6.resolve)(bundlePath2));
+  return (rel === "" ? "." : rel).split(import_node_path6.sep).join("/");
 }
 async function readMergedPins(workspaceDir) {
   const manifests = {};
@@ -2753,7 +3167,7 @@ async function readMergedPins(workspaceDir) {
 // src/kb-pins/frozen.ts
 async function assertBaseNotFrozen(workspaceDir, bundlePath2) {
   const merged = await readMergedPins(workspaceDir);
-  const absolute = (0, import_node_path6.resolve)(bundlePath2);
+  const absolute = (0, import_node_path7.resolve)(bundlePath2);
   const pin = merged.pins.find((entry) => entry.absolutePath === absolute);
   if (pin?.frozen === true) {
     throw new KbBaseFrozenError(pin.path, pin.layer);
@@ -2838,7 +3252,7 @@ async function pinBase(store, workspaceDir, bundlePath2, at, options = {}) {
 }
 
 // src/kb-pins/unpin.ts
-var import_node_path7 = require("path");
+var import_node_path8 = require("path");
 async function unpinBase(workspaceDir, bundlePath2) {
   const layers = [];
   for (const layer of PIN_LAYERS) {
@@ -2859,14 +3273,14 @@ async function unpinBase(workspaceDir, bundlePath2) {
     }
   }
   return {
-    path: storablePath((0, import_node_path7.resolve)(workspaceDir), bundlePath2),
+    path: storablePath((0, import_node_path8.resolve)(workspaceDir), bundlePath2),
     removed: layers.length > 0,
     layers
   };
 }
 
 // src/kb-context.ts
-var import_promises5 = require("fs/promises");
+var import_promises6 = require("fs/promises");
 var HEADING2 = "## Knowledge bases (pinned)";
 var DEFAULT_CONTEXT_BUDGET = 4e3;
 var CONTEXT_PROFILES = {
@@ -3025,7 +3439,7 @@ async function buildContext(store, workspaceDir, options = {}) {
       operation: "kb.context.refused",
       approxTokens: total,
       budgetTokens,
-      bases: bases.map((base) => base.path)
+      bases: bases.map((base2) => base2.path)
     });
     const refusal = [
       HEADING2,
@@ -3035,7 +3449,7 @@ async function buildContext(store, workspaceDir, options = {}) {
       "from a complete one. The pinned bases:",
       "",
       ...bases.map(
-        (base) => `- ${base.path} \u2014 ~${base.approxTokens} tokens (bundlePath: \`${base.absolutePath}\`)`
+        (base2) => `- ${base2.path} \u2014 ~${base2.approxTokens} tokens (bundlePath: \`${base2.absolutePath}\`)`
       ),
       "",
       "For the question at hand, read what you need now \u2014 `kb_load` a base",
@@ -3070,13 +3484,13 @@ function toHookJson(block, event) {
 var CONTEXT_BEGIN = "<!-- strauss-kb:begin -->";
 var CONTEXT_END = "<!-- strauss-kb:end -->";
 async function syncInstructions(file, block) {
-  const existing = await (0, import_promises5.readFile)(file, "utf8").catch(() => null);
+  const existing = await (0, import_promises6.readFile)(file, "utf8").catch(() => null);
   const region = block ? `${CONTEXT_BEGIN}
 ${block.trim()}
 ${CONTEXT_END}` : null;
   if (existing === null) {
     if (!region) return { file, action: "unchanged" };
-    await (0, import_promises5.writeFile)(file, `${region}
+    await (0, import_promises6.writeFile)(file, `${region}
 `, "utf8");
     return { file, action: "created" };
   }
@@ -3087,11 +3501,11 @@ ${CONTEXT_END}` : null;
     const after = existing.slice(end + CONTEXT_END.length);
     const next = region ? `${before}${region}${after}` : `${before.replace(/\n+$/, "\n")}${after.replace(/^\n+/, "\n")}`;
     if (next === existing) return { file, action: "unchanged" };
-    await (0, import_promises5.writeFile)(file, next, "utf8");
+    await (0, import_promises6.writeFile)(file, next, "utf8");
     return { file, action: region ? "replaced" : "removed" };
   }
   if (!region) return { file, action: "unchanged" };
-  await (0, import_promises5.writeFile)(
+  await (0, import_promises6.writeFile)(
     file,
     `${existing.replace(/\n*$/, "\n\n")}${region}
 `,
@@ -3250,6 +3664,16 @@ function validateBundle(records) {
         );
       }
     }
+    for (const anchor of fm.strauss_anchors ?? []) {
+      if (anchor.repo && !isCanonicalRepoUrl(anchor.repo)) {
+        report(
+          "anchor_repo",
+          conceptId2,
+          `anchor repo "${anchor.repo}" is not a full remote URL, so it cannot be resolved against a remote`,
+          "warning"
+        );
+      }
+    }
     if (fm.strauss_assumption && fm.sources?.length) {
       report("assumption", conceptId2, "marked an assumption but cites sources");
     }
@@ -3269,7 +3693,8 @@ var KB_DOCTOR_CHECKS = [
   "orphaned",
   "broken-supersession",
   "superseded-but-cited",
-  "drifted"
+  "drifted",
+  "unchecked"
 ];
 var CHECK_HEADLINES = {
   expired: "past its stale_after date",
@@ -3279,7 +3704,8 @@ var CHECK_HEADLINES = {
   orphaned: "no other record links to it",
   "broken-supersession": "the supersession pointers do not resolve",
   "superseded-but-cited": "a live record's body links to one that no longer holds",
-  drifted: "the code an anchor points at moved out from under its hash"
+  drifted: "the code an anchor points at moved out from under its hash",
+  unchecked: "an anchor in another repository nothing could reach"
 };
 var DAY_MS = 864e5;
 function doctor(bundle, options = {}) {
@@ -3304,7 +3730,8 @@ function doctor(bundle, options = {}) {
     group("orphaned", orphaned(bundle)),
     group("broken-supersession", brokenSupersession(bundle, adjudicated)),
     group("superseded-but-cited", supersededButCited(bundle, standings)),
-    group("drifted", drifted(inForce))
+    group("drifted", drifted(inForce)),
+    group("unchecked", unchecked(inForce))
   ];
   const counts = Object.fromEntries(
     groups.map((entry) => [entry.check, entry.count])
@@ -3491,21 +3918,38 @@ function supersededButCited(bundle, standings) {
   return findings;
 }
 function drifted(hits) {
+  return anchorFindings(
+    hits,
+    "drifted",
+    (count2) => count2 === 1 ? "anchor no longer matches" : "anchors no longer match"
+  );
+}
+function unchecked(hits) {
+  return anchorFindings(
+    hits,
+    "unchecked",
+    (count2) => count2 === 1 ? "anchor was not checked" : "anchors were not checked"
+  );
+}
+function anchorFindings(hits, kind, headline) {
   const findings = [];
   for (const hit of hits) {
-    const warning = hit.warnings.find((entry) => entry.kind === "drifted");
+    const warning = hit.warnings.find(
+      (entry) => entry.kind === kind
+    );
     if (!warning) continue;
+    const byRepo = /* @__PURE__ */ new Map();
+    for (const anchor of warning.anchors) {
+      const repo = anchor.repo ?? "";
+      byRepo.set(repo, [...byRepo.get(repo) ?? [], describeAnchor(anchor)]);
+    }
+    const detail = [...byRepo.entries()].map(
+      ([repo, entries]) => repo ? `${repo}: ${entries.join(", ")}` : entries.join(", ")
+    );
     findings.push(
       finding(
         hit.record,
-        `${warning.anchors.length} ${warning.anchors.length === 1 ? "anchor no longer matches" : "anchors no longer match"}: ${warning.anchors.map((anchor) => {
-          const at = anchor.symbol ? `${anchor.file}:${anchor.symbol}` : anchor.file;
-          if (anchor.reason) return `${at} (${anchor.reason})`;
-          if (anchor.diffSize === null) {
-            return `${at} (changed, size unrecorded)`;
-          }
-          return anchor.diffSize === 0 ? `${at} (content changed, same line count)` : `${at} (${anchor.diffSize} line${anchor.diffSize === 1 ? "" : "s"} apart)`;
-        }).join(", ")}`
+        `${warning.anchors.length} ${headline(warning.anchors.length)}: ${detail.join("; ")}`
       )
     );
   }
@@ -3513,6 +3957,15 @@ function drifted(hits) {
     (left, right) => left.conceptId.localeCompare(right.conceptId)
   );
 }
+function describeAnchor(anchor) {
+  const at = anchor.symbol ? `${anchor.file}:${anchor.symbol}` : anchor.file;
+  if (anchor.reason) return `${at} (${anchor.reason})`;
+  if (anchor.remoteState === "drifted-on-default") {
+    return `${at} (matches ref, moved on the default branch)`;
+  }
+  if (anchor.diffSize === null) return `${at} (changed, size unrecorded)`;
+  return anchor.diffSize === 0 ? `${at} (content changed, same line count)` : `${at} (${anchor.diffSize} line${anchor.diffSize === 1 ? "" : "s"} apart)`;
+}
 function replaces(later, earlier) {
   return (later.frontmatter.strauss_supersedes ?? []).includes(earlier.conceptId) || earlier.frontmatter.strauss_superseded_by === later.conceptId;
 }
@@ -3615,12 +4068,15 @@ function argvFlag(argv, name) {
 var anchorResolveCommand = define({
   name: "anchor-resolve",
   tool: "kb_anchor_resolve",
-  usage: "anchor-resolve <concept-id> [--repo-root <path>] [--rebaseline] [--restamp]",
-  description: "Resolve a record's anchors against the working tree: stamp a hash onto anchors that lack one, report drift where the code moved. kb_verify's mechanical counterpart \u2014 reach for it when the question is whether the code still is what it was, not whether the claim still holds. Anchors naming another repository are skipped. Exits non-zero on drift.",
+  usage: "anchor-resolve <concept-id> [--repo-root <path>] [--offline] [--rebaseline] [--restamp]",
+  description: "Resolve a record's anchors: stamp a hash onto anchors that lack one, report drift where the code moved. An anchor naming another repository is read from that remote through a bare cache; --offline uses the cache only. kb_verify's mechanical counterpart \u2014 reach for it when the question is whether the code still is what it was. Exits non-zero on drift.",
   input: import_zod8.z.object({
     bundlePath,
     conceptId,
     repoRoot: import_zod8.z.string().min(1).optional(),
+    offline: import_zod8.z.boolean().optional().describe(
+      "Resolve foreign anchors from the local repo cache only, never fetching."
+    ),
     rebaseline: import_zod8.z.boolean().optional().describe(
       "Accept the current code as the new baseline for anchors that drifted."
     ),
@@ -3632,10 +4088,11 @@ var anchorResolveCommand = define({
     bundlePath: path,
     conceptId: argv[1],
     repoRoot: argvFlag(argv, "--repo-root"),
+    offline: argv.includes("--offline"),
     rebaseline: argv.includes("--rebaseline"),
     restamp: argv.includes("--restamp")
   }),
-  run: async ({ store, actor, now }, { bundlePath: path, conceptId: id, repoRoot, rebaseline, restamp }) => {
+  run: async ({ store, actor, now }, { bundlePath: path, conceptId: id, repoRoot, offline, rebaseline, restamp }) => {
     const root = repoRoot ?? process.cwd();
     const record = await store.read(path, id);
     if (!record) throw new KbRecordNotFoundError(id);
@@ -3650,18 +4107,10 @@ var anchorResolveCommand = define({
     }
     const results = [];
     const updated = [];
-    const origin = new LazyOrigin(root);
     let dirty = false;
-    if (anchors.some((anchor) => anchor.repo)) await origin.prime();
-    const foreign = new Map(
-      anchors.map((anchor) => [anchor, origin.isForeign(anchor)])
-    );
-    const reads = await readAnchorFiles(
-      anchors.filter((anchor) => !foreign.get(anchor)).map((anchor) => anchor.file),
-      anchorFileReader(root)
-    );
+    const sources = await readSources(anchors, root, offline === true);
     for (const anchor of anchors) {
-      const base = {
+      const base2 = {
         file: anchor.file,
         ...anchor.symbol ? { symbol: anchor.symbol } : {},
         // Carried onto unresolved findings too: an anchor that once hashed
@@ -3669,21 +4118,17 @@ var anchorResolveCommand = define({
         // has to be able to tell it from one nobody ever stamped.
         ...anchor.hash ? { storedHash: anchor.hash } : {}
       };
-      if (foreign.get(anchor)) {
-        results.push({ ...base, state: "unresolved", reason: "foreign-repo" });
-        updated.push(anchor);
-        continue;
-      }
-      const fileRead = reads.get(anchor.file);
-      if (!fileRead.ok) {
-        results.push({ ...base, state: "unresolved", reason: fileRead.reason });
+      const source = sources.get(anchor);
+      if (source.repo) base2.repo = source.repo;
+      if (!source.ok) {
+        results.push({ ...base2, state: "unresolved", reason: source.reason });
         updated.push(anchor);
         continue;
       }
-      const resolved = resolveAnchor(fileRead.source, anchor);
+      const resolved = resolveAnchor(source.source, anchor);
       if (!resolved) {
         results.push({
-          ...base,
+          ...base2,
           state: "unresolved",
           reason: "symbol-not-found"
         });
@@ -3698,30 +4143,47 @@ var anchorResolveCommand = define({
         lines: currentLines,
         resolved_at: now()
       };
+      const pinned = anchor.ref !== void 0 && source.repo !== void 0;
       if (!anchor.hash) {
-        results.push({ ...base, state: "stamped", currentHash });
+        results.push({ ...base2, state: "stamped", currentHash });
         updated.push(stamped);
         dirty = true;
-      } else if (anchor.hash === currentHash) {
-        results.push({
-          ...base,
-          state: "match",
-          currentHash
-        });
-        const refresh = restamp || anchor.resolved_at === void 0;
-        updated.push(refresh ? { ...anchor, resolved_at: now() } : anchor);
-        if (refresh) dirty = true;
-      } else {
+        continue;
+      }
+      if (anchor.hash !== currentHash) {
         results.push({
-          ...base,
+          ...base2,
           state: "drifted",
           currentHash,
-          diffSize: anchor.lines === void 0 ? null : Math.abs(currentLines - anchor.lines),
+          diffSize: lineDelta(anchor, currentLines),
+          ...pinned ? { remoteState: "drifted-from-ref" } : {},
           ...rebaseline ? { rebaselined: true } : {}
         });
         updated.push(rebaseline ? stamped : anchor);
         if (rebaseline) dirty = true;
+        continue;
       }
+      const onDefault = pinned ? headHash(source, anchor) : void 0;
+      if (onDefault && onDefault.hash !== anchor.hash) {
+        results.push({
+          ...base2,
+          state: "drifted",
+          currentHash: onDefault.hash,
+          diffSize: lineDelta(anchor, onDefault.lines),
+          remoteState: "drifted-on-default"
+        });
+        updated.push(anchor);
+        continue;
+      }
+      results.push({
+        ...base2,
+        state: "match",
+        currentHash,
+        ...pinned ? { remoteState: "matches-ref" } : {}
+      });
+      const refresh = restamp || anchor.resolved_at === void 0;
+      updated.push(refresh ? { ...anchor, resolved_at: now() } : anchor);
+      if (refresh) dirty = true;
     }
     let frozen = false;
     if (dirty) {
@@ -3734,16 +4196,19 @@ var anchorResolveCommand = define({
       if (!frozen) await store.updateAnchors(path, id, updated, actor);
     }
     const frozenNote = frozen ? { frozen: true, note: "base is frozen: nothing was stamped" } : {};
-    const checked = results.filter((entry) => entry.reason !== "foreign-repo");
-    const skipped = results.length - checked.length;
-    const matches2 = checked.filter((entry) => entry.state === "match").length;
-    const clean = checked.length > 0 && checked.every((entry) => entry.state === "match");
+    const unreachable = results.filter(
+      (entry) => isUncheckedReason(entry.reason)
+    ).length;
+    const checked = results.length - unreachable;
+    const matches2 = results.filter((entry) => entry.state === "match").length;
+    const note = `${matches2}/${checked} anchors match${unreachable ? `, ${unreachable} unreachable` : ""}`;
+    const clean = checked > 0 && matches2 === checked && unreachable === 0;
     if (clean) {
       try {
         await store.verify(
           path,
           id,
-          `anchor-resolve: ${matches2}/${checked.length} anchors match${skipped ? `, ${skipped} in another repo` : ""} (regex resolver)`,
+          `anchor-resolve: ${note} (regex resolver)`,
           actor,
           now()
         );
@@ -3759,18 +4224,81 @@ var anchorResolveCommand = define({
       }
       return { conceptId: id, results, verified: true, ...frozenNote };
     }
-    return { conceptId: id, results, verified: false, ...frozenNote };
+    return {
+      conceptId: id,
+      results,
+      verified: false,
+      ...unreachable ? { note } : {},
+      ...frozenNote
+    };
   },
   // A stored hash that no longer resolves is a broken anchor, not an absence:
   // the file was deleted or the symbol renamed, and exiting zero on it would
   // let the one edit that destroys an anchor pass the gate that exists to
   // catch it. An anchor nobody ever stamped is still just unstamped, and one
-  // belonging to another repository was never this run's to check — failing CI
-  // on either would gate on work this command did not do.
+  // whose remote nothing could reach was never checked — failing CI on either
+  // would gate on work this command did not do.
   failsWhen: (result) => result.results.some(
-    (entry) => entry.state === "drifted" || entry.state === "unresolved" && entry.storedHash !== void 0 && entry.reason !== "foreign-repo"
+    (entry) => entry.state === "drifted" || entry.state === "unresolved" && entry.storedHash !== void 0 && !isUncheckedReason(entry.reason)
   )
 });
+function lineDelta(anchor, current) {
+  return anchor.lines === void 0 ? null : Math.abs(current - anchor.lines);
+}
+function headHash(source, anchor) {
+  if (source.head === void 0) return void 0;
+  const resolved = resolveAnchor(source.head, anchor);
+  if (!resolved) return void 0;
+  return {
+    hash: hashAnchorText(resolved.text),
+    lines: resolved.endLine - resolved.startLine + 1
+  };
+}
+async function readSources(anchors, root, offline) {
+  const origin = new LazyOrigin(root);
+  if (anchors.some((anchor) => anchor.repo)) await origin.prime();
+  const foreign = new Map(
+    anchors.map((anchor) => [anchor, origin.isForeign(anchor)])
+  );
+  const local = anchors.filter((anchor) => !foreign.get(anchor));
+  const remote = anchors.filter((anchor) => foreign.get(anchor));
+  const reads = await readAnchorFiles(
+    local.map((anchor) => anchor.file),
+    anchorFileReader(root)
+  );
+  const blobs = await readRemoteAnchors(remote.flatMap(remoteWants), {
+    offline
+  });
+  const sources = /* @__PURE__ */ new Map();
+  for (const anchor of local) {
+    const read = reads.get(anchor.file);
+    sources.set(
+      anchor,
+      read.ok ? { ok: true, source: read.source } : { ok: false, reason: read.reason }
+    );
+  }
+  for (const anchor of remote) {
+    const repo = anchor.repo;
+    const key2 = normalizeRepoUrl(repo);
+    const atDefault = blobs.get(wantKey(key2, void 0, anchor.file));
+    const primary = anchor.ref ? blobs.get(wantKey(key2, anchor.ref, anchor.file)) : atDefault;
+    if (!primary?.ok) {
+      sources.set(anchor, {
+        ok: false,
+        reason: primary?.ok === false ? primary.reason : "remote-unreachable",
+        repo
+      });
+      continue;
+    }
+    sources.set(anchor, {
+      ok: true,
+      source: primary.source,
+      repo,
+      ...anchor.ref && atDefault?.ok ? { head: atDefault.source } : {}
+    });
+  }
+  return sources;
+}
 
 // src/commands/answer.ts
 var import_zod9 = require("zod");
@@ -3778,7 +4306,7 @@ var answerCommand = define({
   name: "answer",
   tool: "kb_answer",
   usage: "answer <concept-id> <answer...>",
-  description: "Resolve an open question: sets the status, stamps who answered and when, and appends an Answer section. If the answer overturns an assumption or a decision, that is a supersession \u2014 do it explicitly.",
+  description: "Resolve an open question: set status, stamp who and when, append an Answer section. If the answer overturns a decision or assumption, supersede that record explicitly.",
   input: import_zod9.z.object({ bundlePath, conceptId, answer: import_zod9.z.string().min(1) }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -3873,7 +4401,7 @@ var contextCommand = define({
   name: "context",
   tool: "kb_context",
   usage: "context [--profile NAME] [--budget N] [--full-under N] [--format json] [--event NAME]",
-  description: "The pinned-base index block, for injection at every context birth \u2014 startup, clear, resume, and after compaction. An index, not the content: concept ids, titles and standing, with the bodies left behind kb_load at the point of use. Emits nothing when nothing is pinned. Refuses with the list of bases and their sizes rather than truncating past its budget. Budgets resolve most-specific-first: explicit flags, then the workspace manifests' `context` tables (per profile, over their `default`), then the built-in profile (session-start, compact, turn), then package defaults \u2014 so a repo tunes its own numbers in .strauss/kb-pins.json without touching hook commands. Like kb_schema and kb_types this takes no bundlePath \u2014 it reads the workspace pin manifests, because which bases a session should see is workspace state, not a property of one base.",
+  description: "Index block of pinned bases (ids, titles, standing) for injection at context birth. Takes no bundlePath \u2014 reads the workspace pin manifests. Empty when nothing is pinned; refuses over budget rather than truncating. Budget precedence: flags, then the manifest `context[profile]` over `context.default`, then the built-in profile, then package defaults.",
   input: import_zod12.z.object({
     budgetTokens: import_zod12.z.number().int().positive().optional().describe(
       "Ceiling on the whole emitted block; past it the command refuses with a list of bases rather than truncating. Defaults to 4000."
@@ -3928,8 +4456,8 @@ var days = (what, fallback) => import_zod13.z.number().int().positive().optional
 var doctorCommand = define({
   name: "doctor",
   tool: "kb_doctor",
-  usage: "doctor [--expiring-days N] [--unverified-days N] [--aging-days N] [--repo-root PATH] [--strict]",
-  description: "Read-only health sweep: expired, expiring, unverified, aging, orphaned, broken-supersession, superseded-but-cited, drifted anchors. Every group is reported even when empty; nothing is written or re-stamped. Use it when picking up a base you have not touched in a while; kb_validate only checks that pointers between records agree.",
+  usage: "doctor [--expiring-days N] [--unverified-days N] [--aging-days N] [--repo-root PATH] [--offline] [--strict]",
+  description: "Read-only health sweep: expired, expiring, unverified, aging, orphaned, broken-supersession, superseded-but-cited, drifted and unchecked anchors. Every group is reported even when empty; nothing is written or re-stamped. Use it when picking up a base you have not touched in a while; kb_validate only checks that pointers between records agree.",
   input: import_zod13.z.object({
     bundlePath,
     repoRoot: REPO_ROOT,
@@ -3945,6 +4473,9 @@ var doctorCommand = define({
       "How long a record may stay `open` or `proposed` before `aging` reports it, in days.",
       DEFAULT_AGING_DAYS
     ),
+    offline: import_zod13.z.boolean().optional().describe(
+      "Read foreign anchors from the local repo cache only, never fetching."
+    ),
     strict: import_zod13.z.boolean().optional().describe(
       "Turn an expired record into a non-zero exit for the CLI. No effect on the report itself."
     )
@@ -3964,13 +4495,23 @@ var doctorCommand = define({
       ...expiring2 !== void 0 ? { expiringDays: Number(expiring2) } : {},
       ...unverified2 !== void 0 ? { unverifiedDays: Number(unverified2) } : {},
       ...agingDays !== void 0 ? { agingDays: Number(agingDays) } : {},
+      ...argv.includes("--offline") ? { offline: true } : {},
       ...argv.includes("--strict") ? { strict: true } : {}
     };
   },
-  run: async ({ store, now }, { bundlePath: path, expiringDays, unverifiedDays, agingDays, repoRoot }) => {
+  run: async ({ store, now }, {
+    bundlePath: path,
+    expiringDays,
+    unverifiedDays,
+    agingDays,
+    repoRoot,
+    offline
+  }) => {
     const checkedAt = now();
     const records = await store.list(path);
-    const anchorDrift = await store.detectDrift(records, repoRoot);
+    const anchorDrift = await store.detectDrift(records, repoRoot, {
+      offline: offline === true
+    });
     const report = doctor(records, {
       ...expiringDays !== void 0 ? { expiringDays } : {},
       ...unverifiedDays !== void 0 ? { unverifiedDays } : {},
@@ -4059,7 +4600,7 @@ var listCommand = define({
   name: "list",
   tool: "kb_list",
   usage: "list [type]",
-  description: "Every record, optionally narrowed to one type. Use kb_query when you have a question; this is for enumerating.",
+  description: "Every record, optionally one type. For enumerating; use kb_query for a question.",
   input: import_zod15.z.object({ bundlePath, type: import_zod15.z.enum(KB_RECORD_TYPES).optional() }),
   fromArgv: (argv, path) => ({ bundlePath: path, type: argv[1] }),
   run: async ({ store }, { bundlePath: path, type }) => (await store.list(path, type)).map((record) => ({
@@ -4077,7 +4618,7 @@ var loadCommand = define({
   name: "load",
   tool: "kb_load",
   usage: "load [type] [--budget N | --all] [--repo-root PATH]",
-  description: "Loads the whole knowledge base at once, each record with its standing. Superseded records arrive as stubs; rejected and open records arrive whole. Refuses past the token budget \u2014 call kb_catalog, kb_pack on it; `all` bypasses the budget. Never read record files directly. Cache-stable; `digest` is the base's content stamp \u2014 hooks use it to tell you when to reload.",
+  description: "Load the whole base, each record with its standing \u2014 call it first, at the point of use, since compaction drops it. Superseded records arrive as stubs; kb_trace has the history. Over budget it refuses: kb_catalog, then kb_pack, or narrow with `type`; `all` bypasses. Never read record files directly \u2014 only kb_* tools resolve supersession. `digest` stamps the base's content, so hooks know when to reload.",
   input: import_zod16.z.object({
     bundlePath,
     type: import_zod16.z.enum(KB_RECORD_TYPES).optional(),
@@ -4129,7 +4670,7 @@ var logCommand = define({
   name: "log",
   tool: "kb_log",
   usage: "log",
-  description: "What touched what, and when. The only artifact here that cannot be reconstructed from the records, so malformed lines are reported rather than repaired.",
+  description: "Who touched what, and when. Append-only; malformed lines are reported, never repaired.",
   input: import_zod17.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readLog(path)
@@ -4141,7 +4682,7 @@ var noDecisionCommand = define({
   name: "no-decision",
   tool: "kb_no_decision",
   usage: "no-decision <reason...>",
-  description: 'Claim in one sentence that there was nothing to decide. Gating on "did you write a decision?" rewards writing a junk one; gating on "did you answer?" does not, so silence has to be expressible. Idempotent \u2014 restating it is not a collision.',
+  description: "Record in one sentence that a piece of work had nothing to decide. Idempotent.",
   input: import_zod18.z.object({ bundlePath, reason: import_zod18.z.string().min(1) }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -4164,7 +4705,7 @@ var packCommand = define({
   name: "pack",
   tool: "kb_pack",
   usage: "pack <conceptId> [--hops N] [--max-nodes N] [--budget N]",
-  description: "The bounded neighbourhood around one record: everything within `hops` of the root, ranked and cut to `maxNodes`, with every cut record named under Excluded \u2014 a named gap is knowable, a silent one is not. Prefer this over kb_load when the base is too large to hold whole and the work centres on one record; prefer it over kb_query when the question needs the governed neighbourhood \u2014 what was settled and what binds near this record \u2014 rather than a lookup by wording. Superseded records arrive as name, replacement and date stubs exactly as kb_load emits them: their bodies no longer hold, and kb_trace has the history. Refuses outright rather than truncating when the pack would exceed its token budget \u2014 a partial pack is indistinguishable from a complete one \u2014 reporting the record count and every already-cut id so the caller can lower hops or maxNodes, or raise the budget. The header carries the bundle, root, budget and a timestamp; everything below the header is byte-identical across runs over an unchanged base, so two packs can be diffed and a changed byte means changed knowledge. This tool (with kb_load, kb_query and kb_trace) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.",
+  description: "Bounded neighbourhood around one record: within `hops`, ranked, cut to `maxNodes`, with every cut record named under Excluded. Use when the base is over kb_load's budget and the work centres on a record you can name. Refuses over budget rather than truncating. Everything below the header is byte-stable across runs. Resolves supersession like kb_load.",
   input: import_zod19.z.object({
     bundlePath,
     conceptId,
@@ -4264,7 +4805,7 @@ var pinCommand = define({
   name: "pin",
   tool: "kb_pin",
   usage: "pin [bundle-path] [--mode full|index] [--profiles a,b] [--local|--user] [--frozen|--unfreeze]",
-  description: "Pin a base into a workspace pin manifest, so `context` surfaces it at every context birth. Three layers, nearest wins: the committed project manifest (.strauss/kb-pins.json, the default), `--local` (.strauss/kb-pins.local.json, personal and gitignored), and `--user` (~/.strauss/kb-pins.json, every workspace). Idempotent \u2014 re-pinning changes nothing unless --mode, --profiles, or --frozen/--unfreeze are given, which update just those fields. `--mode full` preloads the whole base into the block regardless of the full-under threshold; `--mode index` never upgrades. `--profiles` scopes the pin to named context profiles. `--frozen` marks the base concluded: write commands against it refuse and `context` labels it read-only. A path with no records yet succeeds with a warning; bases are routinely pinned before they are populated. Pins are workspace state: the pinned base itself is never touched.",
+  description: "Pin a base into a workspace manifest so kb_context surfaces it. Layers, nearest wins: project `.strauss/kb-pins.json` (default), `--local` (personal, gitignored), `--user` (`~/.strauss`). Idempotent; `--mode full|index`, `--profiles`, `--frozen`/`--unfreeze` update only those fields. A path with no records pins with a warning. Never touches the base itself.",
   input: import_zod20.z.object({
     bundlePath,
     mode: import_zod20.z.enum(["full", "index"]).optional().describe(
@@ -4308,7 +4849,7 @@ var pinsCommand = define({
   name: "pins",
   tool: "kb_pins",
   usage: "pins",
-  description: "Every pinned base across the manifest layers, each with its layer and whether it currently resolves to readable records. Reads the workspace manifests rather than any one base, like kb_context.",
+  description: "Every pinned base across the manifest layers, with its layer and whether it resolves to records. Takes no bundlePath.",
   input: import_zod21.z.object({}),
   fromArgv: () => ({}),
   run: ({ store }) => listPins(store, process.cwd())
@@ -4362,7 +4903,7 @@ var readIndexCommand = define({
   name: "index",
   tool: "kb_index",
   usage: "index",
-  description: "The index, rebuilt if it disagrees with the records. One call gives the whole shape of the base: title, type, status, and description per record. The cheap re-orientation call after compaction or deep in a long session \u2014 a few hundred tokens; call it (or kb_context, when bases are pinned) first, then kb_load or fetch by concept id.",
+  description: "The index \u2014 title, type, status, description per record \u2014 rebuilt if stale. Cheapest re-orientation after compaction: call it (or kb_context) first, then kb_load or fetch by id.",
   input: import_zod23.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: ({ store }, { bundlePath: path }) => store.readIndex(path)
@@ -4374,7 +4915,7 @@ var schemaCommand = define({
   name: "schema",
   tool: "kb_schema",
   usage: "schema",
-  description: "JSON Schema for the frontmatter, the write input, and log entries \u2014 generated from the code that enforces them, so it cannot drift from what a write will accept.",
+  description: "JSON Schema for frontmatter, write input, and log entries, generated from the enforcing code.",
   input: import_zod24.z.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(kbJsonSchemas())
@@ -4386,7 +4927,7 @@ var statusCommand = define({
   name: "status",
   tool: "kb_status",
   usage: "status <concept-id> <status>",
-  description: "Move a record's status, leaving everything else alone. Uses a compare-and-swap, so a concurrent change fails loudly rather than being overwritten.",
+  description: "Move a record's status. Compare-and-swap: a concurrent change fails instead of being overwritten.",
   input: import_zod25.z.object({
     bundlePath,
     conceptId,
@@ -4410,7 +4951,7 @@ var supersedeCommand = define({
   name: "supersede",
   tool: "kb_supersede",
   usage: "supersede <concept-id> <replacement-id>",
-  description: "Mark a record superseded by another, linking both directions. Use this rather than editing a record whose meaning changed \u2014 a record that quietly becomes something else invalidates every reference to it, and the earlier understanding is what a later trace needs.",
+  description: "Mark a record superseded by another, linked in both directions. Use instead of editing a record whose meaning changed.",
   input: import_zod26.z.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -4429,7 +4970,7 @@ var import_zod27 = require("zod");
 var syncInstructionsCommand = define({
   name: "sync-instructions",
   usage: "sync-instructions <file> [--profile NAME] [--budget N] [--full-under N]",
-  description: "Idempotently plant the `context` block between sentinel comments in an instruction file (AGENTS.md, CLAUDE.md), creating the block when absent and leaving everything outside the sentinels alone. CLI-only: this is file plumbing for runtimes whose instruction files are re-read where their conversations are not, not an agent capability \u2014 the capability is kb_context.",
+  description: "CLI-only: plant the kb_context block between sentinel comments in AGENTS.md or CLAUDE.md, idempotently.",
   input: import_zod27.z.object({
     file: import_zod27.z.string().min(1).describe("The instruction file to edit in place."),
     budgetTokens: import_zod27.z.number().int().positive().optional(),
@@ -4465,7 +5006,7 @@ var traceCommand = define({
   name: "trace",
   tool: "kb_trace",
   usage: "trace <concept-id> [edges...]",
-  description: 'How a position was arrived at, as a timeline ordered by when each record was written. Deliberately includes rejected, draft, and superseded records \u2014 in a history those are the content, not noise. Follows supersession, shared code anchors, and shared sources. Use when the question is "why is this the way it is" rather than "what do we hold now". This tool (with kb_load and kb_query) is the only supported way to read a base; a raw file read bypasses supersession resolution and returns replaced records as if current.',
+  description: 'Timeline of how a position was reached, ordered by write time, following supersession, shared anchors and shared sources. Includes rejected, draft and superseded records \u2014 in a history they are the content. For "why is it like this"; kb_load answers "what holds now".',
   input: import_zod28.z.object({
     bundlePath,
     conceptId,
@@ -4509,7 +5050,7 @@ var unpinCommand = define({
   name: "unpin",
   tool: "kb_unpin",
   usage: "unpin [bundle-path]",
-  description: "Remove a base from every pin manifest layer that holds it \u2014 project, local, and user \u2014 because unpinned means gone, not still injected from another file. Reports which layers were touched.",
+  description: "Remove a base from every manifest layer that holds it. Reports the layers touched.",
   input: import_zod30.z.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
@@ -4537,7 +5078,7 @@ var verifyCommand = define({
   name: "verify",
   tool: "kb_verify",
   usage: "verify <concept-id> --note <text>",
-  description: "Append one verified[] event \u2014 who checked the record, when, and what the check found. Appends only; prior events are never rewritten. A record's own generator is refused unless the actor is human: re-reading your own output is not an independent check.",
+  description: "Append a verified[] event: who checked, when, and what was found. Append-only. A record's own generator is refused unless the actor is `human:`-prefixed.",
   input: import_zod32.z.object({
     bundlePath,
     conceptId,
@@ -4566,15 +5107,7 @@ var writeCommand = define({
   name: "write",
   tool: "kb_write",
   usage: "write <type> < record.json",
-  description: [
-    "Write one record. Search first \u2014 the same knowledge filed twice under different slugs is how a base rots, and a duplicate concept id is rejected rather than overwritten. Call kb_types for the sections each type accepts.",
-    "",
-    "Judgment the tool cannot enforce for you:",
-    "- An unsourced claim is an `assumption` record with assumption: true, never a `fact` with a vague source. The distinction is what lets a later reader separate what was established from what was guessed.",
-    "- When two records conflict, say so in a `risk`, an `open-question`, or a superseding `decision`. Quietly picking a winner destroys the disagreement, which is usually the useful part.",
-    "- Prefer a new record over overloading an existing one, and keep each short. A record nobody finishes reading is not durable memory.",
-    "- Records are never deleted; supersede instead, so the earlier reasoning stays inspectable."
-  ].join("\n"),
+  description: "Write one record. Search first \u2014 a duplicate concept id is rejected, not overwritten; kb_types lists each type's sections. An unsourced claim is an `assumption` with assumption: true, never a vague `fact`. Conflicting records get a `risk`, `open-question`, or superseding `decision`. Prefer a new short record over overloading one. Never delete; supersede.",
   input: import_zod33.z.object({
     bundlePath,
     type: import_zod33.z.enum(KB_RECORD_TYPES),
@@ -4606,14 +5139,7 @@ var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
   usage: "write-decision < decision.json",
-  description: [
-    "Write a decision. Takes `alternative` and `impact` as fields rather than free sections, because what was rejected is the part a later reader cannot reconstruct from the code \u2014 a heading is too easy to leave empty.",
-    "",
-    "What belongs in one:",
-    '- Record a decision when a later reader would otherwise "simplify" the constraint away. If the diff already answers the question, there is nothing here to write.',
-    "- `alternative` is what you turned down and why, not a list of everything considered.",
-    "- A reference to material you read goes in `sources`; a reference to code goes in `anchors`; a reference to another record goes in `relatedConceptIds`."
-  ].join("\n"),
+  description: "Write a decision, with `alternative` (what was rejected and why) and `impact` as fields. Record one when a later reader would otherwise simplify the constraint away; skip when the diff already answers it. `sources` for material read, `anchors` for code, `relatedConceptIds` for records.",
   input: import_zod34.z.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
@@ -4673,7 +5199,7 @@ var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/version.ts
-var VERSION = true ? "0.1.13" : "0.0.0-dev";
+var VERSION = true ? "0.1.15" : "0.0.0-dev";
 
 // src/mcp.ts
 function createKbMcpServer() {
@@ -4712,7 +5238,7 @@ async function runKbMcpServer() {
 }
 
 // src/cli.ts
-var import_node_path8 = require("path");
+var import_node_path9 = require("path");
 async function runKbCli(argv) {
   const { flags, literal } = takeLiteral(argv);
   const { bundle, rest: withFlags } = takeBundle(flags);
@@ -4769,7 +5295,7 @@ function takeLiteral(argv) {
 function takeBundle(argv) {
   const at = argv.indexOf("--bundle");
   if (at === -1) {
-    return { bundle: (0, import_node_path8.join)(process.cwd(), KB_DIR), rest: argv };
+    return { bundle: (0, import_node_path9.join)(process.cwd(), KB_DIR), rest: argv };
   }
   const bundle = argv[at + 1];
   if (!bundle) die("--bundle requires a path");
@@ -4884,6 +5410,7 @@ function usage() {
   impact,
   inboundIndex,
   indexIsStale,
+  isCanonicalRepoUrl,
   isKbLinkRel,
   isKbRecordType,
   isNoDecisionRecord,
@@ -4907,11 +5434,13 @@ function usage() {
   pinBase,
   readMergedPins,
   readPinsLayer,
+  readRemoteAnchors,
   regexResolver,
   renderCatalogLine,
   renderIndex,
   renderIndexLine,
   renderLogEntry,
+  repoCacheDir,
   resolveAnchor,
   resolveHeads,
   resolveHits,