threadnote 1.0.0 → 1.1.0

package/dist/threadnote.cjs

@@ -3616,6 +3616,41 @@ async function withSpinner(message, action) {
     (0, import_node_readline.cursorTo)(import_node_process.stdout, 0);
   }
 }
+function startProgress(message) {
+  if (import_node_process.stdout.isTTY !== true || process.env.CI !== void 0 || process.env.THREADNOTE_NO_SPINNER !== void 0) {
+    console.log(message);
+    return {
+      update(nextMessage) {
+        console.log(nextMessage);
+      },
+      stop() {
+        return;
+      }
+    };
+  }
+  const frames = ["-", "\\", "|", "/"];
+  let frameIndex = 0;
+  let currentMessage = message;
+  const render = () => {
+    (0, import_node_readline.clearLine)(import_node_process.stdout, 0);
+    (0, import_node_readline.cursorTo)(import_node_process.stdout, 0);
+    import_node_process.stdout.write(`${muted(frames[frameIndex])} ${currentMessage}`);
+    frameIndex = (frameIndex + 1) % frames.length;
+  };
+  const timer = setInterval(render, 100);
+  render();
+  return {
+    update(nextMessage) {
+      currentMessage = nextMessage;
+      render();
+    },
+    stop() {
+      clearInterval(timer);
+      (0, import_node_readline.clearLine)(import_node_process.stdout, 0);
+      (0, import_node_readline.cursorTo)(import_node_process.stdout, 0);
+    }
+  };
+}
 
 // src/utils.ts
 function isJsonObject(value) {
@@ -3753,15 +3788,11 @@ async function maybeRun(dryRun, executable, args, options = {}) {
 }
 async function runCommand(executable, args, options = {}) {
   return new Promise((resolvePromise, rejectPromise) => {
-    const child = (0, import_node_child_process.spawn)(executable, args, { cwd: options.cwd });
-    const stdoutChunks = [];
-    const stderrChunks = [];
     const maxOutputBytes = options.maxOutputBytes ?? defaultCommandMaxOutputBytes();
-    let stdoutBytes = 0;
-    let stderrBytes = 0;
     let finished = false;
-    let failureResult;
     let killTimer;
+    let killEscalationTimer;
+    let failureMessage;
     let sentTerminationSignal = false;
     const timeoutMs = options.timeoutMs ?? defaultCommandTimeoutMs();
     const finish = (result) => {
@@ -3772,22 +3803,47 @@ async function runCommand(executable, args, options = {}) {
       if (killTimer) {
         clearTimeout(killTimer);
       }
+      if (killEscalationTimer) {
+        clearTimeout(killEscalationTimer);
+      }
       if (result.exitCode !== 0 && options.allowFailure !== true) {
         rejectPromise(new Error(`${formatShellCommand(executable, args)} failed: ${result.stderr || result.stdout}`));
         return;
       }
       resolvePromise(result);
     };
+    const child = (0, import_node_child_process.execFile)(
+      executable,
+      [...args],
+      {
+        cwd: options.cwd,
+        encoding: "utf8",
+        maxBuffer: maxOutputBytes
+      },
+      (err, stdout2, stderr) => {
+        finish(
+          commandResultFromExecFileCallback({
+            args,
+            err,
+            executable,
+            failureMessage,
+            maxOutputBytes,
+            stderr,
+            stdout: stdout2
+          })
+        );
+      }
+    );
     const failAndKill = (message) => {
-      if (failureResult) {
+      if (failureMessage) {
         return;
       }
-      failureResult = { exitCode: 124, stderr: message, stdout: stdoutChunks.join("") };
+      failureMessage = message;
       if (!sentTerminationSignal) {
         sentTerminationSignal = true;
         child.kill("SIGTERM");
       }
-      setTimeout(() => {
+      killEscalationTimer = setTimeout(() => {
         if (!finished) {
           child.kill("SIGKILL");
         }
@@ -3799,54 +3855,20 @@ async function runCommand(executable, args, options = {}) {
       }, timeoutMs);
       killTimer.unref?.();
     }
-    child.stdout.on("data", (chunk) => {
-      if (failureResult) {
-        return;
-      }
-      const text = String(chunk);
-      stdoutBytes += Buffer.byteLength(text);
-      if (stdoutBytes + stderrBytes > maxOutputBytes) {
-        failAndKill(`${formatShellCommand(executable, args)} exceeded output limit of ${maxOutputBytes} bytes`);
-        return;
-      }
-      stdoutChunks.push(text);
-    });
-    child.stderr.on("data", (chunk) => {
-      if (failureResult) {
-        return;
-      }
-      const text = String(chunk);
-      stderrBytes += Buffer.byteLength(text);
-      if (stdoutBytes + stderrBytes > maxOutputBytes) {
-        failAndKill(`${formatShellCommand(executable, args)} exceeded output limit of ${maxOutputBytes} bytes`);
-        return;
-      }
-      stderrChunks.push(text);
-    });
-    child.on("error", (err) => {
-      if (finished) {
-        return;
-      }
-      if (killTimer) {
-        clearTimeout(killTimer);
-      }
-      if (options.allowFailure === true) {
-        finish({ exitCode: 127, stderr: errorMessage(err), stdout: "" });
-      } else {
-        finished = true;
-        rejectPromise(err);
-      }
-    });
-    child.on("close", (code) => {
-      const result = failureResult ?? {
-        exitCode: code ?? 1,
-        stderr: stderrChunks.join(""),
-        stdout: stdoutChunks.join("")
-      };
-      finish(result);
-    });
   });
 }
+function commandResultFromExecFileCallback(params) {
+  if (params.failureMessage) {
+    return { exitCode: 124, stderr: params.failureMessage, stdout: params.stdout };
+  }
+  if (!params.err) {
+    return { exitCode: 0, stderr: params.stderr, stdout: params.stdout };
+  }
+  const error = params.err;
+  const exitCode = typeof error.code === "number" ? error.code : error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ? 124 : 127;
+  const stderr = error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ? `${formatShellCommand(params.executable, params.args)} exceeded output limit of ${params.maxOutputBytes} bytes` : params.stderr || errorMessage(error);
+  return { exitCode, stderr, stdout: params.stdout };
+}
 function defaultCommandTimeoutMs() {
   return positiveIntegerFromEnv("THREADNOTE_COMMAND_TIMEOUT_MS") ?? 10 * 60 * 1e3;
 }
@@ -7529,9 +7551,17 @@ var AUTO_REPAIR_STATE_FILE = "index-auto-repair.json";
 var AUTO_REPAIR_TTL_MS = 6 * 60 * 60 * 1e3;
 var MAX_SCAN_DEPTH = 5;
 var MAX_REPAIR_TARGETS = 4;
-var MAINTENANCE_MAX_REPAIR_TARGETS = 16;
+var MAINTENANCE_COLLAPSE_DEPTH = 3;
+var MAINTENANCE_MAX_REPAIR_TARGETS = 512;
 async function repairStaleRecallIndex(config, ov, options = {}) {
+  options.onProgress?.({ type: "scan-start" });
   const targets = await findStaleRecallIndexTargets(config, options);
+  const repairTargets = targets.slice(0, options.maxTargets ?? MAX_REPAIR_TARGETS);
+  options.onProgress?.({
+    repairTargetCount: repairTargets.length,
+    totalTargets: targets.length,
+    type: "scan-complete"
+  });
   if (targets.length === 0) {
     return { repairedUris: [], skippedRecentUris: [], warnings: [] };
   }
@@ -7540,16 +7570,20 @@ async function repairStaleRecallIndex(config, ov, options = {}) {
   const repairedUris = [];
   const skippedRecentUris = [];
   const warnings = [];
-  for (const target of targets.slice(0, options.maxTargets ?? MAX_REPAIR_TARGETS)) {
+  for (const [targetIndex, target] of repairTargets.entries()) {
+    const progressBase = { index: targetIndex + 1, target, total: repairTargets.length };
     const previous = state.entries[target.uri];
     if (previous?.signature === target.signature && now - Date.parse(previous.repairedAt) < AUTO_REPAIR_TTL_MS && options.dryRun !== true && options.ignoreBackoff !== true) {
+      options.onProgress?.({ ...progressBase, type: "repair-skip-recent" });
       skippedRecentUris.push(target.uri);
       continue;
     }
     if (options.dryRun === true) {
+      options.onProgress?.({ ...progressBase, type: "repair-dry-run" });
       repairedUris.push(target.uri);
       continue;
     }
+    options.onProgress?.({ ...progressBase, type: "repair-start" });
     const result = await runCommand(
       ov,
       withIdentity(config, ["reindex", target.uri, "--mode", "semantic_and_vectors", "--wait", "true"]),
@@ -7560,6 +7594,7 @@ async function repairStaleRecallIndex(config, ov, options = {}) {
       state.entries[target.uri] = { repairedAt: new Date(now).toISOString(), signature: target.signature };
     } else {
       warnings.push(indexRepairWarning(target.uri, result));
+      await options.onRepairFailure?.(target, result);
     }
   }
   if (options.dryRun !== true && repairedUris.length > 0) {
@@ -7576,16 +7611,14 @@ async function findStaleRecallIndexTargets(config, options = {}) {
     }
     const sidecars = await staleSidecars(root.path, root.uri);
     if (options.collapseToRoots === true) {
-      if (sidecars.length === 0) {
-        continue;
-      }
-      const parts = sidecars.map((sidecar) => `${sidecar.relativePath}
+      for (const sidecar of sidecars) {
+        const uri = collapseStaleSidecarUri(root.uri, sidecar.relativePath, options.collapseDepth);
+        const current = byUri.get(uri) ?? { parts: [], staleCount: 0, uri };
+        current.parts.push(`${sidecar.relativePath}
 ${sidecar.content}`);
-      byUri.set(root.uri, {
-        parts,
-        staleCount: sidecars.length,
-        uri: root.uri
-      });
+        current.staleCount += 1;
+        byUri.set(uri, current);
+      }
       continue;
     }
     for (const sidecar of sidecars) {
@@ -7602,13 +7635,29 @@ ${sidecar.content}`);
     uri: target.uri
   }));
 }
+function collapseStaleSidecarUri(rootUri, relativePath, depth = 0) {
+  const normalizedRootUri = trimLocalRootUri(rootUri);
+  if (depth <= 0) {
+    return normalizedRootUri;
+  }
+  const parentParts = relativePath.split("/").slice(0, -1);
+  const collapsedParts = parentParts.slice(0, depth);
+  return collapsedParts.length === 0 ? normalizedRootUri : `${normalizedRootUri}/${collapsedParts.join("/")}`;
+}
 function formatRecallIndexRepairMessages(result, options = {}) {
   const messages = [];
-  for (const uri of result.repairedUris) {
+  const maxUris = options.maxUris ?? result.repairedUris.length;
+  for (const uri of result.repairedUris.slice(0, maxUris)) {
     messages.push(
       `${options.dryRun === true ? "Would auto-reindex stale recall scope" : "Auto-reindexed stale recall scope"}: ${uri}`
     );
   }
+  const hiddenUriCount = result.repairedUris.length - maxUris;
+  if (hiddenUriCount > 0) {
+    messages.push(
+      options.dryRun === true ? `Would auto-reindex ${hiddenUriCount} more stale recall scope(s).` : `Auto-reindexed ${hiddenUriCount} more stale recall scope(s).`
+    );
+  }
   for (const warning2 of result.warnings) {
     messages.push(`Auto-index repair warning: ${warning2}`);
   }
@@ -11622,7 +11671,9 @@ async function runUpdate(config, options) {
     return;
   }
   const threadnoteCommand = await installedThreadnoteCommand(runtime);
-  await maybeRun(options.dryRun === true, threadnoteCommand, ["repair", "--no-post-update"]);
+  console.log("");
+  console.log("Repairing local Threadnote setup after package update.");
+  await runThreadnoteSubcommand(options.dryRun === true, threadnoteCommand, ["repair", "--no-post-update"]);
   if (options.postUpdate !== false) {
     const postUpdateArgs = [
       "post-update",
@@ -11632,15 +11683,7 @@ async function runUpdate(config, options) {
       info2.latestVersion,
       ...options.yes === true ? ["--yes"] : []
     ];
-    if (options.dryRun === true) {
-      await maybeRun(true, threadnoteCommand, postUpdateArgs);
-    } else {
-      console.log(`Running: ${formatShellCommand(threadnoteCommand, postUpdateArgs)}`);
-      const postUpdateExitCode = await runInteractive(threadnoteCommand, postUpdateArgs);
-      if (postUpdateExitCode !== 0) {
-        throw new Error(`${formatShellCommand(threadnoteCommand, postUpdateArgs)} exited with ${postUpdateExitCode}.`);
-      }
-    }
+    await runThreadnoteSubcommand(options.dryRun === true, threadnoteCommand, postUpdateArgs);
   } else {
     console.log("Skipping post-update migration prompts because --no-post-update was provided.");
   }
@@ -11742,9 +11785,11 @@ async function ensurePinnedOpenVikingInstalled(config, options) {
   if (usingLaunchd) {
     const launchAgentPath = launchAgentPlistPath();
     await runCommand("launchctl", ["unload", launchAgentPath], { allowFailure: true });
+    await waitForOpenVikingPortClosed(config, 15e3);
     await runCommand("launchctl", ["load", launchAgentPath], { allowFailure: true });
   } else {
     await maybeRun(false, threadnoteCommand, ["stop"]);
+    await waitForOpenVikingPortClosed(config, 15e3);
     await maybeRun(false, threadnoteCommand, ["start"]);
   }
   const healthyAfter = await waitForOpenVikingHealthy(config, 1e4);
@@ -11755,6 +11800,17 @@ async function ensurePinnedOpenVikingInstalled(config, options) {
     console.log("Check the server log or run: threadnote start");
   }
 }
+async function runThreadnoteSubcommand(dryRun, executable, args) {
+  if (dryRun) {
+    await maybeRun(true, executable, args);
+    return;
+  }
+  console.log(`Running: ${formatShellCommand(executable, args)}`);
+  const exitCode = await runInteractive(executable, args);
+  if (exitCode !== 0) {
+    throw new Error(`${formatShellCommand(executable, args)} exited with ${exitCode}.`);
+  }
+}
 function openVikingHealthEndpoint(config) {
   return `http://${config.host}:${config.port}/health`;
 }
@@ -11778,12 +11834,27 @@ async function waitForOpenVikingHealthy(config, timeoutMs) {
     if (await isOpenVikingHealthy(config)) {
       return true;
     }
-    await new Promise((resolvePromise) => {
-      setTimeout(resolvePromise, 500);
-    });
+    await sleep(500);
   }
   return isOpenVikingHealthy(config);
 }
+async function waitForOpenVikingPortClosed(config, timeoutMs) {
+  console.log(`Waiting for OpenViking port ${config.host}:${config.port} to close before restart.`);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await isTcpPortOpen(config.host, config.port, 300)) {
+      return true;
+    }
+    await sleep(300);
+  }
+  if (!await isTcpPortOpen(config.host, config.port, 300)) {
+    return true;
+  }
+  console.log(
+    `Warning: OpenViking port ${config.host}:${config.port} is still in use after ${timeoutMs / 1e3}s; start may fail.`
+  );
+  return false;
+}
 function launchAgentPlistPath() {
   return (0, import_node_path12.join)((0, import_node_os5.homedir)(), "Library", "LaunchAgents", "io.threadnote.openviking.plist");
 }
@@ -12314,16 +12385,44 @@ async function repairRecallIndex(config, dryRun) {
     console.log("Skipping recall index repair: neither ov nor openviking was found in PATH.");
     return;
   }
+  const progress = startProgress("Scanning recall index freshness across memories and seeded resources.");
   try {
     const result = await repairStaleRecallIndex(config, ov, {
+      collapseDepth: MAINTENANCE_COLLAPSE_DEPTH,
       collapseToRoots: true,
       dryRun,
       ignoreBackoff: true,
       includeAgentSkills: true,
       includeManifestResources: true,
-      maxTargets: MAINTENANCE_MAX_REPAIR_TARGETS
+      maxTargets: MAINTENANCE_MAX_REPAIR_TARGETS,
+      onRepairFailure: async () => {
+        progress.update("A recall index reindex failed; checking OpenViking health before continuing.");
+        await repairServerHealth(config, dryRun);
+      },
+      onProgress: (event) => {
+        if (event.type === "scan-complete") {
+          if (event.totalTargets === 0) {
+            progress.update("No stale recall index scopes found.");
+          } else {
+            progress.update(
+              `Found ${event.totalTargets} stale recall index scope(s); repairing ${event.repairTargetCount}.`
+            );
+          }
+        } else if (event.type === "repair-start") {
+          progress.update(
+            `Reindexing ${event.index}/${event.total}: ${event.target.uri} (${event.target.staleCount} stale summaries).`
+          );
+        } else if (event.type === "repair-dry-run") {
+          progress.update(
+            `Planning reindex ${event.index}/${event.total}: ${event.target.uri} (${event.target.staleCount} stale summaries).`
+          );
+        } else if (event.type === "repair-skip-recent") {
+          progress.update(`Skipping recently repaired scope ${event.index}/${event.total}: ${event.target.uri}.`);
+        }
+      }
     });
-    const messages = formatRecallIndexRepairMessages(result, { dryRun });
+    progress.stop();
+    const messages = formatRecallIndexRepairMessages(result, { dryRun, maxUris: 20 });
     if (messages.length === 0) {
       console.log("Recall index freshness OK.");
       return;
@@ -12332,6 +12431,7 @@ async function repairRecallIndex(config, dryRun) {
       console.log(message);
     }
   } catch (err) {
+    progress.stop();
     console.log(`WARN could not repair recall index freshness: ${errorMessage(err)}`);
   }
 }

package/docs/troubleshooting.md

@@ -124,6 +124,10 @@ Threadnote uses its bundled stdio MCP adapter by default, even when the installe
 `/mcp`. The adapter adds Threadnote-specific tools and behavior such as shared-memory sync, exact recall fallback,
 seeded-resource recall augmentation, and recall-index repair.
 
+The adapter also exposes raw OpenViking parity tools with `ov_*` names for native behaviors such as code symbol
+navigation, watch management, raw search/read/list/store/remember, grep/glob, resource import, and forget. Prefer
+Threadnote-named tools for memory workflows; use `ov_*` when you intentionally want native OpenViking behavior.
+
 Use the default stdio adapter:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",