threadnote 1.4.4 → 1.5.0

package/dist/mcp_server.cjs

@@ -35519,6 +35519,9 @@ function redactText(content) {
     "$1[REDACTED]"
   ).replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]").replace(/sk-[A-Za-z0-9_-]{16,}/g, "sk-[REDACTED]").replace(/gh[pousr]_[A-Za-z0-9_]{16,}/g, "gh_[REDACTED]");
 }
+function escapeRegExp(value) {
+  return value.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+}
 async function requiredOpenVikingCli() {
   const command2 = await findOpenVikingCli();
   if (!command2) {
@@ -35906,14 +35909,19 @@ function exactRecallTerms(query) {
     "after",
     "agent",
     "anything",
+    "been",
     "branch",
     "case",
     "current",
+    "does",
     "durable",
     "find",
     "feature",
     "features",
+    "from",
     "handoff",
+    "have",
+    "into",
     "issue",
     "issues",
     "knowledge",
@@ -35927,11 +35935,22 @@ function exactRecallTerms(query) {
     "related",
     "search",
     "stored",
+    "than",
+    "that",
+    "them",
+    "then",
+    "they",
     "this",
     "the",
+    "were",
+    "what",
+    "when",
+    "which",
+    "while",
     "with",
     "workspace",
-    "worktree"
+    "worktree",
+    "your"
   ]);
   const seen = /* @__PURE__ */ new Set();
   const terms = [];
@@ -35965,6 +35984,12 @@ function exactRecallScopeIntents(query) {
 function isSummarySidecarUri(uri) {
   return /\.(?:overview|abstract)\.md(?:#|$)/.test(uri);
 }
+function isAgentArtifactPackUri(uri) {
+  return /\/agent-artifacts\/packs\//.test(uri);
+}
+function isExcludedRecallUri(uri) {
+  return isSummarySidecarUri(uri) || isAgentArtifactPackUri(uri);
+}
 function grepUrisFromJson(output) {
   const start = output.search(/^\{/m);
   if (start < 0) {
@@ -35979,7 +36004,7 @@ function grepUrisFromJson(output) {
     }
     const uris = [];
     for (const match of matches) {
-      if (isJsonObject(match) && typeof match.uri === "string" && !isSummarySidecarUri(match.uri)) {
+      if (isJsonObject(match) && typeof match.uri === "string" && !isExcludedRecallUri(match.uri)) {
         uris.push(match.uri);
       }
     }
@@ -36021,7 +36046,7 @@ function parseRecallHits(output, options = {}) {
         continue;
       }
       for (const item of items) {
-        if (!isJsonObject(item) || typeof item.uri !== "string" || isSummarySidecarUri(item.uri)) {
+        if (!isJsonObject(item) || typeof item.uri !== "string" || isExcludedRecallUri(item.uri)) {
           continue;
         }
         if (options.includeArchived !== true && isArchivedMemoryUri(item.uri)) {
@@ -36080,6 +36105,9 @@ ${hit.snippet}`;
   return kept;
 }
 function categoryForUri(uri) {
+  if (uri.includes("/agent-artifacts/")) {
+    return "skills";
+  }
   if (uri.includes("/memories/")) {
     return "memories";
   }
@@ -36094,6 +36122,36 @@ function contextTypeForCategory(category) {
   }
   return category === "skills" ? "skill" : "resource";
 }
+var RECALL_EXACT_SLUG_BONUS = 4;
+function uriSlug(uri) {
+  const withoutExtension = stripAnchor(uri).replace(/\.[a-z0-9]+$/i, "");
+  return withoutExtension.slice(withoutExtension.lastIndexOf("/") + 1).toLowerCase();
+}
+function exactTermDocumentFrequency(matches) {
+  const frequency = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    for (const term of new Set(match.terms.map((term2) => term2.toLowerCase()))) {
+      frequency.set(term, (frequency.get(term) ?? 0) + 1);
+    }
+  }
+  return frequency;
+}
+function slugNamesTerm(slug, term) {
+  return new RegExp(`(^|[^a-z0-9])${escapeRegExp(term)}([^a-z0-9]|$)`).test(slug);
+}
+function exactMatchStrength(hit, documentFrequency) {
+  if (!hit.exactTerms?.length) {
+    return 0;
+  }
+  const slug = uriSlug(hit.uri);
+  let strength = 0;
+  for (const term of hit.exactTerms) {
+    const normalized = term.toLowerCase();
+    const rarity = 1 / (documentFrequency.get(normalized) ?? 1);
+    strength += rarity * (slugNamesTerm(slug, normalized) ? RECALL_EXACT_SLUG_BONUS : 1);
+  }
+  return strength;
+}
 function applyExactMatchBoost(hits, exactMatches) {
   if (exactMatches.length === 0) {
     return hits;
@@ -36115,24 +36173,33 @@ function applyExactMatchBoost(hits, exactMatches) {
       uri
     };
   });
-  return [...annotated, ...promoted].sort(
-    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || (right.exactTerms?.length ?? 0) - (left.exactTerms?.length ?? 0) || right.score - left.score
+  const documentFrequency = exactTermDocumentFrequency(exactMatches);
+  const merged = [...annotated, ...promoted];
+  const combinedRelevanceByUri = /* @__PURE__ */ new Map();
+  for (const hit of merged) {
+    combinedRelevanceByUri.set(stripAnchor(hit.uri), exactMatchStrength(hit, documentFrequency) + hit.score);
+  }
+  return merged.sort(
+    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || (combinedRelevanceByUri.get(stripAnchor(right.uri)) ?? 0) - (combinedRelevanceByUri.get(stripAnchor(left.uri)) ?? 0) || right.score - left.score
   );
 }
+var RECALL_LOW_CONFIDENCE_NOTE = "\u26A0 No semantically-relevant matches \u2014 the results below only contain the query words (the corpus may not cover this topic).";
 function renderRecallHits(shown, overflow) {
   if (shown.length === 0) {
     return void 0;
   }
   const lines = shown.flatMap((hit, index) => {
     const scorePart = hit.score > 0 ? `score ${hit.score.toFixed(2)}` : void 0;
-    const exactPart = hit.exactTerms?.length ? `exact: ${hit.exactTerms.join(", ")}` : void 0;
+    const exactLabel = hit.score > 0 ? "exact" : "keyword-only";
+    const exactPart = hit.exactTerms?.length ? `${exactLabel}: ${hit.exactTerms.join(", ")}` : void 0;
     const head = `${index + 1}. ${[hit.contextType, scorePart, exactPart].filter(Boolean).join(" \xB7 ")} \xB7 ${hit.uri}`;
     return hit.snippet ? [head, `   ${hit.snippet}`] : [head];
   });
   if (overflow > 0) {
     lines.push(`(+${overflow} more \u2014 refine the query or read a URI above)`);
   }
-  return lines.join("\n");
+  const noSemanticMatch = shown.every((hit) => hit.score === 0);
+  return (noSemanticMatch ? [RECALL_LOW_CONFIDENCE_NOTE, ...lines] : lines).join("\n");
 }
 var RECALL_CATEGORY_RESERVE = 2;
 function selectShownHits(ranked, limit, reserve) {
@@ -37391,7 +37458,7 @@ async function collectPackMembers(manifestDir, manifest) {
   }
   return [...members.values()].sort((a, b) => compareStrings(a.relativePath, b.relativePath));
 }
-function escapeRegExp(value) {
+function escapeRegExp2(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function tokenizePackPaths(text, rewriteRoots) {
@@ -37399,7 +37466,7 @@ function tokenizePackPaths(text, rewriteRoots) {
   for (const root of rewriteRoots) {
     if (root.length > 0) {
       out = out.replace(
-        new RegExp(`(?<![A-Za-z0-9/._~-])${escapeRegExp(root)}(?=[/\\\\]|["'\`\\s),>:\\]};=]|$)`, "g"),
+        new RegExp(`(?<![A-Za-z0-9/._~-])${escapeRegExp2(root)}(?=[/\\\\]|["'\`\\s),>:\\]};=]|$)`, "g"),
         PACK_ROOT_TOKEN
       );
     }

package/dist/threadnote.cjs

@@ -4202,14 +4202,19 @@ function exactRecallTerms(query) {
     "after",
     "agent",
     "anything",
+    "been",
     "branch",
     "case",
     "current",
+    "does",
     "durable",
     "find",
     "feature",
     "features",
+    "from",
     "handoff",
+    "have",
+    "into",
     "issue",
     "issues",
     "knowledge",
@@ -4223,11 +4228,22 @@ function exactRecallTerms(query) {
     "related",
     "search",
     "stored",
+    "than",
+    "that",
+    "them",
+    "then",
+    "they",
     "this",
     "the",
+    "were",
+    "what",
+    "when",
+    "which",
+    "while",
     "with",
     "workspace",
-    "worktree"
+    "worktree",
+    "your"
   ]);
   const seen = /* @__PURE__ */ new Set();
   const terms = [];
@@ -4261,6 +4277,34 @@ function exactRecallScopeIntents(query) {
 function isSummarySidecarUri(uri) {
   return /\.(?:overview|abstract)\.md(?:#|$)/.test(uri);
 }
+function isAgentArtifactPackUri(uri) {
+  return /\/agent-artifacts\/packs\//.test(uri);
+}
+function isExcludedRecallUri(uri) {
+  return isSummarySidecarUri(uri) || isAgentArtifactPackUri(uri);
+}
+function memoryUriProjectSegment(uri) {
+  const marker = "/memories/";
+  const at = uri.indexOf(marker);
+  if (at < 0) {
+    return void 0;
+  }
+  let segments = stripAnchor(uri).slice(at + marker.length).split("/").filter(Boolean);
+  if (segments[0] === "shared") {
+    segments = segments.slice(2);
+  }
+  const [kind, , project, ...rest] = segments;
+  if ((kind === "durable" || kind === "handoffs" || kind === "incidents") && project && rest.length > 0) {
+    return project;
+  }
+  return void 0;
+}
+function memoryFrontmatterField(content, field) {
+  const blankLine = content.indexOf("\n\n");
+  const header = blankLine < 0 ? content : content.slice(0, blankLine);
+  const match = header.match(new RegExp(`^${escapeRegExp(field)}:[ \\t]*(.+)$`, "m"));
+  return match?.[1]?.trim() || void 0;
+}
 function grepUrisFromJson(output2) {
   const start = output2.search(/^\{/m);
   if (start < 0) {
@@ -4275,7 +4319,7 @@ function grepUrisFromJson(output2) {
     }
     const uris = [];
     for (const match of matches) {
-      if (isJsonObject(match) && typeof match.uri === "string" && !isSummarySidecarUri(match.uri)) {
+      if (isJsonObject(match) && typeof match.uri === "string" && !isExcludedRecallUri(match.uri)) {
         uris.push(match.uri);
       }
     }
@@ -4317,7 +4361,7 @@ function parseRecallHits(output2, options = {}) {
         continue;
       }
       for (const item of items) {
-        if (!isJsonObject(item) || typeof item.uri !== "string" || isSummarySidecarUri(item.uri)) {
+        if (!isJsonObject(item) || typeof item.uri !== "string" || isExcludedRecallUri(item.uri)) {
           continue;
         }
         if (options.includeArchived !== true && isArchivedMemoryUri(item.uri)) {
@@ -4376,6 +4420,9 @@ ${hit.snippet}`;
   return kept;
 }
 function categoryForUri(uri) {
+  if (uri.includes("/agent-artifacts/")) {
+    return "skills";
+  }
   if (uri.includes("/memories/")) {
     return "memories";
   }
@@ -4390,6 +4437,36 @@ function contextTypeForCategory(category) {
   }
   return category === "skills" ? "skill" : "resource";
 }
+var RECALL_EXACT_SLUG_BONUS = 4;
+function uriSlug(uri) {
+  const withoutExtension = stripAnchor(uri).replace(/\.[a-z0-9]+$/i, "");
+  return withoutExtension.slice(withoutExtension.lastIndexOf("/") + 1).toLowerCase();
+}
+function exactTermDocumentFrequency(matches) {
+  const frequency = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    for (const term of new Set(match.terms.map((term2) => term2.toLowerCase()))) {
+      frequency.set(term, (frequency.get(term) ?? 0) + 1);
+    }
+  }
+  return frequency;
+}
+function slugNamesTerm(slug, term) {
+  return new RegExp(`(^|[^a-z0-9])${escapeRegExp(term)}([^a-z0-9]|$)`).test(slug);
+}
+function exactMatchStrength(hit, documentFrequency) {
+  if (!hit.exactTerms?.length) {
+    return 0;
+  }
+  const slug = uriSlug(hit.uri);
+  let strength = 0;
+  for (const term of hit.exactTerms) {
+    const normalized = term.toLowerCase();
+    const rarity = 1 / (documentFrequency.get(normalized) ?? 1);
+    strength += rarity * (slugNamesTerm(slug, normalized) ? RECALL_EXACT_SLUG_BONUS : 1);
+  }
+  return strength;
+}
 function applyExactMatchBoost(hits, exactMatches) {
   if (exactMatches.length === 0) {
     return hits;
@@ -4411,24 +4488,33 @@ function applyExactMatchBoost(hits, exactMatches) {
       uri
     };
   });
-  return [...annotated, ...promoted].sort(
-    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || (right.exactTerms?.length ?? 0) - (left.exactTerms?.length ?? 0) || right.score - left.score
+  const documentFrequency = exactTermDocumentFrequency(exactMatches);
+  const merged = [...annotated, ...promoted];
+  const combinedRelevanceByUri = /* @__PURE__ */ new Map();
+  for (const hit of merged) {
+    combinedRelevanceByUri.set(stripAnchor(hit.uri), exactMatchStrength(hit, documentFrequency) + hit.score);
+  }
+  return merged.sort(
+    (left, right) => recallCategoryRank(left.category) - recallCategoryRank(right.category) || (combinedRelevanceByUri.get(stripAnchor(right.uri)) ?? 0) - (combinedRelevanceByUri.get(stripAnchor(left.uri)) ?? 0) || right.score - left.score
   );
 }
+var RECALL_LOW_CONFIDENCE_NOTE = "\u26A0 No semantically-relevant matches \u2014 the results below only contain the query words (the corpus may not cover this topic).";
 function renderRecallHits(shown, overflow) {
   if (shown.length === 0) {
     return void 0;
   }
   const lines = shown.flatMap((hit, index) => {
     const scorePart = hit.score > 0 ? `score ${hit.score.toFixed(2)}` : void 0;
-    const exactPart = hit.exactTerms?.length ? `exact: ${hit.exactTerms.join(", ")}` : void 0;
+    const exactLabel = hit.score > 0 ? "exact" : "keyword-only";
+    const exactPart = hit.exactTerms?.length ? `${exactLabel}: ${hit.exactTerms.join(", ")}` : void 0;
     const head = `${index + 1}. ${[hit.contextType, scorePart, exactPart].filter(Boolean).join(" \xB7 ")} \xB7 ${hit.uri}`;
     return hit.snippet ? [head, `   ${hit.snippet}`] : [head];
   });
   if (overflow > 0) {
     lines.push(`(+${overflow} more \u2014 refine the query or read a URI above)`);
   }
-  return lines.join("\n");
+  const noSemanticMatch = shown.every((hit) => hit.score === 0);
+  return (noSemanticMatch ? [RECALL_LOW_CONFIDENCE_NOTE, ...lines] : lines).join("\n");
 }
 var RECALL_CATEGORY_RESERVE = 2;
 function selectShownHits(ranked, limit, reserve) {
@@ -11768,6 +11854,13 @@ async function storeMemory(config, options) {
     console.log(`Updated existing memory in place: ${memoryUri}`);
   }
 }
+function warnOnSharedProjectDrift(metadata, inferred) {
+  if (inferred?.project && metadata.project && uriSegment(metadata.project) !== inferred.project) {
+    console.log(
+      `WARN keeping shared memory project "${inferred.project}" from its storage path; ignoring requested "${metadata.project}". To change a shared memory's project, forget it and store a new one under the new project.`
+    );
+  }
+}
 async function storeSharedMemoryReplacement(config, ov, options, targetUri) {
   if (options.metadata.kind !== "durable") {
     throw new Error("Shared memory replacement only supports durable memories.");
@@ -11778,9 +11871,10 @@ async function storeSharedMemoryReplacement(config, ov, options, targetUri) {
   }
   const team = await resolveTeam(config, teamName);
   const inferred = sharedMemoryUriParts(config, targetUri);
+  warnOnSharedProjectDrift(options.metadata, inferred);
   const metadata = {
     ...options.metadata,
-    project: options.metadata.project ?? inferred?.project,
+    project: inferred?.project ?? options.metadata.project,
     topic: options.metadata.topic ?? inferred?.topic
   };
   const rawMemory = formatMemoryDocument2(options.title, metadata, options.bodyText);
@@ -13703,6 +13797,7 @@ function isUpdateNotificationDisabled() {
 }
 
 // src/lifecycle.ts
+var INSTALL_OUTPUT_TAIL_CHARS = 64e3;
 async function runDoctor(config, options) {
   const checks = await collectDoctorChecks(config, options);
   for (const check of checks) {
@@ -13735,6 +13830,7 @@ async function collectDoctorChecks(config, options = {}) {
   checks.push(...await userAgentInstructionsChecks());
   checks.push(await manifestCheck(config.manifestPath));
   checks.push(await recallIndexFreshnessCheck(config));
+  checks.push(await memoryProjectConsistencyCheck(config));
   checks.push(await fileCheck((0, import_node_path14.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
   checks.push(await fileCheck((0, import_node_path14.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
   checks.push(await fileCheck((0, import_node_path14.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
@@ -14427,6 +14523,61 @@ async function recallIndexFreshnessCheck(config) {
     return { name: "recall index freshness", status: "warn", detail: errorMessage(err) };
   }
 }
+async function memoryProjectConsistencyCheck(config) {
+  const name = "memory project consistency";
+  const memoriesRoot = (0, import_node_path14.join)(
+    config.agentContextHome,
+    "data",
+    "viking",
+    config.account,
+    "user",
+    uriSegment(config.user),
+    "memories"
+  );
+  try {
+    let entries;
+    try {
+      entries = await (0, import_promises12.readdir)(memoriesRoot, { recursive: true });
+    } catch {
+      return { name, status: "ok", detail: "no memories directory yet" };
+    }
+    const mismatches = [];
+    let checked = 0;
+    for (const entry of entries) {
+      if (!entry.endsWith(".md") || isSummarySidecarUri(entry)) {
+        continue;
+      }
+      const uri = `viking://user/${uriSegment(config.user)}/memories/${entry.split(import_node_path14.sep).join("/")}`;
+      const pathProject = memoryUriProjectSegment(uri);
+      if (!pathProject) {
+        continue;
+      }
+      let content;
+      try {
+        content = await (0, import_promises12.readFile)((0, import_node_path14.join)(memoriesRoot, entry), "utf8");
+      } catch {
+        continue;
+      }
+      checked += 1;
+      const frontProject = memoryFrontmatterField(content, "project");
+      if (frontProject && uriSegment(frontProject) !== pathProject) {
+        mismatches.push(`${uri} (frontmatter "${frontProject}" vs path "${pathProject}")`);
+      }
+    }
+    if (mismatches.length === 0) {
+      return { name, status: "ok", detail: `${checked} project-scoped memories consistent` };
+    }
+    const sample = mismatches.slice(0, 3).join("; ");
+    const extra = Math.max(0, mismatches.length - 3);
+    return {
+      name,
+      status: "warn",
+      detail: `${mismatches.length} memory(ies) whose frontmatter project differs from their storage path; re-store under the correct project to fix: ${sample}${extra > 0 ? `, +${extra} more` : ""}`
+    };
+  } catch (err) {
+    return { name, status: "warn", detail: errorMessage(err) };
+  }
+}
 async function fileCheck(path2, label) {
   return await exists(path2) ? { name: label, status: "ok", detail: path2 } : { name: label, status: "fail", detail: `${path2} missing` };
 }
@@ -14487,32 +14638,169 @@ async function runInstallCommands(config, preferred, force, dryRun) {
       continue;
     }
     console.log(`Running: ${formatShellCommand(installCommand.executable, installCommand.args)}`);
-    const exitCode = await runInteractive(installCommand.executable, installCommand.args);
-    if (exitCode !== 0) {
-      printOpenVikingInstallFailureHelp(installCommand);
-      throw new Error(`${formatShellCommand(installCommand.executable, installCommand.args)} exited with ${exitCode}.`);
+    const result = await runInstallCommand(installCommand);
+    if (result.exitCode !== 0) {
+      const commandOutput = `${result.stderr}
+${result.stdout}`;
+      const retry = openVikingSourceBuildRetryForArchiveFailure(installCommand, commandOutput);
+      if (retry) {
+        console.error("");
+        console.error(
+          "The prebuilt llama-cpp-python wheel failed ZIP archive validation; retrying with a local source build."
+        );
+        console.error("This avoids the rejected wheel and can take 10-20 minutes.");
+        console.log(`Running: ${formatInstallCommand(retry.command, retry.env)}`);
+        const retryResult = await runInstallCommand(retry.command, retry.env);
+        if (retryResult.exitCode === 0) {
+          continue;
+        }
+        printOpenVikingInstallFailureHelp(retry.command, `${retryResult.stderr}
+${retryResult.stdout}`);
+        throw new Error(
+          `${formatInstallCommand(retry.command, retry.env)} exited with ${retryResult.exitCode} after automatic source-build retry.`
+        );
+      }
+      printOpenVikingInstallFailureHelp(installCommand, commandOutput);
+      throw new Error(
+        `${formatShellCommand(installCommand.executable, installCommand.args)} exited with ${result.exitCode}.`
+      );
     }
   }
 }
-function printOpenVikingInstallFailureHelp(failedCommand) {
-  console.error("");
-  console.error("OpenViking install did not complete.");
-  console.error(
-    "openviking[local-embed] includes llama-cpp-python, which compiles from source when no prebuilt wheel matches your Python/platform \u2014 that build can run 10-20 minutes and is memory-heavy, so it may be killed by the OS (out of memory) or look stuck."
-  );
-  console.error("Re-run it directly to see full output without any wrapper timeout:");
-  console.error(`  ${formatShellCommand(failedCommand.executable, failedCommand.args)}`);
-  console.error("Cap memory use during the compile with: CMAKE_BUILD_PARALLEL_LEVEL=2 <command above>");
+async function runInstallCommand(command2, env = {}) {
+  return new Promise((resolvePromise) => {
+    let stdout2 = "";
+    let stderr = "";
+    let settled = false;
+    const child = (0, import_node_child_process4.spawn)(command2.executable, command2.args, {
+      env: Object.keys(env).length === 0 ? process.env : { ...process.env, ...env },
+      stdio: ["inherit", "pipe", "pipe"]
+    });
+    child.stdout?.on("data", (chunk) => {
+      const text = String(chunk);
+      import_node_process4.stdout.write(text);
+      stdout2 = appendInstallOutputTail(stdout2, text);
+    });
+    child.stderr?.on("data", (chunk) => {
+      const text = String(chunk);
+      import_node_process4.stderr.write(text);
+      stderr = appendInstallOutputTail(stderr, text);
+    });
+    child.on("error", (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const message = errorMessage(err);
+      import_node_process4.stderr.write(`${message}
+`);
+      resolvePromise({ exitCode: 1, stderr: appendInstallOutputTail(stderr, message), stdout: stdout2 });
+    });
+    child.on("close", (code) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolvePromise({ exitCode: code ?? 1, stderr, stdout: stdout2 });
+    });
+  });
+}
+function appendInstallOutputTail(current, chunk) {
+  const next = `${current}${chunk}`;
+  return next.length <= INSTALL_OUTPUT_TAIL_CHARS ? next : next.slice(next.length - INSTALL_OUTPUT_TAIL_CHARS);
+}
+function printOpenVikingInstallFailureHelp(failedCommand, commandOutput) {
+  for (const line of openVikingInstallFailureHelpLines(failedCommand, commandOutput)) {
+    console.error(line);
+  }
+}
+function openVikingInstallFailureHelpLines(failedCommand, commandOutput = "") {
+  if (isLlamaWheelArchiveExtractionFailure(commandOutput)) {
+    return [
+      "",
+      "OpenViking install did not complete.",
+      "The prebuilt llama-cpp-python wheel failed ZIP archive validation. Threadnote only falls back to a source build automatically when the failed command came from a prebuilt wheel index."
+    ];
+  }
+  const lines = [
+    "",
+    "OpenViking install did not complete.",
+    "openviking[local-embed] includes llama-cpp-python, which compiles from source when no prebuilt wheel matches your Python/platform \u2014 that build can run 10-20 minutes and is memory-heavy, so it may be killed by the OS (out of memory) or look stuck.",
+    "The package-manager output above contains the underlying build or download error."
+  ];
   if (failedCommand.executable === "uv") {
     if (failedCommand.args.includes("--python")) {
-      console.error(
-        "If uv could not fetch a managed CPython (offline or restricted network), drop the version pin and retry: THREADNOTE_OPENVIKING_PYTHON= threadnote install --force"
+      lines.push(
+        "If uv could not fetch managed CPython, Threadnote cannot complete the local install until that Python download is available."
       );
     }
-    console.error("If it was killed mid-build, clear the partial install first, then retry:");
-    console.error("  uv cache clean");
-    console.error('  rm -rf "$(uv tool dir)/openviking"');
   }
+  return lines;
+}
+function isLlamaWheelArchiveExtractionFailure(output2) {
+  const normalized = output2.toLowerCase();
+  return (normalized.includes("llama-cpp-python") || normalized.includes("llama_cpp_python")) && (normalized.includes("failed to extract archive") || normalized.includes("zip file contains trailing contents after the end-of-central-directory record"));
+}
+function openVikingSourceBuildRetryForArchiveFailure(failedCommand, commandOutput) {
+  if (!isLlamaWheelArchiveExtractionFailure(commandOutput)) {
+    return void 0;
+  }
+  const command2 = withoutExtraIndexUrl(failedCommand);
+  if (!command2) {
+    return void 0;
+  }
+  return { command: command2, env: sourceBuildEnvironment(failedCommand) };
+}
+function withoutExtraIndexUrl(command2) {
+  const args = [];
+  let changed = false;
+  for (let index = 0; index < command2.args.length; index += 1) {
+    const arg = command2.args[index];
+    const next = command2.args[index + 1];
+    if (arg === "--extra-index-url" && next !== void 0) {
+      changed = true;
+      index += 1;
+      continue;
+    }
+    if (arg === "--pip-args" && next?.includes("--extra-index-url") === true) {
+      changed = true;
+      index += 1;
+      continue;
+    }
+    args.push(arg);
+  }
+  return changed ? { ...command2, args } : void 0;
+}
+function formatInstallCommand(command2, env = {}) {
+  return [...formatEnvironmentAssignments(env), formatShellCommand(command2.executable, command2.args)].join(" ");
+}
+function formatEnvironmentAssignments(env) {
+  return Object.entries(env).map(
+    ([key, value]) => key === "CMAKE_ARGS" ? `${key}="${value.replaceAll('"', '\\"')}"` : `${key}=${shellQuote(value)}`
+  );
+}
+function sourceBuildEnvironment(command2) {
+  const env = {};
+  if (extraIndexUrl(command2)?.replace(/\/+$/, "").toLowerCase().endsWith("/metal") === true) {
+    env.CMAKE_ARGS = "-DGGML_METAL=on";
+  }
+  env.CMAKE_BUILD_PARALLEL_LEVEL = "2";
+  return env;
+}
+function extraIndexUrl(command2) {
+  for (let index = 0; index < command2.args.length; index += 1) {
+    const arg = command2.args[index];
+    if (arg === "--extra-index-url") {
+      return command2.args[index + 1];
+    }
+    if (arg === "--pip-args") {
+      const match = command2.args[index + 1]?.match(/(?:^|\s)--extra-index-url\s+(\S+)/);
+      if (match) {
+        return match[1];
+      }
+    }
+  }
+  return void 0;
 }
 async function offerToInstallUv() {
   if (import_node_process4.stdin.isTTY !== true || import_node_process4.stdout.isTTY !== true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",
@@ -59,7 +59,7 @@
     "doctor": "npm run build --silent && node ./bin/threadnote.cjs doctor",
     "mcp-server": "npm run build --silent && node ./bin/threadnote-mcp-server.cjs",
     "pack:dry-run": "npm pack --dry-run",
-    "typecheck": "tsc --noEmit && tsc -p test/tsconfig.json --noEmit"
+    "typecheck": "node ./node_modules/typescript-7/bin/tsc --noEmit && node ./node_modules/typescript-7/bin/tsc -p test/tsconfig.json --noEmit"
   },
   "engines": {
     "node": ">=20"
@@ -68,7 +68,7 @@
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.0.1",
     "@types/react": "^19.2.16",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.1.7",
@@ -83,6 +83,7 @@
     "react-dom": "^19.2.7",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
+    "typescript-7": "npm:typescript@7.0.1-rc",
     "typescript-eslint": "^8.59.2",
     "vitest": "^4.1.7",
     "zod": "^4.4.3"