@openviking/opencode-plugin 0.2.4 → 2026.9.9-1

package/lib/shared/recall-compress-core.mjs

@@ -86,10 +86,16 @@ export function repairDigestUris(digest, validUris = []) {
       lines.push(line);
       continue;
     }
+    let tokenized = line;
+    for (const uri of [...valid].sort((a, b) => b.length - a.length)) {
+      if (/\s/.test(uri)) tokenized = tokenized.split(uri).join(encodeURI(uri));
+    }
     let dropped = false;
-    const repaired = line.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
-      if (validSet.has(uri)) return uri;
-      const nearest = nearestUri(uri, valid);
+    const repaired = tokenized.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
+      let decoded = uri;
+      try { decoded = decodeURI(uri); } catch { /* keep the original candidate */ }
+      if (validSet.has(decoded)) return decoded;
+      const nearest = nearestUri(decoded, valid);
       if (nearest) return nearest;
       dropped = true;
       return uri;
@@ -149,6 +155,7 @@ async function writeCache(path, value) {
 export async function compressRecallContext({
   query,
   rendered,
+  shortContext = rendered,
   entries = [],
   cfg = {},
   runCompressor,
@@ -158,7 +165,9 @@ export async function compressRecallContext({
   const input = String(rendered || "").trim();
   if (!input) return { status: COMPRESS_EMPTY, context: "" };
   const minChars = Math.max(0, Number(cfg.recallCompressMinInputChars ?? 1500));
-  if (input.length < minChars) return { status: COMPRESS_OK, context: input };
+  if (input.length < minChars) {
+    return { status: COMPRESS_OK, context: String(shortContext ?? input).trim() };
+  }
 
   const maxInputChars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
   const maxBullets = Math.max(1, Number(cfg.recallCompressMaxBullets || 6));
@@ -171,7 +180,8 @@ export async function compressRecallContext({
   });
   const cached = await readCache(cachePath);
   if (cached?.key === key && typeof cached.digest === "string") {
-    return { status: COMPRESS_OK, context: cached.digest };
+    const digest = normalizeCompressedContext(cached.digest, 4000, maxBullets);
+    if (digest) return { status: COMPRESS_OK, context: digest };
   }
 
   const prompt = buildRecallCompressionPrompt({
@@ -185,9 +195,10 @@ export async function compressRecallContext({
   if (!normalized) return { status: COMPRESS_EMPTY, context: "" };
 
   const validUris = entries.map((entry) => entry?.uri).filter(Boolean);
-  const digest = repairDigestUris(normalized, validUris.length
+  const repaired = repairDigestUris(normalized, validUris.length
     ? validUris
     : (input.match(/viking:\/\/[^\s<>"']+/g) || []));
+  const digest = normalizeCompressedContext(repaired, 4000, maxBullets);
   if (!digest) return { status: COMPRESS_FAILED, context: "" };
 
   await writeCache(cachePath, { key, digest, updatedAt: now || 0 });

package/lib/shared/recall-core.mjs

@@ -14,8 +14,8 @@ const STOPWORDS = new Set([
 ]);
 const USER_RESERVED_DIRS = new Set(["memories", "skills"]);
 const SOURCES = [
-  { type: "memory", uri: "viking://user/memories", bucket: "memories" },
-  { type: "skill", uri: "viking://user/skills", bucket: "skills" },
+  { type: "memory", uri: "viking://~/memories", bucket: "memories" },
+  { type: "skill", uri: "viking://~/skills", bucket: "skills" },
 ];
 const DEFAULT_CONTEXT_LIMIT = 10;
 const DEFAULT_CONTEXT_MAX_TOKENS = 1600;
@@ -164,10 +164,9 @@ export function contextRequestTimeoutMs(cfg = {}, body = {}) {
   // `query_expansion` defaults to "auto" server-side, so only an explicit "off"
   // takes the expansion fuse back out of the budget.
   const wantsExpansion = Boolean(body.session_id) && body.query_expansion !== "off";
-  if (!wantsRewrite && !wantsExpansion) return undefined;
-
   const configured = Number(cfg.recallContextTimeoutMs);
   if (Number.isFinite(configured) && configured > 0) return Math.max(1000, Math.floor(configured));
+  if (!wantsRewrite && !wantsExpansion) return undefined;
   const floor = wantsRewrite ? SERVER_REWRITE_REQUEST_TIMEOUT_MS : EXPANSION_REQUEST_TIMEOUT_MS;
   return Math.max(Number(cfg.timeoutMs) || 0, floor);
 }
@@ -272,6 +271,11 @@ async function resolveUserSpace(fetchJSON, actorPeerId = "") {
 
 async function resolveTargetUri(fetchJSON, targetUri, actorPeerId = "") {
   const trimmed = targetUri.trim().replace(/\/+$/, "");
+  // viking://~ is the home alias: the server expands it to the caller's own user
+  // space, so it needs no client-side rewrite.
+  if (trimmed === "viking://~" || trimmed.startsWith("viking://~/")) return trimmed;
+  // Legacy compat: uid-less viking://user/<reserved> URIs may still sit in plugin
+  // configs. Newer servers reject them, so rewrite to an explicit-uid URI here.
   const m = trimmed.match(/^viking:\/\/user(?:\/(.*))?$/);
   if (!m) return trimmed;
   const rawRest = (m[1] ?? "").trim();
@@ -413,6 +417,31 @@ export async function markContextFaceLegacy(path = stateFile("context-face.json"
   await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });
 }
 
+/**
+ * A `peer_scope` the server rejects is remembered the same way, but unlike the
+ * context face this one is not a silent capability probe: dropping the field
+ * widens recall from the caller's own peer to the whole user root, so doctor
+ * reads this file back and warns.
+ */
+export function peerScopeMemoPath() {
+  return stateFile("peer-scope.json");
+}
+
+export async function readPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {
+  const cached = await readJsonFile(path);
+  if (!cached?.legacyUntil || Number(cached.legacyUntil) <= now) return null;
+  return cached;
+}
+
+export async function markPeerScopeDowngrade(scope, status, path = peerScopeMemoPath(), now = Date.now()) {
+  await writeJsonFile(path, {
+    legacyUntil: now + LEGACY_CACHE_TTL_MS,
+    scope: String(scope || ""),
+    status: Number(status) || 0,
+    at: now,
+  });
+}
+
 function looksLikeUnknownField(res) {
   const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();
   return text.includes("extra") || text.includes("mode") || text.includes("unexpected");
@@ -421,7 +450,7 @@ function looksLikeUnknownField(res) {
 function wrapContext(body) {
   return [
     "<openviking-context>",
-    "Relevant memory from OpenViking. Use the recall/read MCP tools to expand URIs.",
+    "Relevant memory from OpenViking. Use the search/read MCP tools to expand URIs.",
     body,
     "</openviking-context>",
   ].join("\n");
@@ -554,7 +583,15 @@ async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log =
 export async function postRecall(fetchJSON, body, opts = {}) {
   const actorPeerId = opts.actorPeerId || "";
   const log = opts.log || (() => {});
+  const memoPath = opts.peerScopeMemoPath;
   const request = { ...body };
+
+  // A remembered downgrade is still a downgrade: recall runs wider than the
+  // caller asked for, so the memo doubles as the doctor's evidence.
+  if (request.peer_scope && await readPeerScopeDowngrade(memoPath)) {
+    delete request.peer_scope;
+  }
+
   const res = await fetchJSON("/api/v1/search/recall", {
     method: "POST",
     body: JSON.stringify(request),
@@ -562,9 +599,17 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   if (!request.peer_scope || (res.status !== 400 && res.status !== 422)) {
     return res;
   }
+  // Only an unknown-field rejection means "this server predates peer_scope".
+  // Retrying every other 400/422 without it silently widens the search from
+  // the caller's own peer to the whole user root.
+  if (!looksLikeUnknownField(res)) {
+    log("recall_peer_scope_error", { status: res.status || 0 });
+    return res;
+  }
 
   const downgraded = { ...request };
   delete downgraded.peer_scope;
+  await markPeerScopeDowngrade(String(request.peer_scope), res.status || 0, memoPath);
   log("recall_peer_scope_downgrade", { status: res.status || 0 });
   return fetchJSON("/api/v1/search/recall", {
     method: "POST",
@@ -572,7 +617,31 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   }, { actorPeerId });
 }
 
+/**
+ * Recall, plus whatever is still filed under the peer this workspace used
+ * before the identity rule changed.
+ *
+ * Under the default `peer_scope: "all"` this costs nothing: the server's own
+ * sweep of `{user_root}/peers` already reaches the old peer's memories. Under
+ * `"actor"` that sweep is off by definition, so the old peer is asked for
+ * separately — as itself, which is both cheaper and wider than a bare
+ * cross-peer read (that would need the user id, and reaches memories only).
+ */
 export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+  const primary = await recallForPeer(fetchJSON, cfg, query, options);
+
+  const legacyPeerId = String(options.legacyPeerId || "").trim();
+  const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+  if (cfg.recallPeerScope !== "actor" || !legacyPeerId || legacyPeerId === actorPeerId) return primary;
+
+  const log = options.log || (() => {});
+  const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
+  if (!legacy) return primary;
+  log("recall_legacy_peer_hit", { legacyPeerId });
+  return primary ? `${primary}\n${legacy}` : legacy;
+}
+
+async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
   const log = options.log || (() => {});
   const trimmed = String(query || "").trim();

package/lib/shared/setup-wizard.mjs

@@ -39,14 +39,17 @@ export async function runSetupWizard({
   output = process.stdout,
   env = process.env,
 } = {}) {
-  const { cliPath } = loadCredentialFiles(env);
-  const current = readJsonSafe(cliPath);
+  // cliPath is empty until the file exists; first-run writes go to the candidate
+  // path (OPENVIKING_CLI_CONFIG_FILE, else ~/.openviking/ovcli.conf).
+  const { cliPath, cliPathCandidate } = loadCredentialFiles(env);
+  const targetPath = cliPath || cliPathCandidate;
+  const current = readJsonSafe(targetPath);
   const rl = createInterface({ input, output });
   const say = (line = "") => output.write(`${line}\n`);
 
   try {
     say("OpenViking memory plugin setup");
-    say(`Config file: ${cliPath}`);
+    say(`Config file: ${targetPath}`);
     say("");
     say("Current values:");
     say(`  url:     ${current.url || "(not set)"}`);
@@ -89,22 +92,22 @@ export async function runSetupWizard({
     const confirm = (await rl.question("Write config? [Y/n] ")).trim().toLowerCase();
     if (confirm === "n" || confirm === "no") {
       say("Aborted; nothing written.");
-      return { written: false, path: cliPath };
+      return { written: false, path: targetPath };
     }
 
-    mkdirSync(dirname(cliPath), { recursive: true });
-    if (existsSync(cliPath)) {
-      copyFileSync(cliPath, `${cliPath}.bak.${Date.now()}`);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    if (existsSync(targetPath)) {
+      copyFileSync(targetPath, `${targetPath}.bak.${Date.now()}`);
     }
-    writeFileSync(cliPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    writeFileSync(targetPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
     try {
-      chmodSync(cliPath, 0o600);
+      chmodSync(targetPath, 0o600);
     } catch {
       /* best effort on platforms without chmod semantics */
     }
-    say(`Written: ${cliPath}`);
+    say(`Written: ${targetPath}`);
     say("The stdio MCP proxy and hooks pick this up on the next harness start.");
-    return { written: true, path: cliPath };
+    return { written: true, path: targetPath };
   } finally {
     rl.close();
   }

package/lib/shared/uri-guard.mjs

@@ -14,30 +14,52 @@ export function normalizeToolName(value) {
   return String(value || "").trim().toLowerCase();
 }
 
-export function findVikingUri(args = {}, keys = DEFAULT_URI_KEYS) {
+// Arguments that carry file CONTENT rather than a location. The sweep below
+// looks past the known path keys so an unusual one (`paths`, a nested target)
+// is still caught, but text a tool is asked to WRITE is not a path: a local
+// `write` whose body merely mentions viking://user/default/ was denied, and no
+// file was created. Skipped by name at any depth.
+const DEFAULT_CONTENT_KEYS = [
+  "content",
+  "contents",
+  "text",
+  "body",
+  "old_string",
+  "oldString",
+  "new_string",
+  "newString",
+  "old_str",
+  "new_str",
+  "file_text",
+  "insert_line",
+  "replacement",
+];
+
+export function findVikingUri(args = {}, keys = DEFAULT_URI_KEYS, contentKeys = DEFAULT_CONTENT_KEYS) {
   if (!args || typeof args !== "object") return null;
   for (const key of keys) {
     const uri = findVikingUriInValue(args[key]);
     if (uri) return uri;
   }
-  return findVikingUriInValue(args);
+  return findVikingUriInValue(args, new Set(contentKeys));
 }
 
-export function findVikingUriInValue(value) {
+export function findVikingUriInValue(value, skipKeys) {
   if (typeof value === "string") {
     const match = value.match(/\bviking:\/\/[^\s"'`<>)]*/i);
     return match?.[0] || null;
   }
   if (Array.isArray(value)) {
     for (const item of value) {
-      const uri = findVikingUriInValue(item);
+      const uri = findVikingUriInValue(item, skipKeys);
       if (uri) return uri;
     }
     return null;
   }
   if (value && typeof value === "object") {
-    for (const item of Object.values(value)) {
-      const uri = findVikingUriInValue(item);
+    for (const [key, item] of Object.entries(value)) {
+      if (skipKeys?.has(key)) continue;
+      const uri = findVikingUriInValue(item, skipKeys);
       if (uri) return uri;
     }
   }

package/lib/shared/workspace-identity.mjs

@@ -0,0 +1,334 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Workspace identity: where the workspace root is, and what git calls it.
+ *
+ * Every hook is a fresh Node process and this runs on prompt-level paths, so
+ * the derivation is pure filesystem work — no `git` subprocess. That keeps it
+ * inside the tightest hook budget (Codex allows SessionEnd 3s against
+ * SessionStart's 70s), and it keeps working where git is absent from PATH or
+ * would refuse the repo over dubious ownership.
+ *
+ * The result is cached per cwd under the state dir so the several hooks of one
+ * turn pay for the walk once.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
+
+// The workspace config file names live here, and `workspace-config.mjs`
+// re-exports them: the walk below needs the filenames to recognise a directory
+// someone marked as a workspace, and it must not pull in the config layer to
+// learn them.
+export const CONFIG_DIR_NAME = ".openviking";
+export const TEAM_FILE = "config.json";
+export const LOCAL_FILE = "config.local.json";
+
+const IDENTITY_CACHE_TTL_MS = 60_000;
+// 255 is the AGFS path-segment limit; stopping well short leaves room for the
+// hash suffix and for anything that later prefixes a peer id.
+const MAX_PEER_ID_LENGTH = 100;
+
+export function stateDir(env = process.env) {
+  const explicit = String(env.OPENVIKING_STATE_DIR || "").trim();
+  if (explicit) return explicit;
+  const home = String(env.OPENVIKING_HOME || "").trim();
+  const base = home ? home.replace(/^~(?=$|\/)/, homedir()) : join(homedir(), ".openviking");
+  return join(base, "state");
+}
+
+function shortHash(value) {
+  return createHash("sha256").update(String(value)).digest("hex").slice(0, 12);
+}
+
+/**
+ * Legacy peer sanitation: one byte in, one byte out, no collapsing and no
+ * trimming, so a leading `/` still becomes a leading `-`. Kept byte-exact
+ * because `peer.source: "cwd"` and the legacy id that dual-read recomputes both
+ * depend on it — do not "improve" it.
+ */
+export function legacySanitize(value) {
+  return String(value || "").replace(/[^A-Za-z0-9]/g, "-");
+}
+
+/**
+ * Readable sanitation for values that were never path-shaped — a normalized
+ * remote, a directory name. Mirrors the server's own `_sanitize_component`
+ * (`openviking/ingest/peer.py:32`) so both languages agree on the id, then
+ * enforces what `validate_identifier_part` additionally requires.
+ */
+export function sanitizePeerId(value) {
+  const raw = String(value || "").trim();
+  let cleaned = raw.replace(/[^a-zA-Z0-9_.@-]+/g, "-").replace(/-{2,}/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  if (!cleaned) return "";
+  // The server accepts at most one `@` in an identifier part.
+  const at = cleaned.indexOf("@");
+  if (at !== -1) cleaned = cleaned.slice(0, at + 1) + cleaned.slice(at + 1).replace(/@/g, "-");
+  // `ext-` is the server's namespace for base64-encoded external identities,
+  // and `__self` its operation-target sentinel. Neither is ours to occupy.
+  if (cleaned.startsWith("ext-")) cleaned = `x-${cleaned}`;
+  if (cleaned === "__self") cleaned = "self";
+  if (cleaned === "." || cleaned === "..") return "";
+  if (cleaned.length > MAX_PEER_ID_LENGTH) {
+    cleaned = `${cleaned.slice(0, MAX_PEER_ID_LENGTH - 13).replace(/[-.]+$/, "")}-${shortHash(raw)}`;
+  }
+  return cleaned;
+}
+
+/**
+ * Normalize a remote URL to `host/path`, lowercased.
+ *
+ * Both spellings of the same repo converge, and userinfo is dropped — so a
+ * remote with an embedded token cannot leak it into a peer id. The cost of
+ * case folding is that two repos differing only in case share one namespace on
+ * the rare case-sensitive forge.
+ */
+export function normalizeGitRemote(url) {
+  const raw = String(url || "").trim();
+  if (!raw) return "";
+
+  // `C:\src\repo` and `C:/src/repo` are one machine's directory, not a shared
+  // identity — and the scp pattern would happily read the drive as a host.
+  if (/^[A-Za-z]:[\\/]/.test(raw)) return "";
+
+  let host = "";
+  let path = "";
+  const scp = /^(?:[^@/\\]+@)?([^:/\\]+):(?!\/)(.+)$/.exec(raw);
+  if (scp && !/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw)) {
+    host = scp[1];
+    path = scp[2];
+  } else {
+    let parsed;
+    try {
+      parsed = new URL(raw);
+    } catch {
+      return "";
+    }
+    // A local clone has no stable shared identity — fall through to the path
+    // rules instead of minting one from `file://` or a bare directory.
+    if (parsed.protocol === "file:" || !parsed.hostname) return "";
+    host = parsed.hostname;
+    path = parsed.pathname;
+  }
+
+  host = host.toLowerCase().replace(/^\[|\]$/g, "");
+  path = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "").toLowerCase();
+  if (!host || !path) return "";
+  return `${host}/${path}`;
+}
+
+function readFileOrEmpty(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Read `[remote "origin"] url` out of a git config with a minimal INI parse.
+ *
+ * `include` / `includeIf` are deliberately not followed: resolving them means
+ * more filesystem walking for a value the fallback chain already covers, so an
+ * unreadable remote just falls through to the next template.
+ */
+export function readGitRemoteUrl(commonDir, remote = "origin") {
+  const text = readFileOrEmpty(join(commonDir, "config"));
+  if (!text) return "";
+
+  let inSection = false;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(";")) continue;
+    const section = /^\[([^\]]+)\]/.exec(trimmed);
+    if (section) {
+      const header = section[1].trim();
+      // git folds section and key names to lower case but keeps a quoted
+      // subsection exact, so `[Remote "origin"]` is the same section and
+      // `[remote "Origin"]` is not.
+      const quoted = /^remote\s+"(.*)"$/i.exec(header);
+      inSection = Boolean(quoted && quoted[1] === remote);
+      continue;
+    }
+    if (!inSection) continue;
+    const pair = /^url\s*=\s*(.*)$/i.exec(trimmed);
+    // git treats an unquoted `#` or `;` as starting a comment anywhere on the
+    // line, so a trailing note is not part of the URL.
+    if (pair) return pair[1].split(/[#;]/)[0].trim().replace(/^["']|["']$/g, "");
+  }
+  return "";
+}
+
+function resolveGitDir(root) {
+  const dotGit = join(root, ".git");
+  let stat;
+  try {
+    stat = statSync(dotGit);
+  } catch {
+    return null;
+  }
+  if (stat.isDirectory()) return { gitDir: dotGit, commonDir: dotGit, kind: "repo" };
+  if (!stat.isFile()) return null;
+
+  const pointer = /^gitdir:\s*(.+)$/m.exec(readFileOrEmpty(dotGit));
+  if (!pointer) return null;
+  const gitDir = resolve(root, pointer[1].trim());
+
+  // `commondir` is the worktree signal, so it is read first — a repository
+  // that merely lives under a directory called `modules` is not a submodule.
+  const commonRef = readFileOrEmpty(join(gitDir, "commondir")).trim();
+  const commonDir = commonRef
+    ? (isAbsolute(commonRef) ? commonRef : resolve(gitDir, commonRef))
+    : gitDir;
+
+  // A submodule keeps its own remote under the superproject's
+  // `.git/modules/<name>`; converging it onto the superproject would merge two
+  // repositories that release, and are reviewed, separately. Only the segment
+  // right after a `.git` directory means that, which is also why a worktree of
+  // a submodule resolves here through its own commondir.
+  const kind = /[/\\]\.git[/\\]modules[/\\]/.test(`${commonDir}${sep}`)
+    ? "submodule"
+    : (commonRef ? "worktree" : "repo");
+  return { gitDir, commonDir, kind };
+}
+
+/** A directory the user made a workspace on purpose, by giving it a config file. */
+function hasWorkspaceMarker(dir) {
+  for (const name of [TEAM_FILE, LOCAL_FILE]) {
+    try {
+      if (statSync(join(dir, CONFIG_DIR_NAME, name)).isFile()) return true;
+    } catch { /* not marked here */ }
+  }
+  return false;
+}
+
+const NO_ROOT = Object.freeze({ root: "", rootKind: "", git: null, gitRoot: "" });
+
+/**
+ * Walk up from `cwd` to the nearest workspace root.
+ *
+ * A workspace is a git repository, or a directory someone marked as one by
+ * creating `.openviking/config.json` (or `config.local.json`) in it. Nearest
+ * wins. Above a marked directory the walk continues to the enclosing
+ * repository, if any, so the git-shaped variables still resolve there.
+ * Anything else — a scratch folder, a download, an app's per-task directory —
+ * is not a workspace and gets no peer of its own.
+ *
+ * `$HOME` and the filesystem root are never workspace roots: a stray `.git`
+ * in either would silently make every unrelated directory one workspace.
+ */
+export function findWorkspaceRoot(cwd, env = process.env) {
+  const start = String(cwd || "").trim();
+  if (!start) return NO_ROOT;
+
+  let absolute;
+  try {
+    // A relative `start` makes `resolve` read process.cwd(), which throws when
+    // the directory is gone — the very case the catch below is meant to cover.
+    absolute = resolve(start);
+  } catch {
+    return NO_ROOT;
+  }
+
+  // `current` and `stopAt` are compared as strings, so they must be
+  // canonicalized together. A `$HOME` reached through a symlink plus an
+  // unresolvable cwd would otherwise walk straight past the guard.
+  const home = String(env.HOME || "").trim() || homedir();
+  let current;
+  let stopAt;
+  try {
+    current = realpathSync(absolute);
+    stopAt = realpathSync(home);
+  } catch {
+    current = absolute;
+    stopAt = home;
+  }
+  const filesystemRoot = parse(current).root;
+  if (current === stopAt || current === filesystemRoot) return NO_ROOT;
+
+  let root = "";
+  let rootKind = "";
+  while (current && current !== filesystemRoot && current !== stopAt) {
+    const git = resolveGitDir(current);
+    if (git) return { root: root || current, rootKind: rootKind || "git", git, gitRoot: current };
+    if (!root && hasWorkspaceMarker(current)) {
+      root = current;
+      rootKind = "config";
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return root ? { root, rootKind, git: null, gitRoot: "" } : NO_ROOT;
+}
+
+function cachePath(cwd, env) {
+  return join(stateDir(env), `ws-identity-${shortHash(cwd)}.json`);
+}
+
+function readCache(path, now) {
+  try {
+    const cached = JSON.parse(readFileSync(path, "utf-8"));
+    // Bounded on both sides: an entry stamped in the future — a clock that ran
+    // fast, or `Infinity` — would otherwise pin a stale identity indefinitely.
+    if (typeof cached?.ts !== "number" || cached.ts > now || now - cached.ts > IDENTITY_CACHE_TTL_MS) return null;
+    const identity = cached.identity;
+    if (identity && typeof identity === "object" && identity.vars && typeof identity.vars === "object") {
+      return identity;
+    }
+  } catch { /* a cold or corrupt cache just costs one walk */ }
+  return null;
+}
+
+function writeCache(path, identity, now) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ ts: now, identity }), { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch { /* best effort */ }
+}
+
+/**
+ * Everything the peer templates can substitute, for one cwd.
+ *
+ * `git_remote` and `dir` are already sanitized; `git_root` and `cwd` carry the
+ * legacy byte-for-byte rule, because they are the two that must reproduce a
+ * peer minted before any of this existed.
+ */
+export function resolveWorkspaceIdentity({ cwd = "", env = process.env, cache = true, now = Date.now() } = {}) {
+  const key = String(cwd || "");
+  const path = cachePath(key, env);
+  if (cache) {
+    const hit = readCache(path, now);
+    if (hit) return hit;
+  }
+
+  const { root, rootKind, git, gitRoot } = findWorkspaceRoot(key, env);
+  // Only the normalized form is kept. The raw URL may carry a token, and this
+  // file outlives the process — writing it here would undo the care
+  // `normalizeGitRemote` takes to drop userinfo.
+  const remote = git ? normalizeGitRemote(readGitRemoteUrl(git.commonDir)) : "";
+  const identity = {
+    cwd: key,
+    root,
+    rootKind,
+    isGit: Boolean(git),
+    gitKind: git?.kind || "",
+    gitCommonDir: git?.commonDir || "",
+    gitRoot,
+    remote,
+    vars: {
+      git_remote: sanitizePeerId(remote),
+      // The enclosing repository's root, which is not the workspace root when a
+      // marker file below it won. Empty outside a repository, so the `git`
+      // preset resolves to nothing there rather than to a bare path.
+      git_root: git ? legacySanitize(gitRoot) : "",
+      cwd: legacySanitize(key),
+      dir: root ? sanitizePeerId(root.split(/[/\\]/).filter(Boolean).pop() || "") : "",
+    },
+  };
+  if (cache) writeCache(path, identity, now);
+  return identity;
+}