paseo-smart-session 3.6.0 → 3.6.1

package/hooks/ask.mjs

@@ -12,15 +12,20 @@
  * a queued compaction is still delivered once the session goes idle.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { forTools, isEnrolled, occupancy, readSettings } from "./context.mjs";
 import { fileURLToPath } from "node:url";
 import { dirname as parentOf } from "node:path";
 
-/** The one-call bridge a detached session is pointed at (beside this plugin's hooks). */
-export const BRIDGE = join(parentOf(fileURLToPath(import.meta.url)), "..", "mcp.mjs");
+/**
+ * The one-call bridge a detached session is pointed at. The stable shim in the data
+ * directory when it exists, since this install's own path is gone after the next update;
+ * otherwise the `mcp.mjs` beside these hooks.
+ */
+const BRIDGE_SHIM = join(pluginDir(), "hooks", "mcp.mjs");
+export const BRIDGE = existsSync(BRIDGE_SHIM) ? BRIDGE_SHIM : join(parentOf(fileURLToPath(import.meta.url)), "..", "mcp.mjs");
 import { pluginDir, stateAgeSeconds, statePath } from "./pointer.mjs";
 import { readLedger } from "./asks.mjs";
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {

package/server/hook-path.ts

@@ -0,0 +1,133 @@
+/**
+ * A path to this plugin's scripts that survives updates.
+ *
+ * Paseo installs every npm or Git update into a fresh directory and deletes the old one.
+ * Claude Code's hook commands and the stdio MCP server are absolute paths, so anything
+ * written against an install directory breaks the moment that directory goes: on
+ * 2026-11-09 the 3.6.0 update registered the hooks against the 3.5 directory seconds
+ * before Paseo removed it, and every hook failed with MODULE_NOT_FOUND for hours.
+ *
+ * So nothing outside the plugin names an install directory any more. Small shims live in
+ * the fixed data directory (`plugin-data/smart-session/hooks/`), and each one reads
+ * `current.json` beside it to find the install it should run. The plugin rewrites that
+ * pointer on every load and checks it on a slow timer. A shim whose target is missing
+ * exits 0 without a word: a hook that fails would fail every turn of every session.
+ */
+
+import { randomUUID } from "node:crypto";
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { dataDir } from "./store.ts";
+
+/** The scripts that get a shim: the three hooks, and the agent-facing MCP server. */
+export const SHIMMED = ["context-threshold.mjs", "ask-compact.mjs", "post-compact.mjs", "mcp.mjs"] as const;
+export type Shimmed = (typeof SHIMMED)[number];
+
+/** Where each script lives inside an install. */
+export function scriptIn(pluginDir: string, script: Shimmed): string {
+  return script === "mcp.mjs" ? join(pluginDir, "mcp.mjs") : join(pluginDir, "hooks", script);
+}
+
+/** The stable directory the shims and their pointer live in. */
+export function shimDir(): string {
+  return join(dataDir(), "hooks");
+}
+
+export function pointerPath(): string {
+  return join(shimDir(), "current.json");
+}
+
+/**
+ * The shim itself. Dependency-free, and it never fails: an unreadable pointer, a missing
+ * target, or a target that disappears between the check and the import all end in a
+ * silent exit 0. The real script runs in this same process through `import()`, so it
+ * keeps its own `import.meta.url` (and with it its siblings) and the hot `PostToolUse`
+ * path pays for no second Node start.
+ */
+export function shimSource(script: Shimmed): string {
+  const relative = script === "mcp.mjs" ? ["mcp.mjs"] : ["hooks", script];
+  return `#!/usr/bin/env node
+// Written by the Smart Session Paseo plugin, rewritten on every load. Do not edit.
+// Runs ${script} from the install named in current.json, or exits 0 if there is none.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+let target = null;
+try {
+  const { dir } = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "current.json"), "utf8"));
+  const candidate = typeof dir === "string" && dir !== "" ? join(dir, ...${JSON.stringify(relative)}) : null;
+  if (candidate !== null && existsSync(candidate)) target = candidate;
+} catch {}
+if (target === null) process.exit(0);
+try {
+  await import(pathToFileURL(target).href);
+} catch {
+  process.exit(0);
+}
+`;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeIfChanged(path: string, text: string): Promise<boolean> {
+  const current = await readFile(path, "utf8").catch(() => null);
+  if (current === text) return false;
+  const temp = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temp, text, "utf8");
+  await rename(temp, path);
+  return true;
+}
+
+/** The install directory the pointer names, or null when there is no readable pointer. */
+export async function readPointer(): Promise<string | null> {
+  try {
+    const { dir } = JSON.parse(await readFile(pointerPath(), "utf8")) as { dir?: unknown };
+    return typeof dir === "string" && dir !== "" ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether every shimmed script exists in that install. */
+export async function complete(pluginDir: string): Promise<boolean> {
+  const found = await Promise.all(SHIMMED.map((script) => exists(scriptIn(pluginDir, script))));
+  return found.every(Boolean);
+}
+
+/**
+ * Writes the shims and points them at `pluginDir`. Touches nothing that is already
+ * right, so the common case (every load after the first) reads five small files and
+ * writes none. Returns the shim directory, and whether the pointer moved.
+ */
+export async function pointShimsAt(pluginDir: string): Promise<{ dir: string; moved: boolean }> {
+  const dir = shimDir();
+  await mkdir(dir, { recursive: true });
+  for (const script of SHIMMED) await writeIfChanged(join(dir, script), shimSource(script));
+  const moved = await writeIfChanged(pointerPath(), `${JSON.stringify({ dir: pluginDir })}\n`);
+  return { dir, moved };
+}
+
+/** The stable path of one shim (whether or not it has been written yet). */
+export function shimFor(script: Shimmed): string {
+  return join(shimDir(), script);
+}
+
+/**
+ * The cheap check the timer runs: true when the pointer names an install that still has
+ * its scripts and every shim is in place. Stats only; reads and writes nothing else.
+ */
+export async function pointerHealthy(): Promise<boolean> {
+  const dir = await readPointer();
+  if (dir === null) return false;
+  const shims = await Promise.all(SHIMMED.map((script) => exists(shimFor(script))));
+  return shims.every(Boolean) && (await complete(dir));
+}

package/server/install-on-load.ts

@@ -13,7 +13,8 @@
  * machine's real Claude Code settings just because something imported a function.
  */
 
-import { install, resolvePluginDir } from "./install.ts";
+import { lifecycle } from "../shared/lifecycle.ts";
+import { install, refreshPointer, resolvePluginDir } from "./install.ts";
 import { removeGlobalRegistrations } from "./mcp-registrations.ts";
 
 void install()
@@ -47,3 +48,18 @@ void resolvePluginDir()
     }
   })
   .catch(() => undefined);
