threadnote 0.4.0 → 0.5.0

package/dist/threadnote.cjs

@@ -3498,6 +3498,12 @@ var USER_AGENT_INSTRUCTION_TARGETS = [
     path: "~/.copilot/instructions/threadnote.instructions.md"
   }
 ];
+var CLAUDE_SETTINGS_PATH = "~/.claude/settings.json";
+var THREADNOTE_HOOK_MARKER = "_threadnote";
+var THREADNOTE_HOOK_MARKER_VALUE = "managed";
+var HOOK_PRE_COMPACT_COMMAND = "threadnote pre-compact-hook";
+var HOOK_SESSION_START_COMMAND = "threadnote session-start-hook";
+var HOOK_AUTO_PRECOMPACT_TOPIC = "auto-precompact";
 var DEFAULT_SEED_PATTERNS = [
   "AGENTS.md",
   "CLAUDE.md",
@@ -3515,6 +3521,16 @@ var DEFAULT_SEED_PATTERNS = [
   "docs/**/*.md"
 ];
 
+// src/hooks.ts
+var import_promises5 = require("node:fs/promises");
+var import_node_path5 = require("node:path");
+
+// src/mcp.ts
+var import_node_fs2 = require("node:fs");
+var import_promises2 = require("node:fs/promises");
+var import_node_path2 = require("node:path");
+var import_node_os2 = require("node:os");
+
 // src/utils.ts
 var import_node_child_process = require("node:child_process");
 var import_node_crypto = require("node:crypto");
@@ -3986,10 +4002,6 @@ function errorMessage(err) {
 }
 
 // src/mcp.ts
-var import_node_fs2 = require("node:fs");
-var import_promises2 = require("node:fs/promises");
-var import_node_path2 = require("node:path");
-var import_node_os2 = require("node:os");
 async function runMcpInstall(config, agent, options) {
   const name = options.name ?? OPENVIKING_MCP_NAME;
   const url = options.url ?? `http://${config.host}:${config.port}/mcp`;
@@ -4470,50 +4482,6 @@ function existsSyncDirectory(path) {
   }
 }
 
-// src/runtime.ts
-var import_node_fs3 = require("node:fs");
-var import_node_os3 = require("node:os");
-var import_node_path3 = require("node:path");
-function getRuntimeConfig(program2, manifestOverride) {
-  const options = program2.opts();
-  const threadnoteHome = expandPath(options.home ?? process.env.THREADNOTE_HOME ?? "~/.openviking");
-  const manifestPath = expandPath(
-    manifestOverride ?? options.manifest ?? process.env.THREADNOTE_MANIFEST ?? defaultManifestPath(threadnoteHome)
-  );
-  return {
-    account: process.env.THREADNOTE_ACCOUNT ?? DEFAULT_ACCOUNT,
-    agentContextHome: threadnoteHome,
-    agentId: process.env.THREADNOTE_AGENT_ID ?? DEFAULT_AGENT_ID,
-    host: options.host ?? process.env.THREADNOTE_HOST ?? DEFAULT_HOST,
-    manifestPath,
-    openVikingVersion: process.env.THREADNOTE_OPENVIKING_VERSION ?? DEFAULT_OPENVIKING_VERSION,
-    port: options.port ?? parsePort(process.env.THREADNOTE_PORT ?? String(DEFAULT_PORT)),
-    user: process.env.THREADNOTE_USER ?? (0, import_node_os3.userInfo)().username
-  };
-}
-function defaultManifestPath(agentContextHome) {
-  const userManifest = (0, import_node_path3.join)(agentContextHome, USER_MANIFEST_NAME);
-  return (0, import_node_fs3.existsSync)(userManifest) ? userManifest : builtInExampleManifestPath();
-}
-function builtInExampleManifestPath() {
-  return (0, import_node_path3.join)(toolRoot(), "config", "seed-manifest.example.yaml");
-}
-function openVikingHealthUrl(config) {
-  return `http://${config.host}:${config.port}/health`;
-}
-function openVikingLogPath(config) {
-  return (0, import_node_path3.join)(config.agentContextHome, "logs", "server.log");
-}
-function openVikingServerArgs(config) {
-  return ["--config", (0, import_node_path3.join)(config.agentContextHome, "ov.conf"), "--host", config.host, "--port", String(config.port)];
-}
-function withIdentity(config, args) {
-  return [...args, "--account", config.account, "--user", config.user, "--agent-id", config.agentId];
-}
-function renderTemplate(template, config) {
-  return template.replaceAll("{{THREADNOTE_HOME}}", config.agentContextHome).replaceAll("{{OPENVIKING_ACCOUNT}}", config.account).replaceAll("{{OPENVIKING_AGENT_ID}}", config.agentId).replaceAll("{{OPENVIKING_HOST}}", config.host).replaceAll("{{OPENVIKING_PORT}}", String(config.port)).replaceAll("{{OPENVIKING_USER}}", config.user);
-}
-
 // src/memory.ts
 var import_promises4 = require("node:fs/promises");
 var import_node_path4 = require("node:path");
@@ -7205,6 +7173,50 @@ function readStringArray(object, key) {
   return value;
 }
 
+// src/runtime.ts
+var import_node_fs3 = require("node:fs");
+var import_node_os3 = require("node:os");
+var import_node_path3 = require("node:path");
+function getRuntimeConfig(program2, manifestOverride) {
+  const options = program2.opts();
+  const threadnoteHome = expandPath(options.home ?? process.env.THREADNOTE_HOME ?? "~/.openviking");
+  const manifestPath = expandPath(
+    manifestOverride ?? options.manifest ?? process.env.THREADNOTE_MANIFEST ?? defaultManifestPath(threadnoteHome)
+  );
+  return {
+    account: process.env.THREADNOTE_ACCOUNT ?? DEFAULT_ACCOUNT,
+    agentContextHome: threadnoteHome,
+    agentId: process.env.THREADNOTE_AGENT_ID ?? DEFAULT_AGENT_ID,
+    host: options.host ?? process.env.THREADNOTE_HOST ?? DEFAULT_HOST,
+    manifestPath,
+    openVikingVersion: process.env.THREADNOTE_OPENVIKING_VERSION ?? DEFAULT_OPENVIKING_VERSION,
+    port: options.port ?? parsePort(process.env.THREADNOTE_PORT ?? String(DEFAULT_PORT)),
+    user: process.env.THREADNOTE_USER ?? (0, import_node_os3.userInfo)().username
+  };
+}
+function defaultManifestPath(agentContextHome) {
+  const userManifest = (0, import_node_path3.join)(agentContextHome, USER_MANIFEST_NAME);
+  return (0, import_node_fs3.existsSync)(userManifest) ? userManifest : builtInExampleManifestPath();
+}
+function builtInExampleManifestPath() {
+  return (0, import_node_path3.join)(toolRoot(), "config", "seed-manifest.example.yaml");
+}
+function openVikingHealthUrl(config) {
+  return `http://${config.host}:${config.port}/health`;
+}
+function openVikingLogPath(config) {
+  return (0, import_node_path3.join)(config.agentContextHome, "logs", "server.log");
+}
+function openVikingServerArgs(config) {
+  return ["--config", (0, import_node_path3.join)(config.agentContextHome, "ov.conf"), "--host", config.host, "--port", String(config.port)];
+}
+function withIdentity(config, args) {
+  return [...args, "--account", config.account, "--user", config.user, "--agent-id", config.agentId];
+}
+function renderTemplate(template, config) {
+  return template.replaceAll("{{THREADNOTE_HOME}}", config.agentContextHome).replaceAll("{{OPENVIKING_ACCOUNT}}", config.account).replaceAll("{{OPENVIKING_AGENT_ID}}", config.agentId).replaceAll("{{OPENVIKING_HOST}}", config.host).replaceAll("{{OPENVIKING_PORT}}", String(config.port)).replaceAll("{{OPENVIKING_USER}}", config.user);
+}
+
 // src/memory.ts
 function parseMemoryKind(value) {
   if (["durable", "handoff", "incident", "preference", "smoke"].includes(value)) {
@@ -8083,9 +8095,201 @@ function formatBlock(value, emptyValue) {
   return trimmed.split("\n").map((line) => `- ${line}`).join("\n");
 }
 
+// src/hooks.ts
+var MANAGED_HOOKS = [
+  {
+    event: "PreCompact",
+    command: HOOK_PRE_COMPACT_COMMAND,
+    description: "Auto-store a handoff snapshot before context compaction so the next turn can recall it."
+  },
+  {
+    event: "SessionStart",
+    command: HOOK_SESSION_START_COMMAND,
+    description: "Pre-load the latest handoff for the current repo into the new session context."
+  }
+];
+async function runHooksInstall(config, agent, options) {
+  const apply = options.apply === true && options.dryRun !== true;
+  const remove = options.remove === true;
+  switch (agent) {
+    case "claude":
+      await runClaudeHooksInstall({ apply, remove });
+      return;
+    case "codex":
+      printCodexHooksNotice(remove);
+      return;
+    case "cursor":
+      printNoHooksSupported("cursor", remove);
+      return;
+    case "copilot":
+      printNoHooksSupported("copilot", remove);
+      return;
+  }
+}
+async function runClaudeHooksInstall(options) {
+  const path = expandPath(CLAUDE_SETTINGS_PATH);
+  const existingRaw = await exists(path) ? await (0, import_promises5.readFile)(path, "utf8") : "{}";
+  const parsed = parseJsonConfigObject(existingRaw) ?? {};
+  const next = options.remove ? withoutThreadnoteHooks(parsed) : withThreadnoteHooks(parsed);
+  const before = JSON.stringify(parsed);
+  const after = JSON.stringify(next);
+  if (before === after) {
+    console.log(`Claude hooks already ${options.remove ? "absent" : "managed"} in ${path}.`);
+    return;
+  }
+  console.log(`${options.apply ? "Updating" : "Would update"} ${path}:`);
+  for (const entry of MANAGED_HOOKS) {
+    console.log(`  ${options.remove ? "-" : "+"} ${entry.event}: ${entry.command}`);
+  }
+  if (!options.apply) {
+    console.log("\nRe-run with --apply to actually modify the file.");
+    return;
+  }
+  await (0, import_promises5.mkdir)((0, import_node_path5.dirname)(path), { recursive: true });
+  const serialized = `${JSON.stringify(next, void 0, 2)}
+`;
+  await (0, import_promises5.writeFile)(path, serialized, { encoding: "utf8", mode: 384 });
+  await (0, import_promises5.chmod)(path, 384);
+  console.log(`${options.remove ? "Removed" : "Installed"} threadnote-managed Claude hooks.`);
+}
+function withThreadnoteHooks(input2) {
+  const hooks = ensureMutableObject(input2.hooks);
+  for (const entry of MANAGED_HOOKS) {
+    const list = ensureMutableArray(hooks[entry.event]).filter((item) => !isManagedThreadnoteEntry(item));
+    list.push({
+      [THREADNOTE_HOOK_MARKER]: THREADNOTE_HOOK_MARKER_VALUE,
+      matcher: "",
+      hooks: [{ type: "command", command: entry.command }]
+    });
+    hooks[entry.event] = list;
+  }
+  return { ...input2, hooks };
+}
+function withoutThreadnoteHooks(input2) {
+  if (!isJsonObject(input2.hooks)) {
+    return input2;
+  }
+  const hooks = {};
+  for (const [event, value] of Object.entries(input2.hooks)) {
+    if (!Array.isArray(value)) {
+      hooks[event] = value;
+      continue;
+    }
+    const filtered = value.filter((item) => !isManagedThreadnoteEntry(item));
+    if (filtered.length > 0) {
+      hooks[event] = filtered;
+    }
+  }
+  if (Object.keys(hooks).length === 0) {
+    const next = { ...input2 };
+    delete next.hooks;
+    return next;
+  }
+  return { ...input2, hooks };
+}
+function isManagedThreadnoteEntry(value) {
+  return isJsonObject(value) && value[THREADNOTE_HOOK_MARKER] === THREADNOTE_HOOK_MARKER_VALUE;
+}
+function ensureMutableObject(value) {
+  return isJsonObject(value) ? { ...value } : {};
+}
+function ensureMutableArray(value) {
+  return Array.isArray(value) ? [...value] : [];
+}
+function printCodexHooksNotice(remove) {
+  if (remove) {
+    console.log("Codex CLI does not expose a managed hook surface today, so there is nothing to remove.");
+    return;
+  }
+  console.log(
+    [
+      "Codex CLI does not currently expose lifecycle hooks (no PreCompact or SessionStart analog).",
+      "Threadnote already installs Codex user instructions at ~/.codex/AGENTS.md; that remains the active guidance surface.",
+      "If a future Codex release adds hook events, threadnote will pick them up via `install-hooks codex`."
+    ].join("\n")
+  );
+}
+function printNoHooksSupported(agent, remove) {
+  if (remove) {
+    console.log(`${agent} does not expose a hook surface; nothing to remove.`);
+    return;
+  }
+  console.log(
+    [
+      `${agent} does not expose agent-mode hooks today.`,
+      "Threadnote already installs user-level instructions for this agent; that remains the active guidance surface.",
+      "Hooks support will be added if the agent gains a hook surface upstream."
+    ].join("\n")
+  );
+}
+async function hasManagedClaudeHooks() {
+  const path = expandPath(CLAUDE_SETTINGS_PATH);
+  if (!await exists(path)) {
+    return false;
+  }
+  const raw = await (0, import_promises5.readFile)(path, "utf8");
+  const parsed = parseJsonConfigObject(raw);
+  if (!parsed || !isJsonObject(parsed.hooks)) {
+    return false;
+  }
+  for (const value of Object.values(parsed.hooks)) {
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    if (value.some((item) => isManagedThreadnoteEntry(item))) {
+      return true;
+    }
+  }
+  return false;
+}
+async function runPreCompactHook(config, options = {}) {
+  try {
+    const repoRoot = await gitValue(["rev-parse", "--show-toplevel"]);
+    const project = repoRoot ? (0, import_node_path5.basename)(repoRoot) : "general";
+    await runHandoff(config, {
+      blockers: "- none recorded",
+      dryRun: options.dryRun === true,
+      nextStep: "Continue from this auto-snapshot. A manual `threadnote handoff` will produce a richer write-up if you have more context.",
+      project,
+      sourceAgentClient: "claude",
+      task: "Auto-snapshot captured at Claude PreCompact (deterministic safety net before context compaction).",
+      tests: "- not recorded (auto-snapshot)",
+      topic: HOOK_AUTO_PRECOMPACT_TOPIC
+    });
+  } catch (err) {
+    process.stderr.write(
+      `threadnote pre-compact-hook: snapshot skipped (${err instanceof Error ? err.message : String(err)})
+`
+    );
+  }
+}
+async function runSessionStartHook(config, options = {}) {
+  try {
+    const repoRoot = await gitValue(["rev-parse", "--show-toplevel"]);
+    if (!repoRoot) {
+      return;
+    }
+    const project = (0, import_node_path5.basename)(repoRoot);
+    process.stdout.write(`## Threadnote \u2014 latest context for ${project}
+
+`);
+    await runRecall(config, {
+      dryRun: options.dryRun === true,
+      inferScope: true,
+      nodeLimit: "5",
+      query: `${project} latest handoff durable feature memory`
+    });
+  } catch (err) {
+    process.stderr.write(
+      `threadnote session-start-hook: recall skipped (${err instanceof Error ? err.message : String(err)})
+`
+    );
+  }
+}
+
 // src/seeding.ts
-var import_promises5 = require("node:fs/promises");
-var import_node_path5 = require("node:path");
+var import_promises6 = require("node:fs/promises");
+var import_node_path6 = require("node:path");
 async function runSeed(config, options) {
   const manifest = await readSeedManifest(config.manifestPath);
   const ignorePatterns = await loadIgnorePatterns();
@@ -8114,7 +8318,7 @@ async function runSeed(config, options) {
 }
 async function runInitManifest(config, options) {
   const manifestPath = expandPath(
-    options.path ?? process.env.THREADNOTE_MANIFEST ?? (0, import_node_path5.join)(config.agentContextHome, USER_MANIFEST_NAME)
+    options.path ?? process.env.THREADNOTE_MANIFEST ?? (0, import_node_path6.join)(config.agentContextHome, USER_MANIFEST_NAME)
   );
   const repoInputs = options.repo && options.repo.length > 0 ? options.repo : [getInvocationCwd()];
   const existingManifest = options.replace === true || !await exists(manifestPath) ? void 0 : await readSeedManifest(manifestPath);
@@ -8157,9 +8361,9 @@ async function runInitManifest(config, options) {
     console.log(output2.trimEnd());
     return;
   }
-  await ensureDirectory((0, import_node_path5.dirname)(manifestPath), false);
-  await (0, import_promises5.writeFile)(manifestPath, output2, { encoding: "utf8", mode: 384 });
-  await (0, import_promises5.chmod)(manifestPath, 384);
+  await ensureDirectory((0, import_node_path6.dirname)(manifestPath), false);
+  await (0, import_promises6.writeFile)(manifestPath, output2, { encoding: "utf8", mode: 384 });
+  await (0, import_promises6.chmod)(manifestPath, 384);
   console.log(`Wrote manifest: ${manifestPath}`);
   console.log("Seed with:");
   console.log("  threadnote seed --dry-run");
@@ -8189,13 +8393,13 @@ async function resolveRepoRoot(repoInput) {
 async function projectIdentity(path) {
   const expanded = expandPath(path);
   try {
-    return await (0, import_promises5.realpath)(expanded);
+    return await (0, import_promises6.realpath)(expanded);
   } catch (_err) {
     return expanded;
   }
 }
 function projectManifestForRepo(repoRoot, existingProjects) {
-  const baseName = uriSegment((0, import_node_path5.basename)(repoRoot));
+  const baseName = uriSegment((0, import_node_path6.basename)(repoRoot));
   const usedNames = new Set(existingProjects.map((project) => project.name));
   const usedUris = new Set(existingProjects.map((project) => project.uri));
   let name = baseName;
@@ -8217,7 +8421,7 @@ async function collectSeedCandidates(project, projectRoot, ignorePatterns) {
   for (const pattern of project.seed) {
     const files = await resolveProjectPattern(projectRoot, pattern);
     for (const filePath of files) {
-      const relativePath = toPosixPath((0, import_node_path5.relative)(projectRoot, filePath));
+      const relativePath = toPosixPath((0, import_node_path6.relative)(projectRoot, filePath));
       if (seen.has(relativePath) || matchesIgnore(relativePath, ignorePatterns)) {
         continue;
       }
@@ -8235,20 +8439,20 @@ async function collectSeedCandidates(project, projectRoot, ignorePatterns) {
 async function resolveProjectPattern(projectRoot, pattern) {
   const normalizedPattern = toPosixPath(pattern);
   if (!hasGlob(normalizedPattern)) {
-    const filePath = (0, import_node_path5.join)(projectRoot, normalizedPattern);
+    const filePath = (0, import_node_path6.join)(projectRoot, normalizedPattern);
     return await isFile(filePath) ? [filePath] : [];
   }
   const globBase = getGlobBase(normalizedPattern);
-  const basePath = (0, import_node_path5.join)(projectRoot, globBase);
+  const basePath = (0, import_node_path6.join)(projectRoot, globBase);
   if (!await exists(basePath)) {
     return [];
   }
   const regex = globToRegExp(normalizedPattern);
   const files = await walkFiles(basePath);
-  return files.filter((filePath) => regex.test(toPosixPath((0, import_node_path5.relative)(projectRoot, filePath))));
+  return files.filter((filePath) => regex.test(toPosixPath((0, import_node_path6.relative)(projectRoot, filePath))));
 }
 async function prepareSeedFile(config, candidate, dryRun) {
-  const content = await (0, import_promises5.readFile)(candidate.filePath, "utf8");
+  const content = await (0, import_promises6.readFile)(candidate.filePath, "utf8");
   const redactedContent = shouldRedactPath(candidate.relativePath) ? redactContent(candidate.relativePath, content) : content;
   const secretMatches = detectSecretMatches(redactedContent);
   if (secretMatches.length > 0) {
@@ -8260,14 +8464,14 @@ async function prepareSeedFile(config, candidate, dryRun) {
   if (redactedContent === content) {
     return candidate.filePath;
   }
-  const redactedPath = (0, import_node_path5.join)(config.agentContextHome, "redacted", candidate.projectName, candidate.relativePath);
+  const redactedPath = (0, import_node_path6.join)(config.agentContextHome, "redacted", candidate.projectName, candidate.relativePath);
   if (dryRun) {
     console.log(`Would write redacted copy: ${redactedPath}`);
     return redactedPath;
   }
-  await ensureDirectory((0, import_node_path5.dirname)(redactedPath), false);
-  await (0, import_promises5.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
-  await (0, import_promises5.chmod)(redactedPath, 384);
+  await ensureDirectory((0, import_node_path6.dirname)(redactedPath), false);
+  await (0, import_promises6.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
+  await (0, import_promises6.chmod)(redactedPath, 384);
   return redactedPath;
 }
 async function collectSkillCandidates(config) {
@@ -8292,7 +8496,7 @@ async function collectSkillCandidates(config) {
   for (const source of sources) {
     const files = await resolveAbsolutePattern(expandPath(source.pattern));
     for (const filePath of files) {
-      const content = await (0, import_promises5.readFile)(filePath, "utf8");
+      const content = await (0, import_promises6.readFile)(filePath, "utf8");
       const matches = detectSecretMatches(content);
       if (matches.length > 0) {
         console.log(`SKIP skill with possible secret: ${filePath}`);
@@ -8323,10 +8527,10 @@ async function resolveAbsolutePattern(pattern) {
   return files.filter((filePath) => regex.test(toPosixPath(filePath)));
 }
 function skillResourceUri(skill) {
-  return `viking://resources/agent-skills/${uriSegment(skill.source)}/${uriSegment((0, import_node_path5.basename)((0, import_node_path5.dirname)(skill.filePath)))}-${skill.hash.slice(0, 12)}.md`;
+  return `viking://resources/agent-skills/${uriSegment(skill.source)}/${uriSegment((0, import_node_path6.basename)((0, import_node_path6.dirname)(skill.filePath)))}-${skill.hash.slice(0, 12)}.md`;
 }
 async function loadIgnorePatterns() {
-  const raw = await (0, import_promises5.readFile)((0, import_node_path5.join)(toolRoot(), ".threadnoteignore"), "utf8");
+  const raw = await (0, import_promises6.readFile)((0, import_node_path6.join)(toolRoot(), ".threadnoteignore"), "utf8");
   return raw.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
 }
 function matchesIgnore(relativePath, patterns) {
@@ -8397,9 +8601,9 @@ function detectSecretMatches(content) {
 }
 
 // src/share.ts
-var import_promises6 = require("node:fs/promises");
+var import_promises7 = require("node:fs/promises");
 var import_node_os4 = require("node:os");
-var import_node_path6 = require("node:path");
+var import_node_path7 = require("node:path");
 var TEAMS_FILE_VERSION = 1;
 var SHARED_SEGMENT = "shared";
 var SHAREABLE_MEMORY_KIND_DIRS = ["durable"];
@@ -8437,8 +8641,8 @@ async function runShareInit(config, remoteUrl, options) {
   if (await exists(gitdir)) {
     throw new Error(`Gitdir already exists at ${gitdir}; remove it or pick a different team name.`);
   }
-  await ensureDirectory((0, import_node_path6.dirname)(worktree), dryRun);
-  await ensureDirectory((0, import_node_path6.dirname)(gitdir), dryRun);
+  await ensureDirectory((0, import_node_path7.dirname)(worktree), dryRun);
+  await ensureDirectory((0, import_node_path7.dirname)(gitdir), dryRun);
   const git = await requiredExecutable("git");
   await maybeRun(dryRun, git, ["clone", `--separate-git-dir=${gitdir}`, "--", remoteUrl, worktree]);
   const newConfig = {
@@ -8469,7 +8673,7 @@ async function runShareInit(config, remoteUrl, options) {
 var SHARED_GITIGNORE_PATTERNS = ["**/.abstract.md", "**/.overview.md"];
 var SHARED_GITIGNORE_HEADER = "# Threadnote: ignore OpenViking-generated directory summaries.";
 async function ensureSharedGitignore(worktree, git, push) {
-  const gitignorePath = (0, import_node_path6.join)(worktree, ".gitignore");
+  const gitignorePath = (0, import_node_path7.join)(worktree, ".gitignore");
   const existing = await readFileIfExists(gitignorePath) ?? "";
   const lines = existing.split("\n").map((line) => line.trim());
   const missingPatterns = SHARED_GITIGNORE_PATTERNS.filter((pattern) => !lines.includes(pattern));
@@ -8488,7 +8692,7 @@ async function ensureSharedGitignore(worktree, git, push) {
     segments.push(SHARED_GITIGNORE_HEADER, "\n");
   }
   segments.push(missingPatterns.join("\n"), "\n");
-  await (0, import_promises6.writeFile)(gitignorePath, `${existing}${segments.join("")}`, { encoding: "utf8" });
+  await (0, import_promises7.writeFile)(gitignorePath, `${existing}${segments.join("")}`, { encoding: "utf8" });
   console.log(`Added ${missingPatterns.join(", ")} to ${portablePath(gitignorePath)}`);
   await maybeRun(false, git, ["-C", worktree, "add", ".gitignore"]);
   const commitResult = await runCommand(
@@ -8553,7 +8757,7 @@ async function runShareSync(config, options) {
   if (dryRun) {
     console.log(`Would run: ${formatShellCommand(git, ["-C", worktree, "pull", "--rebase", DEFAULT_GIT_REMOTE_NAME])}`);
   } else if (pullResult && pullResult.exitCode !== 0) {
-    if (await exists((0, import_node_path6.join)(team.config.gitdir, "rebase-merge")) || await exists((0, import_node_path6.join)(team.config.gitdir, "rebase-apply"))) {
+    if (await exists((0, import_node_path7.join)(team.config.gitdir, "rebase-merge")) || await exists((0, import_node_path7.join)(team.config.gitdir, "rebase-apply"))) {
       throw new Error(
         `git pull --rebase reported conflicts in ${worktree}. The worktree is in a rebase-in-progress state.
 Resolve the conflicts in-place, run \`git -C ${worktree} rebase --continue\` (or --abort), then re-run \`threadnote share sync\`.`
@@ -8704,10 +8908,10 @@ function normalizeTeamName(input2) {
   return candidate;
 }
 function teamsFilePath(config) {
-  return (0, import_node_path6.join)(config.agentContextHome, "share", "teams.json");
+  return (0, import_node_path7.join)(config.agentContextHome, "share", "teams.json");
 }
 function teamWorktreePath(config, team) {
-  return (0, import_node_path6.join)(
+  return (0, import_node_path7.join)(
     config.agentContextHome,
     "data",
     "viking",
@@ -8720,7 +8924,7 @@ function teamWorktreePath(config, team) {
   );
 }
 function teamGitdirPath(config, team) {
-  return (0, import_node_path6.join)(config.agentContextHome, "share", "teams", `${team}.gitdir`);
+  return (0, import_node_path7.join)(config.agentContextHome, "share", "teams", `${team}.gitdir`);
 }
 async function readTeamsFile(config) {
   const path = teamsFilePath(config);
@@ -8763,13 +8967,13 @@ async function readTeamsFile(config) {
 }
 async function writeTeamsFile(config, contents) {
   const path = teamsFilePath(config);
-  await (0, import_promises6.mkdir)((0, import_node_path6.dirname)(path), { recursive: true });
+  await (0, import_promises7.mkdir)((0, import_node_path7.dirname)(path), { recursive: true });
   const serializable = {
     defaultTeam: contents.defaultTeam,
     teams: contents.teams,
     version: contents.version
   };
-  await (0, import_promises6.writeFile)(path, `${JSON.stringify(serializable, void 0, 2)}
+  await (0, import_promises7.writeFile)(path, `${JSON.stringify(serializable, void 0, 2)}
 `, { encoding: "utf8", mode: 384 });
 }
 async function resolveTeam(config, requested) {
@@ -8799,7 +9003,7 @@ async function assertWorktreeUsable(worktree) {
   if (!await isDirectory(worktree)) {
     throw new Error(`Cannot use ${worktree} as a worktree: not a directory.`);
   }
-  const entries = await (0, import_promises6.readdir)(worktree);
+  const entries = await (0, import_promises7.readdir)(worktree);
   if (entries.length > 0) {
     const preview = entries.slice(0, 5).join(", ");
     const suffix = entries.length > 5 ? `, +${entries.length - 5} more` : "";
@@ -8823,7 +9027,7 @@ async function walkMemoryFiles(root) {
   async function visit(path, depth) {
     let entries;
     try {
-      entries = await (0, import_promises6.readdir)(path, { withFileTypes: true });
+      entries = await (0, import_promises7.readdir)(path, { withFileTypes: true });
     } catch (err) {
       console.warn(`Skipping ${path} during shared-tree walk: ${err instanceof Error ? err.message : String(err)}`);
       return;
@@ -8832,7 +9036,7 @@ async function walkMemoryFiles(root) {
       if (entry.name === ".git") {
         continue;
       }
-      const full = (0, import_node_path6.join)(path, entry.name);
+      const full = (0, import_node_path7.join)(path, entry.name);
       if (entry.isDirectory()) {
         if (depth === 0 && !SHAREABLE_MEMORY_KIND_DIRS.includes(entry.name)) {
           continue;
@@ -8856,7 +9060,7 @@ async function walkMemoryFiles(root) {
   return out;
 }
 function workfileToVikingUri(config, team, filePath) {
-  const rel = (0, import_node_path6.relative)(team.worktree, filePath).split(import_node_path6.sep).join("/");
+  const rel = (0, import_node_path7.relative)(team.worktree, filePath).split(import_node_path7.sep).join("/");
   return `viking://user/${uriSegment(config.user)}/memories/${SHARED_SEGMENT}/${team.name}/${rel}`;
 }
 function isInSharedNamespace(config, uri) {
@@ -8950,13 +9154,13 @@ async function writeMemoryFile(config, ov, uri, content, initialMode, dryRun) {
     console.log(`Would run: ${formatShellCommand(ov, args)}`);
     return;
   }
-  const stagingDir = await (0, import_promises6.mkdtemp)((0, import_node_path6.join)((0, import_node_os4.tmpdir)(), "threadnote-share-"));
-  const tempPath = (0, import_node_path6.join)(stagingDir, "body.txt");
+  const stagingDir = await (0, import_promises7.mkdtemp)((0, import_node_path7.join)((0, import_node_os4.tmpdir)(), "threadnote-share-"));
+  const tempPath = (0, import_node_path7.join)(stagingDir, "body.txt");
   try {
-    await (0, import_promises6.writeFile)(tempPath, content, { encoding: "utf8", mode: 384 });
+    await (0, import_promises7.writeFile)(tempPath, content, { encoding: "utf8", mode: 384 });
     await writeOvFileWithRetry(config, ov, uri, tempPath, initialMode);
   } finally {
-    await (0, import_promises6.rm)(stagingDir, { force: true, recursive: true });
+    await (0, import_promises7.rm)(stagingDir, { force: true, recursive: true });
   }
 }
 async function writeOvFileWithRetry(config, ov, uri, fromFile, initialMode) {
@@ -9014,7 +9218,7 @@ ${stdout}`.toLowerCase();
   return output2.includes("resource is busy") || output2.includes("resource is being processed") || output2.includes("network error") || output2.includes("error sending request") || output2.includes("http request failed") || output2.includes("connection refused") || output2.includes("connection reset") || output2.includes("timed out");
 }
 async function ingestSingleFile(ov, config, uri, filePath, initialMode) {
-  const content = await (0, import_promises6.readFile)(filePath, "utf8");
+  const content = await (0, import_promises7.readFile)(filePath, "utf8");
   await writeMemoryFile(config, ov, uri, content, initialMode, false);
 }
 async function removeWithRollback(config, ov, sourceUri, rollbackUri, worktree, dryRun, label) {
@@ -9056,7 +9260,7 @@ async function bestEffortRemoveWorktreeFile(rollbackUri, worktree, label) {
   if (!relative3) {
     return;
   }
-  await (0, import_promises6.rm)((0, import_node_path6.join)(worktree, relative3), { force: true });
+  await (0, import_promises7.rm)((0, import_node_path7.join)(worktree, relative3), { force: true });
 }
 async function removeMemoryUri(config, ov, uri, dryRun) {
   const args = withIdentity(config, ["rm", uri]);
@@ -9113,8 +9317,8 @@ async function listChangedFiles(worktree, beforeRev, afterRev) {
       const oldRel = entries[index + 1];
       const newRel = entries[index + 2];
       if (oldRel && newRel) {
-        changes.push({ path: (0, import_node_path6.join)(worktree, oldRel), relativePath: oldRel, status: "removed" });
-        changes.push({ path: (0, import_node_path6.join)(worktree, newRel), relativePath: newRel, status: "added" });
+        changes.push({ path: (0, import_node_path7.join)(worktree, oldRel), relativePath: oldRel, status: "removed" });
+        changes.push({ path: (0, import_node_path7.join)(worktree, newRel), relativePath: newRel, status: "added" });
       }
       index += 3;
       continue;
@@ -9122,7 +9326,7 @@ async function listChangedFiles(worktree, beforeRev, afterRev) {
     const rel = entries[index + 1];
     if (rel) {
       const status = head === "A" ? "added" : head === "D" ? "removed" : "modified";
-      changes.push({ path: (0, import_node_path6.join)(worktree, rel), relativePath: rel, status });
+      changes.push({ path: (0, import_node_path7.join)(worktree, rel), relativePath: rel, status });
     }
     index += 2;
   }
@@ -9160,16 +9364,18 @@ async function applyChangesToOpenViking(config, team, changes) {
 // src/lifecycle.ts
 var import_node_child_process2 = require("node:child_process");
 var import_node_fs5 = require("node:fs");
-var import_promises9 = require("node:fs/promises");
+var import_promises10 = require("node:fs/promises");
 var import_node_os6 = require("node:os");
-var import_node_path8 = require("node:path");
+var import_node_path9 = require("node:path");
+var import_node_process2 = require("node:process");
+var import_promises11 = require("node:readline/promises");
 
 // src/update.ts
 var import_node_fs4 = require("node:fs");
-var import_promises7 = require("node:fs/promises");
+var import_promises8 = require("node:fs/promises");
 var import_node_os5 = require("node:os");
-var import_node_path7 = require("node:path");
-var import_promises8 = require("node:readline/promises");
+var import_node_path8 = require("node:path");
+var import_promises9 = require("node:readline/promises");
 var import_node_process = require("node:process");
 var NPM_PACKAGE_NAME = "threadnote";
 var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
@@ -9317,7 +9523,7 @@ async function getUpdateInfo(config, options) {
   };
 }
 async function currentPackageVersion() {
-  const rawPackage = await (0, import_promises7.readFile)((0, import_node_path7.join)(toolRoot(), "package.json"), "utf8");
+  const rawPackage = await (0, import_promises8.readFile)((0, import_node_path8.join)(toolRoot(), "package.json"), "utf8");
   const parsed = JSON.parse(rawPackage);
   if (!isJsonObject(parsed) || typeof parsed.version !== "string") {
     throw new Error("Could not read current threadnote package version.");
@@ -9367,11 +9573,11 @@ async function readFreshCache(config, registry) {
 }
 async function writeUpdateCache(config, cache) {
   await ensureDirectory(config.agentContextHome, false);
-  await (0, import_promises7.writeFile)(updateCachePath(config), `${JSON.stringify(cache, null, 2)}
+  await (0, import_promises8.writeFile)(updateCachePath(config), `${JSON.stringify(cache, null, 2)}
 `, { encoding: "utf8", mode: 384 });
 }
 function updateCachePath(config) {
-  return (0, import_node_path7.join)(config.agentContextHome, "update-check.json");
+  return (0, import_node_path8.join)(config.agentContextHome, "update-check.json");
 }
 async function runApplicablePostUpdateMigrations(config, options) {
   const state = await readPostUpdateState(config);
@@ -9435,7 +9641,7 @@ async function applicablePostUpdateMigrations(config, options) {
   return applicable;
 }
 async function readPostUpdateMigrations() {
-  const raw = await readFileIfExists((0, import_node_path7.join)(toolRoot(), "config", POST_UPDATE_MIGRATIONS_FILE));
+  const raw = await readFileIfExists((0, import_node_path8.join)(toolRoot(), "config", POST_UPDATE_MIGRATIONS_FILE));
   if (!raw) {
     return [];
   }
@@ -9474,7 +9680,7 @@ function printPostUpdateMigration(migration) {
   }
 }
 async function confirmPostUpdateMigration(prompt) {
-  const readline = (0, import_promises8.createInterface)({ input: import_node_process.stdin, output: import_node_process.stdout });
+  const readline = (0, import_promises9.createInterface)({ input: import_node_process.stdin, output: import_node_process.stdout });
   try {
     const answer = (await readline.question(prompt)).trim().toLowerCase();
     return answer === "y" || answer === "yes";
@@ -9506,11 +9712,11 @@ async function readPostUpdateState(config) {
 }
 async function writePostUpdateState(config, state) {
   await ensureDirectory(config.agentContextHome, false);
-  await (0, import_promises7.writeFile)(postUpdateStatePath(config), `${JSON.stringify(state, null, 2)}
+  await (0, import_promises8.writeFile)(postUpdateStatePath(config), `${JSON.stringify(state, null, 2)}
 `, { encoding: "utf8", mode: 384 });
 }
 function postUpdateStatePath(config) {
-  return (0, import_node_path7.join)(config.agentContextHome, POST_UPDATE_STATE_FILE);
+  return (0, import_node_path8.join)(config.agentContextHome, POST_UPDATE_STATE_FILE);
 }
 async function resolveUpdateRuntime(runtime) {
   if (runtime !== "auto") {
@@ -9540,18 +9746,18 @@ async function runtimeThreadnoteBin(runtime) {
   if (runtime === "npm") {
     const result = await runCommand("npm", ["prefix", "--global"], { allowFailure: true });
     const prefix = result.stdout.trim();
-    return prefix ? (0, import_node_path7.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
+    return prefix ? (0, import_node_path8.join)(prefix, "bin", NPM_PACKAGE_NAME) : void 0;
   }
   if (runtime === "bun") {
     const result = await runCommand("bun", ["pm", "bin", "-g"], { allowFailure: true });
     const binDir = result.stdout.trim();
-    return binDir ? (0, import_node_path7.join)(binDir, NPM_PACKAGE_NAME) : void 0;
+    return binDir ? (0, import_node_path8.join)(binDir, NPM_PACKAGE_NAME) : void 0;
   }
-  return (0, import_node_path7.join)(process.env.DENO_INSTALL ?? (0, import_node_path7.join)((0, import_node_os5.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
+  return (0, import_node_path8.join)(process.env.DENO_INSTALL ?? (0, import_node_path8.join)((0, import_node_os5.homedir)(), ".deno"), "bin", NPM_PACKAGE_NAME);
 }
 async function isExecutable(path) {
   try {
-    await (0, import_promises7.access)(path, import_node_fs4.constants.X_OK);
+    await (0, import_promises8.access)(path, import_node_fs4.constants.X_OK);
     return true;
   } catch (_err) {
     return false;
@@ -9642,9 +9848,9 @@ async function runDoctor(config, options) {
   checks.push(await commandShimCheck());
   checks.push(...await userAgentInstructionsChecks());
   checks.push(await manifestCheck(config.manifestPath));
-  checks.push(await fileCheck((0, import_node_path8.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
-  checks.push(await fileCheck((0, import_node_path8.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
-  checks.push(await fileCheck((0, import_node_path8.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
+  checks.push(await fileCheck((0, import_node_path9.join)(toolRoot(), ".threadnoteignore"), "ignore file"));
+  checks.push(await fileCheck((0, import_node_path9.join)(toolRoot(), "config", "ov.conf.template.json"), "server config template"));
+  checks.push(await fileCheck((0, import_node_path9.join)(toolRoot(), "config", "ovcli.conf.template.json"), "cli config template"));
   checks.push(await healthCheck(config));
   for (const check of checks) {
     console.log(`${formatStatus(check.status)} ${check.name}: ${check.detail}`);
@@ -9661,9 +9867,9 @@ async function runInstall(config, options) {
   const repairInvalidConfigs = options.repairInvalidConfigs === true;
   const dryRun = options.dryRun === true;
   await ensureDirectory(config.agentContextHome, dryRun);
-  await ensureDirectory((0, import_node_path8.join)(config.agentContextHome, "logs"), dryRun);
-  await ensureDirectory((0, import_node_path8.join)(config.agentContextHome, "redacted"), dryRun);
-  await ensureDirectory((0, import_node_path8.join)(config.agentContextHome, "mcp"), dryRun);
+  await ensureDirectory((0, import_node_path9.join)(config.agentContextHome, "logs"), dryRun);
+  await ensureDirectory((0, import_node_path9.join)(config.agentContextHome, "redacted"), dryRun);
+  await ensureDirectory((0, import_node_path9.join)(config.agentContextHome, "mcp"), dryRun);
   await installCommandShim(dryRun);
   await installUserAgentInstructions(dryRun);
   const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
@@ -9689,17 +9895,17 @@ async function runInstall(config, options) {
   }
   await writeTemplateIfMissing({
     config,
-    destinationPath: (0, import_node_path8.join)(config.agentContextHome, "ov.conf"),
+    destinationPath: (0, import_node_path9.join)(config.agentContextHome, "ov.conf"),
     dryRun,
     shouldRepair: (content) => shouldRepairOpenVikingConfig(content, config) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
-    templatePath: (0, import_node_path8.join)(toolRoot(), "config", "ov.conf.template.json")
+    templatePath: (0, import_node_path9.join)(toolRoot(), "config", "ov.conf.template.json")
   });
   await writeTemplateIfMissing({
     config,
-    destinationPath: (0, import_node_path8.join)(config.agentContextHome, "ovcli.conf"),
+    destinationPath: (0, import_node_path9.join)(config.agentContextHome, "ovcli.conf"),
     dryRun,
     shouldRepair: (content) => shouldRepairLegacyOvCliConfig(content) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
-    templatePath: (0, import_node_path8.join)(toolRoot(), "config", "ovcli.conf.template.json")
+    templatePath: (0, import_node_path9.join)(toolRoot(), "config", "ovcli.conf.template.json")
   });
   if (options.start !== false) {
     const healthy = await repairServerHealth(config, dryRun);
@@ -9736,6 +9942,10 @@ async function runRepair(config, options) {
       await runMcpInstall(config, client, { apply: !dryRun, name: OPENVIKING_MCP_NAME });
     }
   }
+  if (await hasManagedClaudeHooks()) {
+    console.log("\nRepairing claude hooks (re-asserting threadnote-managed entries).");
+    await runHooksInstall(config, "claude", { apply: !dryRun, dryRun });
+  }
   console.log("\nPost-repair doctor:");
   await runDoctor(config, { dryRun, strict: false });
   if (options.postUpdate !== false) {
@@ -9749,10 +9959,13 @@ async function runUninstall(config, options) {
   }
   console.log("Uninstalling local Threadnote setup.");
   await runStop(config, { dryRun });
-  await removePathIfExists((0, import_node_path8.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
+  await removePathIfExists((0, import_node_path9.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
   await removeLaunchAgent(dryRun);
   await removeMcpConfigs(options.mcp ?? "available", dryRun);
   await removeMcpSnippets(config, dryRun);
+  if (await hasManagedClaudeHooks()) {
+    await runHooksInstall(config, "claude", { apply: !dryRun, dryRun, remove: true });
+  }
   await removeCommandShim(dryRun);
   await removeUserAgentInstructions(dryRun);
   if (options.eraseMemories === true) {
@@ -9803,16 +10016,16 @@ async function repairManifest(config, dryRun) {
     console.log(output2.trimEnd());
     return;
   }
-  await ensureDirectory((0, import_node_path8.dirname)(config.manifestPath), false);
+  await ensureDirectory((0, import_node_path9.dirname)(config.manifestPath), false);
   const currentContent = await readFileIfExists(config.manifestPath);
   if (currentContent !== void 0) {
     const backupPath = `${config.manifestPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises9.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
-    await (0, import_promises9.chmod)(backupPath, 384);
+    await (0, import_promises10.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.chmod)(backupPath, 384);
     console.log(`Backup: ${backupPath}`);
   }
-  await (0, import_promises9.writeFile)(config.manifestPath, output2, { encoding: "utf8", mode: 384 });
-  await (0, import_promises9.chmod)(config.manifestPath, 384);
+  await (0, import_promises10.writeFile)(config.manifestPath, output2, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.chmod)(config.manifestPath, 384);
   console.log(`Wrote replacement manifest: ${config.manifestPath}`);
 }
 async function repairServerHealth(config, dryRun) {
@@ -9853,7 +10066,7 @@ async function runStart(config, options) {
     );
   }
   const logPath = openVikingLogPath(config);
-  await ensureDirectory((0, import_node_path8.dirname)(logPath), false);
+  await ensureDirectory((0, import_node_path9.dirname)(logPath), false);
   if (options.foreground === true) {
     const result = await runInteractive(server, args);
     process.exitCode = result;
@@ -9862,7 +10075,7 @@ async function runStart(config, options) {
   const logFd = (0, import_node_fs5.openSync)(logPath, "a");
   const child = spawnDetachedServerWithLog(server, args, logFd);
   child.unref();
-  await (0, import_promises9.writeFile)((0, import_node_path8.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
+  await (0, import_promises10.writeFile)((0, import_node_path9.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
 `, "utf8");
   const health = await waitForOpenVikingHealth(config, START_HEALTH_TIMEOUT_MS);
   if (health) {
@@ -9895,7 +10108,7 @@ async function runStop(config, options) {
       console.log(`No LaunchAgent found: ${launchAgentPath}`);
     }
   }
-  const pidPath = (0, import_node_path8.join)(config.agentContextHome, "openviking-server.pid");
+  const pidPath = (0, import_node_path9.join)(config.agentContextHome, "openviking-server.pid");
   const pidText = await readFileIfExists(pidPath);
   if (!pidText) {
     console.log("No pid file found for detached OpenViking server.");
@@ -9991,7 +10204,7 @@ async function pythonSystemCertificatesCheck() {
   };
 }
 async function commandShimCheck() {
-  const shimPath = (0, import_node_path8.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const shimPath = (0, import_node_path9.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
   if (content === void 0) {
     return { name: "threadnote shim", status: "warn", detail: `${shimPath} missing; repair will create it` };
@@ -10057,11 +10270,11 @@ async function hasPythonModule(serverPath, moduleName) {
 async function siblingPythonForExecutable(executablePath) {
   let resolvedPath;
   try {
-    resolvedPath = await (0, import_promises9.realpath)(executablePath);
+    resolvedPath = await (0, import_promises10.realpath)(executablePath);
   } catch (_err) {
     return void 0;
   }
-  const pythonPath = (0, import_node_path8.join)((0, import_node_path8.dirname)(resolvedPath), "python");
+  const pythonPath = (0, import_node_path9.join)((0, import_node_path9.dirname)(resolvedPath), "python");
   return await exists(pythonPath) ? pythonPath : void 0;
 }
 async function manifestCheck(path) {
@@ -10110,11 +10323,83 @@ async function waitForOpenVikingHealth(config, timeoutMs) {
   return void 0;
 }
 async function runInstallCommands(config, preferred, force, dryRun) {
-  const installCommands = await getInstallCommands(config, preferred, force);
+  let manager = preferred;
+  if (manager === void 0 && !dryRun) {
+    const detected = await detectPackageManager();
+    if (detected === "pip" && await offerToInstallUv()) {
+      const rediscovered = await detectPackageManager();
+      if (rediscovered === "uv") {
+        manager = "uv";
+      }
+    }
+  }
+  const installCommands = await getInstallCommands(config, manager, force);
   for (const installCommand of installCommands) {
     await maybeRun(dryRun, installCommand.executable, installCommand.args);
   }
 }
+async function offerToInstallUv() {
+  if (import_node_process2.stdin.isTTY !== true || import_node_process2.stdout.isTTY !== true) {
+    console.warn(
+      "Neither uv nor pipx was found on PATH. Falling back to `python3 -m pip install --user`, which fails on PEP 668 (Homebrew/system) Python.\nRe-run with --package-manager uv after installing uv (brew install uv), or pass --package-manager pipx."
+    );
+    return false;
+  }
+  const readline = (0, import_promises11.createInterface)({ input: import_node_process2.stdin, output: import_node_process2.stdout });
+  let answer;
+  try {
+    answer = (await readline.question(
+      "OpenViking installs into Python; neither uv nor pipx is on PATH so threadnote would fall back to `pip install --user`, which fails on PEP 668 setups.\nInstall uv now? [Y/n] "
+    )).trim().toLowerCase();
+  } finally {
+    readline.close();
+  }
+  if (answer === "n" || answer === "no") {
+    console.log("Continuing with `python3 -m pip install --user`. You may hit PEP 668 errors on managed Pythons.");
+    return false;
+  }
+  return await installUv();
+}
+async function installUv() {
+  const brew = await findExecutable(["brew"]);
+  if (brew) {
+    console.log("Installing uv via Homebrew...");
+    const result = await runCommand(brew, ["install", "uv"], { allowFailure: true });
+    if (result.exitCode === 0) {
+      if (result.stdout.trim()) {
+        console.log(result.stdout.trim());
+      }
+      if (await findExecutable(["uv"])) {
+        return true;
+      }
+    } else {
+      console.warn(`brew install uv failed: ${(result.stderr || result.stdout).trim()}`);
+    }
+  }
+  if (await findExecutable(["curl"]) && await findExecutable(["sh"])) {
+    console.log("Installing uv via the official install script (curl -LsSf https://astral.sh/uv/install.sh | sh)...");
+    const result = await runCommand("sh", ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], {
+      allowFailure: true
+    });
+    if (result.exitCode === 0) {
+      if (result.stdout.trim()) {
+        console.log(result.stdout.trim());
+      }
+      if (await findExecutable(["uv"])) {
+        return true;
+      }
+      console.warn(
+        "uv installed, but the new binary is not yet on this shell PATH. Open a new shell (or `source ~/.zshrc` / `source ~/.bashrc`) and re-run `threadnote install`."
+      );
+      return false;
+    }
+    console.warn(`uv install script failed: ${(result.stderr || result.stdout).trim()}`);
+  }
+  console.warn(
+    "Could not install uv automatically. Install it manually (brew install uv) and re-run threadnote install."
+  );
+  return false;
+}
 async function getPythonSystemCertificatesInstallCommand(serverPath) {
   const pythonPath = await siblingPythonForExecutable(serverPath);
   if (!pythonPath) {
@@ -10183,38 +10468,38 @@ function printInstallNextSteps(options) {
 }
 async function writeTemplateIfMissing(options) {
   if (await exists(options.destinationPath)) {
-    const currentContent = await (0, import_promises9.readFile)(options.destinationPath, "utf8");
+    const currentContent = await (0, import_promises10.readFile)(options.destinationPath, "utf8");
     if (options.shouldRepair?.(currentContent) !== true) {
       console.log(`Already exists: ${options.destinationPath}`);
       return;
     }
-    const rendered2 = renderTemplate(await (0, import_promises9.readFile)(options.templatePath, "utf8"), options.config);
+    const rendered2 = renderTemplate(await (0, import_promises10.readFile)(options.templatePath, "utf8"), options.config);
     if (options.dryRun) {
       console.log(`Would repair generated config: ${options.destinationPath}`);
       return;
     }
     const backupPath = `${options.destinationPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises9.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
-    await (0, import_promises9.chmod)(backupPath, 384);
-    await (0, import_promises9.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
-    await (0, import_promises9.chmod)(options.destinationPath, 384);
+    await (0, import_promises10.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.chmod)(backupPath, 384);
+    await (0, import_promises10.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.chmod)(options.destinationPath, 384);
     console.log(`Repaired generated config: ${options.destinationPath}`);
     console.log(`Backup: ${backupPath}`);
     return;
   }
-  const rendered = renderTemplate(await (0, import_promises9.readFile)(options.templatePath, "utf8"), options.config);
+  const rendered = renderTemplate(await (0, import_promises10.readFile)(options.templatePath, "utf8"), options.config);
   if (options.dryRun) {
     console.log(`Would write ${options.destinationPath}`);
     return;
   }
-  await ensureDirectory((0, import_node_path8.dirname)(options.destinationPath), false);
-  await (0, import_promises9.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
-  await (0, import_promises9.chmod)(options.destinationPath, 384);
+  await ensureDirectory((0, import_node_path9.dirname)(options.destinationPath), false);
+  await (0, import_promises10.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.chmod)(options.destinationPath, 384);
   console.log(`Wrote ${options.destinationPath}`);
 }
 async function installCommandShim(dryRun) {
   const binDir = expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin");
-  const shimPath = (0, import_node_path8.join)(binDir, "threadnote");
+  const shimPath = (0, import_node_path9.join)(binDir, "threadnote");
   const existingContent = await readFileIfExists(shimPath);
   if (existingContent && !isManagedCommandShim(existingContent)) {
     console.log(`WARN not overwriting existing command shim: ${shimPath}`);
@@ -10230,12 +10515,12 @@ async function installCommandShim(dryRun) {
     return;
   }
   await ensureDirectory(binDir, false);
-  await (0, import_promises9.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
-  await (0, import_promises9.chmod)(shimPath, 493);
+  await (0, import_promises10.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
+  await (0, import_promises10.chmod)(shimPath, 493);
   console.log(`Wrote command shim: ${shimPath}`);
 }
 async function removeCommandShim(dryRun) {
-  const shimPath = (0, import_node_path8.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const shimPath = (0, import_node_path9.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
   if (content === void 0) {
     console.log(`Already absent: ${shimPath}`);
@@ -10269,8 +10554,8 @@ async function installUserAgentInstructions(dryRun) {
       console.log(currentContent === void 0 ? `Would write ${targetPath}` : `Would update ${targetPath}`);
       continue;
     }
-    await ensureDirectory((0, import_node_path8.dirname)(targetPath), false);
-    await (0, import_promises9.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    await ensureDirectory((0, import_node_path9.dirname)(targetPath), false);
+    await (0, import_promises10.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(currentContent === void 0 ? `Wrote ${targetPath}` : `Updated ${targetPath}`);
   }
 }
@@ -10307,7 +10592,7 @@ async function removeUserAgentInstructions(dryRun) {
       console.log(`Would update ${targetPath}`);
       continue;
     }
-    await (0, import_promises9.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    await (0, import_promises10.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(`Updated ${targetPath}`);
   }
 }
@@ -10327,7 +10612,7 @@ async function renderUserAgentInstructions(target) {
   ].join("\n");
 }
 async function renderUserAgentInstructionsBlock() {
-  const instructions = (await (0, import_promises9.readFile)((0, import_node_path8.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
+  const instructions = (await (0, import_promises10.readFile)((0, import_node_path9.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
   return `${USER_INSTRUCTIONS_START_MARKER}
 ${instructions}
 ${USER_INSTRUCTIONS_END_MARKER}`;
@@ -10405,9 +10690,9 @@ async function installLaunchAgent(config, dryRun) {
   if ((0, import_node_os6.platform)() !== "darwin") {
     throw new Error("launchd autostart is only supported on macOS.");
   }
-  const source = (0, import_node_path8.join)(toolRoot(), "config", "launchd", `${LAUNCHD_LABEL}.plist.template`);
+  const source = (0, import_node_path9.join)(toolRoot(), "config", "launchd", `${LAUNCHD_LABEL}.plist.template`);
   const destination = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
-  const rendered = renderTemplate(await (0, import_promises9.readFile)(source, "utf8"), config);
+  const rendered = renderTemplate(await (0, import_promises10.readFile)(source, "utf8"), config);
   if (dryRun) {
     console.log(`Would write ${destination}`);
     console.log(`Would run: launchctl unload ${destination}`);
@@ -10415,9 +10700,9 @@ async function installLaunchAgent(config, dryRun) {
     console.log(`Would run: launchctl start ${LAUNCHD_LABEL}`);
     return;
   }
-  await ensureDirectory((0, import_node_path8.dirname)(destination), false);
-  await ensureDirectory((0, import_node_path8.dirname)(openVikingLogPath(config)), false);
-  await (0, import_promises9.writeFile)(destination, rendered, "utf8");
+  await ensureDirectory((0, import_node_path9.dirname)(destination), false);
+  await ensureDirectory((0, import_node_path9.dirname)(openVikingLogPath(config)), false);
+  await (0, import_promises10.writeFile)(destination, rendered, "utf8");
   await maybeRun(false, "launchctl", ["unload", destination], { allowFailure: true });
   await maybeRun(false, "launchctl", ["load", destination]);
   await maybeRun(false, "launchctl", ["start", LAUNCHD_LABEL]);
@@ -10480,7 +10765,7 @@ function isGeneratedLocalPilotConfig(parsed, config) {
   if (typeof parsed.default_user !== "string") {
     return false;
   }
-  if (!isJsonObject(parsed.storage) || parsed.storage.workspace !== (0, import_node_path8.join)(config.agentContextHome, "data")) {
+  if (!isJsonObject(parsed.storage) || parsed.storage.workspace !== (0, import_node_path9.join)(config.agentContextHome, "data")) {
     return false;
   }
   return isJsonObject(parsed.server) && parsed.server.host === config.host && String(parsed.server.port) === String(config.port);
@@ -10508,9 +10793,20 @@ async function main() {
     await runDoctor(config, options);
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
-  program2.command("install").description("Install OpenViking, local config files, command shim, and user-level agent instructions").option("--dry-run", "Print the actions without making changes").option("--no-start", "Do not start OpenViking or check server health after installing").option("--package-manager <manager>", "uv, pipx, or pip", parsePackageManager).action(async (options) => {
+  program2.command("install").description("Install OpenViking, local config files, command shim, and user-level agent instructions").option("--dry-run", "Print the actions without making changes").option("--no-start", "Do not start OpenViking or check server health after installing").option("--package-manager <manager>", "uv, pipx, or pip", parsePackageManager).option(
+    "--with-hooks",
+    "Also install agent-side hooks (Claude PreCompact + SessionStart) for deterministic handoff snapshots and context preload"
+  ).action(async (options) => {
     const config = getRuntimeConfig(program2);
     await runInstall(config, options);
+    if (options.withHooks === true) {
+      const dryRun = options.dryRun === true;
+      for (const agent of ["claude", "codex", "cursor", "copilot"]) {
+        console.log(`
+--- ${agent} hooks ---`);
+        await runHooksInstall(config, agent, { apply: !dryRun, dryRun });
+      }
+    }
     await maybeNotifyUpdate(config, { dryRun: options.dryRun === true });
   });
   program2.command("update").description("Update the published Threadnote package, then repair local shims and MCP config").option("--check", "Only check whether a newer version is available").option("--dry-run", "Print update and repair commands without running them").option("--force", "Run package-manager update even if this version is already current").option("--registry <url>", "npm registry URL", process.env.THREADNOTE_NPM_REGISTRY).option("--runtime <runtime>", "auto, npm, bun, or deno", parseUpdateRuntime, "auto").option("--no-repair", "Skip threadnote repair after updating the package").option("--no-post-update", "Skip post-update migration prompts").option("--yes", "Accept applicable post-update migrations without prompting").action(async (options) => {
@@ -10555,6 +10851,21 @@ async function main() {
   program2.command("mcp-install").description("Install OpenViking MCP config for a supported agent").argument("<agent>", "codex, claude, cursor, or copilot").option("--apply", "Actually modify the selected agent config").option("--name <name>", "MCP server name", OPENVIKING_MCP_NAME).option("--native-http", "Install OpenViking native HTTP MCP endpoint instead of the local stdio adapter").option("--scope <scope>", "Claude MCP config scope: user, local, or project", parseClaudeMcpScope, "user").option("--url <url>", "OpenViking native HTTP MCP URL").option("--bearer-token-env-var <name>", "Environment variable containing the local API key").action(async (agent, options) => {
     await runMcpInstall(getRuntimeConfig(program2), parseAgentClient(agent), options);
   });
+  program2.command("install-hooks").description(
+    "Install deterministic agent hooks (Claude PreCompact + SessionStart). Soft instruction files remain the cross-agent guidance surface; hooks add a deterministic safety net where the agent supports it."
+  ).argument("<agent>", "codex, claude, cursor, or copilot").option("--apply", "Actually modify the selected agent config").option("--dry-run", "Print the planned change without applying it").option("--remove", "Remove threadnote-managed hook entries instead of adding them").action(async (agent, options) => {
+    await runHooksInstall(getRuntimeConfig(program2), parseAgentClient(agent), options);
+  });
+  program2.command("pre-compact-hook", { hidden: true }).description(
+    "Hook entry point: store a handoff snapshot before context compaction. Used by `install-hooks claude`."
+  ).option("--dry-run", "Print the handoff payload without writing it").action(async (options) => {
+    await runPreCompactHook(getRuntimeConfig(program2), options);
+  });
+  program2.command("session-start-hook", { hidden: true }).description(
+    "Hook entry point: print the latest threadnote handoff/feature memory for the current repo so Claude can preload it."
+  ).option("--dry-run", "Print the planned ov command without running it").action(async (options) => {
+    await runSessionStartHook(getRuntimeConfig(program2), options);
+  });
   program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--kind <kind>", "durable, handoff, incident, preference, or smoke", parseMemoryKind, "durable").option("--project <name>", "Project/repo/topic namespace for lifecycle-aware storage").option("--replace <uri>", "Supersede an existing viking:// memory after the new memory is stored").option("--source-agent-client <name>", "codex, claude, cursor, copilot, or another client name", "codex").option("--status <status>", "active, archived, or superseded", parseMemoryStatus, "active").option("--stdin", "Read memory text from stdin").option("--text <text>", "Memory text to store").option("--topic <name>", "Stable topic name; active memories with the same project/topic update one file").action(async (options) => {
     await runRemember(getRuntimeConfig(program2), options);
   });