paseo-smart-session 3.5.0 → 3.6.1

package/server/hooklib/asks.mjs

@@ -0,0 +1,163 @@
+/**
+ * The record of what this session has already been asked, and what it answered.
+ *
+ * Asking once and never again lets a session drift; asking every turn is nagging.
+ * So the ask is latched, re-armed by growth rather than by a clock alone, and can
+ * be switched off for a while by the agent itself — that last part is what makes it
+ * a question instead of an announcement.
+ *
+ * One file per agent rather than one shared file. `state/<agentId>.md` already
+ * works that way, and it means the `Stop` hook and the `defer_compaction` tool —
+ * two separate processes — can never be writing the same file at the same moment.
+ */
+
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+import { pluginDir } from "./pointer.mjs";
+
+/** Asks per compaction epoch, after which the session is left to its own judgement. */
+export const MAX_ASKS = 3;
+
+/**
+ * Further occupancy, in percentage points of the window, that re-arms the ask.
+ *
+ * Time alone is the wrong trigger: a session parked at 31% for an hour has not
+ * changed its situation, and one that went 31% to 55% in ten minutes plainly has.
+ */
+export const RE_ASK_GROWTH_PCT = 10;
+
+/**
+ * `now*` is the upper line's own record. It is kept apart from the end-of-turn ask
+ * so that having been asked politely at the lower line never silences the one ask
+ * that says "stop pushing on", and `deferredAt` survives an answered ask so the
+ * upper line can tell "deferred after I asked" from "never answered".
+ */
+const EMPTY = {
+  askCount: 0,
+  lastAskedAt: null,
+  askedAtPct: null,
+  deferredUntil: null,
+  deferReason: null,
+  deferredAt: null,
+  nowAskCount: 0,
+  nowAskedAt: null,
+};
+
+/**
+ * Keyed by Paseo agent id where there is one, because that survives compaction
+ * whatever Claude Code decides to do with the session id.
+ */
+export function ledgerPath(sessionId, agentId = process.env.PASEO_AGENT_ID) {
+  const key = agentId !== undefined && agentId !== "" ? agentId : sessionId;
+  if (typeof key !== "string" || key === "") return null;
+  return join(pluginDir(), "asks", `${key.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+export function readLedger(sessionId, agentId) {
+  const path = ledgerPath(sessionId, agentId ?? undefined);
+  if (path === null) return { ...EMPTY };
+  try {
+    return { ...EMPTY, ...JSON.parse(readFileSync(path, "utf8")) };
+  } catch {
+    return { ...EMPTY };
+  }
+}
+
+export function writeLedger(sessionId, ledger, agentId) {
+  const path = ledgerPath(sessionId, agentId ?? undefined);
+  if (path === null) return;
+  try {
+    mkdirSync(join(pluginDir(), "asks"), { recursive: true });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify(ledger), "utf8");
+    renameSync(temp, path);
+  } catch {
+    // A hook that cannot persist its latch must still not break the turn.
+  }
+}
+
+/**
+ * Forgets everything, because the window just emptied.
+ *
+ * A compaction is a new epoch: the occupancy the last ask was about is gone, and a
+ * session that fills up again deserves to be asked again.
+ */
+export function resetLedger(sessionId) {
+  const path = ledgerPath(sessionId);
+  if (path === null) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // A stale ledger costs one missed ask, never a failed turn.
+  }
+}
+
+/** The agent's own answer: not now, and here is for how long. */
+export function defer(sessionId, minutes, reason, agentId) {
+  const ledger = readLedger(sessionId, agentId);
+  const until = new Date(Date.now() + minutes * 60_000).toISOString();
+  writeLedger(sessionId, { ...ledger, deferredUntil: until, deferReason: reason, deferredAt: new Date().toISOString() }, agentId);
+  return until;
+}
+
+/**
+ * Whether to ask, given what has already been said and how much has changed.
+ *
+ * `pct` is the occupancy now; `askedAtPct` the occupancy the last ask was about.
+ */
+function deferred(ledger, now) {
+  if (ledger.deferredUntil === null) return false;
+  const until = Date.parse(ledger.deferredUntil);
+  return Number.isFinite(until) && now < until;
+}
+
+export function shouldAsk(ledger, pct, now = Date.now()) {
+  if (deferred(ledger, now)) return false;
+  if (ledger.askCount >= MAX_ASKS) return false;
+  if (ledger.askedAtPct === null) return true;
+  return pct >= ledger.askedAtPct + RE_ASK_GROWTH_PCT;
+}
+
+/** Records that the question was actually put to the model. */
+export function recordAsk(sessionId, ledger, pct) {
+  writeLedger(sessionId, {
+    ...ledger,
+    askCount: ledger.askCount + 1,
+    lastAskedAt: new Date().toISOString(),
+    askedAtPct: pct,
+    // An answered ask clears the deferral it was waiting out.
+    deferredUntil: null,
+    deferReason: null,
+  });
+}
+
+/**
+ * Whether to ask right away, mid-turn, at the upper line.
+ *
+ * Once per compaction epoch. It comes back only if the agent answered the last one
+ * with a deferral and that deferral has run out — ignoring it earns no repeat, so a
+ * long turn hears it once rather than after every tool call — and never more than
+ * `MAX_ASKS` times in all. Any live deferral, from either ask, holds it off: the
+ * agent's "not now" is one answer, not one per line.
+ */
+export function shouldAskNow(ledger, now = Date.now()) {
+  if (deferred(ledger, now)) return false;
+  if (ledger.nowAskCount === 0 || ledger.nowAskedAt === null) return true;
+  if (ledger.nowAskCount >= MAX_ASKS) return false;
+  const asked = Date.parse(ledger.nowAskedAt);
+  const answered = ledger.deferredAt === null ? Number.NaN : Date.parse(ledger.deferredAt);
+  return Number.isFinite(asked) && Number.isFinite(answered) && answered >= asked;
+}
+
+/** Records that the upper line's question was put to the model. */
+export function recordNowAsk(sessionId, ledger) {
+  writeLedger(sessionId, {
+    ...ledger,
+    nowAskCount: ledger.nowAskCount + 1,
+    nowAskedAt: new Date().toISOString(),
+    deferredUntil: null,
+    deferReason: null,
+  });
+}

package/server/hooklib/context.mjs

@@ -0,0 +1,284 @@
+/**
+ * What every hook needs to know about the session it is running in.
+ *
+ * Two hooks now answer "how full is this context" — `context-threshold.mjs` on
+ * `PostToolUse` and `ask-compact.mjs` on `Stop` — and they must not disagree. One
+ * reading them differently from the other would mean the agent hears the number and
+ * the advice from two different sessions.
+ *
+ * Everything here reads the tail of a file rather than the whole of it: these run
+ * on the hot path, and the newest row is the only one that matters.
+ */
+
+import { closeSync, fstatSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+
+import { pluginDir } from "./pointer.mjs";
+
+/** Enough tail to contain the last assistant message in any realistic transcript. */
+const TAIL_BYTES = 256 * 1024;
+
+/**
+ * Defaults mirroring thresholds.shared.ts, used when the plugin has not written a
+ * settings file yet. Kept in sync by a test that runs the hooks and checks where
+ * they fire against the shared module's numbers.
+ *
+ * Two profiles because a percentage of the window is the wrong unit on its own:
+ * what tires a context is the absolute prefix re-read every turn, so 30% of a
+ * million tokens is a heavier context than 85% of two hundred thousand.
+ */
+export const DEFAULT_THRESHOLDS = {
+  largeWindowFrom: 400_000,
+  large: { notice: 15, closing: 22, compact: 30, now: 40 },
+  small: { notice: 60, closing: 75, compact: 85, now: 90 },
+};
+
+export const BANDS = ["notice", "closing", "compact"];
+
+export const DEFAULT_SETTINGS = {
+  enabled: true,
+  showPill: true,
+  autoEnrol: true,
+  freshStateMinutes: 30,
+  thresholds: DEFAULT_THRESHOLDS,
+};
+
+/** The plugin's settings are the single source of truth when they exist. */
+export function readSettings() {
+  try {
+    const raw = JSON.parse(readFileSync(join(pluginDir(), "settings.json"), "utf8"));
+    const merged = { ...DEFAULT_THRESHOLDS, ...(raw.thresholds ?? {}) };
+    return {
+      // Absent means an install that predates the switch, which was always meant
+      // to be on once it could only ask rather than act.
+      enabled: raw.enabled !== false,
+      showPill: raw.showPill !== false,
+      autoEnrol: raw.autoEnrol !== false,
+      freshStateMinutes:
+        typeof raw.freshStateMinutes === "number" && raw.freshStateMinutes > 0
+          ? raw.freshStateMinutes
+          : DEFAULT_SETTINGS.freshStateMinutes,
+      thresholds: {
+        largeWindowFrom: merged.largeWindowFrom ?? DEFAULT_THRESHOLDS.largeWindowFrom,
+        large: withUpperLine(merged.large, DEFAULT_THRESHOLDS.large),
+        small: withUpperLine(merged.small, DEFAULT_THRESHOLDS.small),
+      },
+    };
+  } catch {
+    return DEFAULT_SETTINGS;
+  }
+}
+
+/**
+ * A saved profile, with the upper line filled in when it predates one.
+ *
+ * Mirrors `normalizeProfile` in thresholds.ts: the saved lower line is kept, and an
+ * absent upper line keeps the default's distance above it, never falling below it.
+ */
+export function withUpperLine(saved, fallback) {
+  const profile = { ...fallback, ...(saved ?? {}) };
+  const compact = profile.compact;
+  const migrated = Math.min(99, Math.max(fallback.now, compact + (fallback.now - fallback.compact)));
+  const raw = typeof saved?.now === "number" && Number.isFinite(saved.now) ? saved.now : migrated;
+  return { ...profile, now: Math.min(99, Math.max(Math.min(99, compact + 1), raw)) };
+}
+
+export function profileFor(maxTokens, thresholds) {
+  return maxTokens >= thresholds.largeWindowFrom ? thresholds.large : thresholds.small;
+}
+
+/**
+ * Whether this agent is one the governor may speak to.
+ *
+ * The same rule settings.server.ts resolves, duplicated here because a hook on the
+ * hot path must not open a daemon connection to answer it: an explicit answer in
+ * `enrolment.json` outranks the state-file inference in both directions, and the
+ * inference itself only counts while `autoEnrol` is on.
+ */
+export function isEnrolled(agentId, settings = readSettings()) {
+  if (typeof agentId !== "string" || agentId === "") return false;
+  try {
+    const overrides = JSON.parse(readFileSync(join(pluginDir(), "enrolment.json"), "utf8"));
+    if (typeof overrides?.[agentId] === "boolean") return overrides[agentId];
+  } catch {
+    // No file, or one we cannot read: nobody has overridden anything.
+  }
+  if (!settings.autoEnrol) return false;
+  try {
+    return readdirSync(join(pluginDir(), "state")).includes(`${agentId}.md`);
+  } catch {
+    return false;
+  }
+}
+
+/** The tail of a file as text, or null if it cannot be read. */
+function tail(path, bytes) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.allocUnsafe(length);
+    readSync(fd, buffer, 0, length, size - length);
+    return buffer.toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Context occupancy from the last assistant message's usage.
+ *
+ * input + cache_read + cache_creation + output is the same arithmetic Claude Code
+ * itself documents for a resumed session's `context_tokens`, so it is the
+ * sanctioned way to ask "how much of the window is currently occupied".
+ */
+export function readContextTokens(transcriptPath) {
+  const text = tail(transcriptPath, TAIL_BYTES);
+  if (text === null) return null;
+  const lines = text.split("\n");
+
+  // Backwards: the newest assistant message wins, and a partial first line from
+  // slicing mid-file simply fails to parse and is skipped.
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined || line === "" || !line.includes('"usage"')) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.type !== "assistant") continue;
+    // A subagent's usage is its own window, not the main thread's.
+    if (entry.isSidechain === true) continue;
+    const usage = entry.message?.usage;
+    if (usage === undefined) continue;
+    const used =
+      (usage.input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0) +
+      (usage.output_tokens ?? 0);
+    return { used, model: entry.message?.model ?? null };
+  }
+  return null;
+}
+
+/**
+ * Models whose context window is not the current default of 1M.
+ *
+ * The transcript records the resolved model id (`claude-opus-5`), never the config
+ * alias (`opus[1m]`), so the suffix is not a signal. Every current Opus, Sonnet and
+ * Fable model has a 1M window; Haiku and the older generations do not.
+ */
+const SMALL_WINDOW = /haiku|-3-|sonnet-3|opus-3|sonnet-4-5|opus-4-5|sonnet-4-20|opus-4-20/;
+
+/**
+ * The window size Paseo reported for this agent, from the recorder's own log.
+ *
+ * Read from the tail, like the transcript: this is the hot path, and the newest row
+ * is the only one that matters.
+ */
+function recordedWindow() {
+  const agentId = process.env.PASEO_AGENT_ID;
+  if (agentId === undefined || agentId === "") return null;
+  const month = new Date().toISOString().slice(0, 7);
+  const text = tail(join(pluginDir(), `context-${month}.jsonl`), 64 * 1024);
+  if (text === null) return null;
+
+  const lines = text.split("\n");
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined || !line.includes(agentId)) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row.agentId === agentId && typeof row.maxTokens === "number" && row.maxTokens > 0) {
+        return row.maxTokens;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * The window size for this session.
+ *
+ * Getting this wrong is worse than not warning at all: assuming 200k on a 1M
+ * session warns at a fifth of the real occupancy and reports negative headroom.
+ * So the first choice is what Paseo actually measured for this agent — recorded by
+ * the plugin, read from the tail of its log — and the model table is the fallback.
+ */
+export function windowFor(model) {
+  const override = Number(process.env.SMART_SESSION_CONTEXT_WINDOW ?? "");
+  if (Number.isFinite(override) && override > 0) return override;
+
+  const recorded = recordedWindow();
+  if (recorded !== null) return recorded;
+
+  if (typeof model === "string" && SMALL_WINDOW.test(model)) return 200_000;
+  return 1_000_000;
+}
+
+/**
+ * Occupancy, the window it is measured against, and the bands that apply.
+ *
+ * Returns null when the transcript says nothing yet — a session with no completed
+ * assistant turn has no usage to read, and guessing would be worse than silence.
+ */
+export function occupancy(transcriptPath, settings = readSettings()) {
+  const reading = readContextTokens(transcriptPath);
+  if (reading === null) return null;
+  const max = windowFor(reading.model);
+  return {
+    used: reading.used,
+    max,
+    model: reading.model,
+    pct: Math.floor((reading.used / max) * 100),
+    profile: profileFor(max, settings.thresholds),
+  };
+}
+
+/**
+ * Names Smart Session's tools in agent-facing text as this agent has them. On Paseo 0.15+ they are
+ * served through Paseo's own MCP with a `smart_` prefix (`SMART_SESSION_TOOLS=native` in the
+ * agent's environment); sessions opened before that, and the stdio fallback, keep the bare names.
+ */
+const TOOL_MENTION = /\b(call|Call|with) (checkpoint|request_compaction|defer_compaction|context_status|budget_status)\b/g;
+export function named(text, native = toolsMode() === "native") {
+  return native ? text.replace(TOOL_MENTION, "$1 smart_$2") : text;
+}
+
+/**
+ * Which tools this session has. Native tools live in the plugin process, so a plugin update or reload detaches them
+ * from every open session until it reopens (Paseo 0.15.2 reopens a session before that agent's next prompt). The
+ * worker records its instance in `tools-instance.json` and each native attach the instance that attached it in
+ * `tools/native-<agentId>.json`; a mismatch means "detached".
+ */
+export function toolsMode(env = process.env) {
+  if (env.SMART_SESSION_TOOLS !== "native") return env.SMART_SESSION_TOOLS === "stdio" ? "stdio" : "legacy";
+  const read = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } };
+  const current = read(join(pluginDir(), "tools-instance.json"));
+  const agentId = env.PASEO_AGENT_ID;
+  const mine = agentId ? read(join(pluginDir(), "tools", `native-${agentId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`)) : null;
+  return current?.instance && mine?.instance !== current.instance ? "detached" : "native";
+}
+
+/** What a detached session is told: the same tools, one call each, through mcp.mjs beside this plugin's hooks. */
+export function detachedNotice(bridge) {
+  return `Smart Session was updated while this session was open, so its smart_* tools are detached and fail with "Tool not found" until this session reopens (Paseo reopens it before your next prompt). Until then run the same tools by their plain names: node ${JSON.stringify(bridge)} call <tool> '<json>' (for example: call checkpoint '{"current_step":"..."}'). Do not mention this to the user.`;
+}
+
+/** Agent-facing text for this session's tools: smart_ names, plain names, or plain names plus the bridge. */
+export function forTools(text, bridge) {
+  const mode = toolsMode();
+  if (mode === "native") return named(text, true);
+  return mode === "detached" ? `${text}\n\n${detachedNotice(bridge)}` : text;
+}

package/server/hooklib/pointer.mjs

@@ -0,0 +1,149 @@
+/**
+ * The state-file pointer, and the two ways it can reach the model.
+ *
+ * Compaction is the one moment the agent is deciding what it knows, so it is the
+ * one moment worth spending an injection on. But `PostCompact` — the event that
+ * knows a compaction happened — cannot inject: Claude Code validates
+ * `hookSpecificOutput.hookEventName` against a union that does not contain it, and
+ * rejects the whole output. So the pointer is written here as a small pending note
+ * and delivered by whichever hook speaks first:
+ *
+ *   - `SessionStart` with `source: "compact"`, which fires in the emptied context
+ *     and does accept `additionalContext`; or
+ *   - the next `PostToolUse`, which is guaranteed to run.
+ *
+ * Whoever delivers it clears it, so it is said exactly once.
+ *
+ * Keyed by Paseo agent id when there is one, because that survives compaction
+ * whatever Claude Code decides to do with the session id.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function pluginDir() {
+  const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+  return join(home, "plugin-data", "smart-session");
+}
+
+/** The same derivation the agent's `checkpoint` tool uses. */
+export function statePath() {
+  const override = process.env.SMART_SESSION_STATE_FILE;
+  if (override !== undefined && override !== "") return override;
+  const agentId = process.env.PASEO_AGENT_ID;
+  if (agentId === undefined || agentId === "") return null;
+  return join(pluginDir(), "state", `${agentId}.md`);
+}
+
+/** Seconds since the state file was last written, or null if there isn't one. */
+export function stateAgeSeconds(path) {
+  if (path === null || !existsSync(path)) return null;
+  try {
+    return Math.round((Date.now() - statSync(path).mtimeMs) / 1000);
+  } catch {
+    return null;
+  }
+}
+
+const STALE_AFTER_SECONDS = 30 * 60;
+
+/**
+ * What the continuation needs to hear, given what is actually on disk.
+ *
+ * Returns null when there is nowhere to point — no agent id, no override — since
+ * naming no file at all would be worse than silence.
+ */
+export function pointerText(path = statePath(), age = stateAgeSeconds(path)) {
+  if (path === null) return null;
+  if (age === null) {
+    return (
+      `No durable state file exists yet for this session (expected at ${path}). Everything not in the summary above is now gone. ` +
+      "Before continuing, write down the goal, the step in progress and its exact next action, decisions made and why, and every approach already tried and rejected — then keep it current, so the next compaction costs nothing."
+    );
+  }
+  const lines = [
+    `Durable task state for this session is at ${path}. Re-read it before acting. Where it disagrees with the summary above, the file is correct — it was written deliberately; the summary was compressed automatically.`,
+  ];
+  // A state file older than the work it is supposed to describe is worse than
+  // none, because it reads as authoritative. Say so plainly.
+  if (age > STALE_AFTER_SECONDS) {
+    lines.push(
+      `Note: that file was last written ${Math.round(age / 60)} minutes ago, so it may predate recent work. Reconcile it against the summary and update it before continuing.`,
+    );
+  }
+  return lines.join(" ");
+}
+
+function pointerPath(sessionId) {
+  const agentId = process.env.PASEO_AGENT_ID;
+  const key = agentId !== undefined && agentId !== "" ? agentId : sessionId;
+  if (typeof key !== "string" || key === "") return null;
+  return join(pluginDir(), "pointers", `${key.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+function readNote(sessionId) {
+  const path = pointerPath(sessionId);
+  if (path === null) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeNote(sessionId, note) {
+  const path = pointerPath(sessionId);
+  if (path === null) return;
+  try {
+    mkdirSync(join(pluginDir(), "pointers"), { recursive: true });
+    writeFileSync(path, JSON.stringify(note), "utf8");
+  } catch {
+    // A hook that cannot persist its note must still not break the turn.
+  }
+}
+
+/** Leaves the pointer where either delivery path will find it. */
+export function writePending(sessionId, text) {
+  if (text === null) return;
+  writeNote(sessionId, { at: new Date().toISOString(), text });
+}
+
+/**
+ * Records that the pointer has already reached the model for this compaction.
+ *
+ * Measured on a real compaction: `SessionStart:compact` fires ~55ms *before*
+ * `PostCompact`, so without this the later event would queue a note that the next
+ * tool call repeats. The marker is left in place rather than deleted — the next
+ * compaction overwrites it, and an absent file has to keep meaning "nothing
+ * pending".
+ */
+export function markDelivered(sessionId) {
+  writeNote(sessionId, { at: new Date().toISOString(), delivered: true });
+}
+
+/** Whether this compaction's pointer was already said, within `withinMs`. */
+export function deliveredRecently(sessionId, withinMs) {
+  const note = readNote(sessionId);
+  if (note?.delivered !== true) return false;
+  const at = Date.parse(note.at ?? "");
+  return Number.isFinite(at) && Date.now() - at < withinMs;
+}
+
+/** The pending pointer, without consuming it — nothing is cleared until it is said. */
+export function readPending(sessionId) {
+  const note = readNote(sessionId);
+  if (note === null || note.delivered === true) return null;
+  return typeof note.text === "string" && note.text !== "" ? note.text : null;
+}
+
+/** Called only once the pointer has actually been written to stdout. */
+export function clearPending(sessionId) {
+  const path = pointerPath(sessionId);
+  if (path === null) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // A stale note costs one repeated sentence, never a failed turn.
+  }
+}

package/server/install-on-load.ts

@@ -13,7 +13,9 @@
  * machine's real Claude Code settings just because something imported a function.
  */
 
-import { install } from "./install.ts";
+import { lifecycle } from "../shared/lifecycle.ts";
+import { install, refreshPointer, resolvePluginDir } from "./install.ts";
+import { removeGlobalRegistrations } from "./mcp-registrations.ts";
 
 void install()
   .then((report) => {
@@ -33,3 +35,31 @@ void install()
     }
   })
   .catch((error: unknown) => console.error("[smart-session] hook install failed", String(error)));
+
+// Older versions registered the agent tools globally; they are attached per launch now. Only an
+// install Paseo actually loads from this PASEO_HOME does this, so a check that loads the bundle
+// against a sandbox (check-teardown.mjs) never reaches the machine's real Claude and Codex homes.
+void resolvePluginDir()
+  .then((directory) => (directory === null ? [] : removeGlobalRegistrations()))
+  .then((results) => {
+    for (const result of results) {
+      if (result.status === "removed") console.log(`[smart-session] removed the global MCP registration from ${result.path} (backup beside it)`);
+      if (result.status === "error" || result.status === "unavailable") console.error(`[smart-session] could not remove the global MCP registration from ${result.path}: ${result.error ?? "no claude CLI on PATH"}`);
+    }
+  })
+  .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));