+
+// Self-heal. The hooks run through shims whose pointer names an install directory, and
+// Paseo deletes an install directory on update. install() above already points the shims
+// at the running version; this repairs the pointer if its target disappears later. A
+// healthy pointer costs a few stat calls and writes nothing, hence ten minutes.
+const HEAL_MS = 10 * 60_000;
+const heal = setInterval(() => {
+  void refreshPointer()
+    .then((moved) => {
+      if (moved) console.log("[smart-session] re-pointed the hook shims at the running install");
+    })
+    .catch(() => undefined);
+}, HEAL_MS);
+heal.unref?.();
+lifecycle.teardowns.push(() => clearInterval(heal));

package/server/install.ts

@@ -14,12 +14,15 @@
  *
  * The rules that make that acceptable:
  *
- *   - **Own only our own.** An entry is ours when its command points at a
- *     `hooks/*.mjs` in this repository. Nothing else in the file is read for
- *     meaning, reordered or rewritten.
- *   - **Never write a path that does not exist.** The plugin directory comes from
- *     Paseo's own `config.json` and is then checked for the scripts themselves. A
- *     hook command pointing at a missing file fails on every turn of every session.
+ *   - **Own only our own.** An entry is ours when its command points at one of our
+ *     `hooks/*.mjs` scripts: the stable shim in Smart Session's data directory, or
+ *     (from older versions, migrated on the next load) an install's own `hooks/`.
+ *     Nothing else in the file is read for meaning, reordered or rewritten.
+ *   - **Never name an install directory.** Paseo deletes the old one on every update,
+ *     so the commands run shims in the fixed data directory (`server/hook-path.ts`),
+ *     each guarded so that a missing shim is a silent no-op. The shims are written, and
+ *     their pointer checked against the scripts themselves, before any command naming
+ *     them is.
  *   - **Write only on a real change.** Reconciling to identical JSON writes nothing,
  *     so the common case — every reload after the first — touches no files.
  *   - **Be reversible.** One backup, kept from the first modification, and turning
@@ -28,11 +31,13 @@
 
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
-import { access, copyFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 
+import { PLUGIN_VERSION } from "../shared/version.ts";
+import { complete, pointerHealthy, pointShimsAt } from "./hook-path.ts";
 import { readSettings } from "./settings.ts";
 
 const execFileAsync = promisify(execFile);
@@ -94,16 +99,55 @@ async function exists(path: string): Promise<boolean> {
   }
 }
 
+interface Candidate {
+  readonly dir: string;
+  /** Explicitly named (SMART_SESSION_PLUGIN_DIR): taken as is, whatever its version. */
+  readonly explicit?: boolean;
+}
+
+/** Every install directory under `$PASEO_HOME/plugins/<id>/<install>/`, newest first. */
+async function scanInstalls(home: string): Promise<string[]> {
+  const root = join(home, "plugins");
+  const found: { dir: string; mtime: number }[] = [];
+  for (const id of await readdir(root).catch(() => [] as string[])) {
+    for (const install of await readdir(join(root, id)).catch(() => [] as string[])) {
+      // npm installs land in node_modules/<package>, Git installs in checkout/.
+      for (const dir of [join(root, id, install, "node_modules", "paseo-smart-session"), join(root, id, install, "checkout")]) {
+        const info = await stat(dir).catch(() => null);
+        if (info?.isDirectory()) found.push({ dir, mtime: info.mtimeMs });
+      }
+    }
+  }
+  return found.sort((a, b) => b.mtime - a.mtime).map(({ dir }) => dir);
+}
+
+async function packageVersion(dir: string): Promise<string | null> {
+  try {
+    const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as { name?: unknown; version?: unknown };
+    return pkg.name === "paseo-smart-session" && typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Where this plugin's files live, according to Paseo.
+ * Where the running plugin's files live.
  *
- * Read from the host's own `config.json` rather than derived from the module's
- * location: Paseo compiles `index.server.ts` into a bundle whose path is an
- * implementation detail, and `import.meta` is not safe to rely on across that
- * compilation. Every configured plugin is checked rather than just `smart-session`,
- * because a second install under `--id something-else` is a supported thing to do.
+ * Paseo evaluates the server bundle from a string and hands it no directory, so
+ * `import.meta.url` and `__dirname` say nothing. What the bundle does carry is its own
+ * version, and the install it came from carries the same one in `package.json`. That is
+ * the first test, because `config.json` is not trustworthy during an update: on
+ * 2026-11-09 it still named the previous install when this ran, the hooks were written
+ * against it, and Paseo deleted it seconds later.
+ *
+ * Candidates are `SMART_SESSION_PLUGIN_DIR` (taken as is), every plugin `config.json`
+ * names (a second install under `--id something-else` is supported), then every install
+ * directory under `$PASEO_HOME/plugins`, newest first. Only a directory holding the
+ * scripts counts. The first whose version is the running one wins; failing that, the
+ * first complete one, which is what this did before it knew its version.
  */
-export async function resolvePluginDir(): Promise<string | null> {
+export async function resolvePluginDir(options: { version?: string } = {}): Promise<string | null> {
+  const version = options.version ?? PLUGIN_VERSION;
   const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
   let configured: string[] = [];
   try {
@@ -114,21 +158,28 @@ export async function resolvePluginDir(): Promise<string | null> {
       .map((entry) => entry.path)
       .filter((path): path is string => typeof path === "string" && path !== "");
   } catch {
-    // No config, or one we cannot read. Fall through to the environment.
+    // No config, or one we cannot read. Fall through to the environment and the scan.
   }
 
   const fromEnv = process.env.SMART_SESSION_PLUGIN_DIR;
-  const candidates = fromEnv !== undefined && fromEnv !== "" ? [fromEnv, ...configured] : configured;
-
-  for (const candidate of candidates) {
+  const candidates: Candidate[] = [
+    ...(fromEnv !== undefined && fromEnv !== "" ? [{ dir: fromEnv, explicit: true }] : []),
+    ...configured.map((dir) => ({ dir })),
+    ...(await scanInstalls(home)).map((dir) => ({ dir })),
+  ];
+
+  let fallback: string | null = null;
+  const seen = new Set<string>();
+  for (const { dir, explicit } of candidates) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
     // The scripts themselves are the proof. A directory that merely has the right
     // name would still produce hook commands that fail on every turn.
-    const complete = await Promise.all(
-      OUR_SCRIPTS.map((script) => exists(join(candidate, "hooks", script))),
-    );
-    if (complete.every(Boolean)) return candidate;
+    if (!(await complete(dir))) continue;
+    if (explicit === true || (await packageVersion(dir)) === version) return dir;
+    fallback ??= dir;
   }
-  return null;
+  return fallback;
 }
 
 /** Whether a hook command is one of ours, wherever it was installed from. */
@@ -137,8 +188,18 @@ function isOurs(command: unknown): boolean {
   return OUR_SCRIPTS.some((script) => command.includes(`hooks/${script}`));
 }
 
-function commandFor(pluginDir: string, script: string): string {
-  return `node ${join(pluginDir, "hooks", script)}`;
+/** A shell word, single-quoted. */
+function quote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * The command for one hook: the stable shim, guarded, so a missing shim is a silent
+ * no-op rather than a failing hook on every turn of every session.
+ */
+export function commandFor(shims: string, script: string): string {
+  const path = quote(join(shims, script));
+  return `if [ -f ${path} ]; then node ${path}; fi`;
 }
 
 /**
@@ -148,7 +209,7 @@ function commandFor(pluginDir: string, script: string): string {
  * directory or renamed a script leaves nothing stale behind — and so the manual
  * entries an early adopter added by hand are adopted rather than duplicated.
  */
-export function reconcile(existing: HookMap, pluginDir: string | null): HookMap {
+export function reconcile(existing: HookMap, shims: string | null): HookMap {
   const next: HookMap = {};
 
   for (const [event, groups] of Object.entries(existing)) {
@@ -162,13 +223,13 @@ export function reconcile(existing: HookMap, pluginDir: string | null): HookMap
     if (kept.length > 0) next[event] = kept;
   }
 
-  if (pluginDir === null) return next;
+  if (shims === null) return next;
 
   for (const { event, matcher, script } of MANAGED) {
     const groups = next[event] ?? [];
     const entry: HookEntry = {
       type: "command",
-      command: commandFor(pluginDir, script),
+      command: commandFor(shims, script),
       timeout: HOOK_TIMEOUT_SECONDS,
     };
     const group = groups.find((candidate) => (candidate.matcher ?? "") === matcher);
@@ -226,8 +287,8 @@ const currentRuntime = (): McpRuntime => ({
  * the app launches its bundled `paseo` CLI. An AppImage mounts at a fresh path on
  * every launch, so its stable `$APPIMAGE` stands in for the mounted executable.
  */
-export function mcpDefinition(pluginDir: string, runtime: McpRuntime = currentRuntime()): McpDefinition {
-  const args = [join(pluginDir, "mcp.mjs")];
+export function mcpDefinition(pluginDir: string, runtime: McpRuntime = currentRuntime(), script?: string): McpDefinition {
+  const args = [script ?? join(pluginDir, "mcp.mjs")];
   if (runtime.electron === undefined) return { type: "stdio", command: "node", args };
   return {
     type: "stdio",
@@ -303,7 +364,25 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
   return serialize(async () => {
     const path = settingsPath();
     const settings = await readSettings();
-    const pluginDir = settings.installHooks ? await resolvePluginDir() : null;
+    // Resolved and pointed at whether or not hooks are installed: the stdio MCP server
+    // and the bridge the asks name run through the same shims.
+    const resolved = await resolvePluginDir();
+    let shims: string | null = null;
+    if (resolved !== null) {
+      try {
+        shims = (await pointShimsAt(resolved)).dir;
+      } catch (error) {
+        return {
+          pluginDir: resolved,
+          settingsPath: path,
+          changed: false,
+          hooks: [],
+          mcp: "skipped",
+          error: `Could not write the hook shims into Smart Session's data directory (${(error as NodeJS.ErrnoException).code ?? "error"}), so no hooks were installed.`,
+        };
+      }
+    }
+    const pluginDir = settings.installHooks ? resolved : null;
 
     if (settings.installHooks && pluginDir === null) {
       return {
@@ -339,7 +418,7 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
     }
 
     const before = (parsed.hooks ?? {}) as HookMap;
-    const after = reconcile(before, pluginDir);
+    const after = reconcile(before, pluginDir === null ? null : shims);
     const merged = { ...parsed, hooks: after };
     if (Object.keys(after).length === 0) delete (merged as { hooks?: unknown }).hooks;
 
@@ -364,3 +443,20 @@ export function install(options: { registerMcp?: boolean } = {}): Promise<Instal
     };
   });
 }
+
+/**
+ * Points the shims at the running install, if they do not already point at one that
+ * still exists. Cheap enough for a timer: when the pointer is healthy it stats a handful
+ * of files and writes nothing. When it moves, the hooks are reconciled too (which writes
+ * `settings.json` only if that changes anything). Returns whether the pointer moved.
+ */
+export async function refreshPointer(): Promise<boolean> {
+  // The load-time install() already pointed the shims at the running version; this only
+  // repairs a pointer whose target has since gone (or a shim someone deleted).
+  if (await pointerHealthy()) return false;
+  const dir = await resolvePluginDir();
+  if (dir === null) return false;
+  const { moved } = await pointShimsAt(dir);
+  if (moved) await install();
+  return moved;
+}

package/server/session-mcp.ts

@@ -1,9 +1,10 @@
 import type { PluginServerContext, PluginSessionOpenRequest } from "@getpaseo/plugin/server";
 import { randomUUID } from "node:crypto";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { readPointer, shimFor } from "./hook-path.ts";
 import { mcpDefinition, resolvePluginDir } from "./install.ts";
 import { type Invoke, nativeTools, nativeToolsAvailable } from "./native-tools.ts";
 import { readSettings } from "./settings.ts";
@@ -48,7 +49,10 @@ export function contributeSessionMcp(server: PluginServerContext, invoke: Invoke
 async function withStdio(request: PluginSessionOpenRequest): Promise<PluginSessionOpenRequest | void> {
   const directory = await resolvePluginDir();
   if (!directory) return;
-  const definition = mcpDefinition(directory);
+  // Through the stable shim when it is in place, so a session opened just before an
+  // update does not hold a path Paseo is about to delete.
+  const shim = shimFor("mcp.mjs");
+  const definition = mcpDefinition(directory, undefined, (await readPointer()) === directory && existsSync(shim) ? shim : undefined);
   return {
     ...request,
     env: { ...request.env, SMART_SESSION_TOOLS: "stdio" },

package/shared/version.ts

@@ -0,0 +1,10 @@
+/**
+ * This plugin's version, compiled into the bundle.
+ *
+ * Paseo evaluates the server bundle from a string, so the running code has no
+ * `import.meta.url` or `__dirname` to say which install directory it came from. Its
+ * version is the one thing it carries that the directory on disk also carries
+ * (`package.json`), which is how `resolvePluginDir()` tells the install that is running
+ * from a stale one during an update. `version.test.ts` keeps it equal to `package.json`.
+ */
+export const PLUGIN_VERSION = "3.6.1";