myagentmemory 0.5.1 → 0.5.3

package/dist/completions.d.ts

@@ -5,9 +5,21 @@ export interface CompletionInstallResult {
     profilePath?: string;
     profileUpdated: boolean;
 }
+export interface CompletionUninstallResult {
+    shell: CompletionShell;
+    completionPath: string;
+    removed: boolean;
+    profilePath?: string;
+    profileUpdated: boolean;
+}
 export declare function generateCompletion(shell: CompletionShell): string;
 export declare function detectCompletionShell(environment?: Record<string, string | undefined>, platform?: NodeJS.Platform): CompletionShell | null;
 export declare function installCompletion(shell: CompletionShell, options?: {
     homeDir?: string;
     platform?: NodeJS.Platform;
 }): CompletionInstallResult;
+/** Reverse of {@link installCompletion} across every supported shell. */
+export declare function uninstallCompletion(options?: {
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+}): CompletionUninstallResult[];

package/dist/completions.js

@@ -395,6 +395,29 @@ function ensureProfileBlock(filePath, lines) {
     fs.writeFileSync(filePath, updated, { mode: 0o600 });
     return true;
 }
+/** Reverse of {@link ensureProfileBlock}: strips the marker block, if present, from the given file. */
+function removeProfileBlock(filePath) {
+    const start = "# >>> agent-memory completion >>>";
+    const end = "# <<< agent-memory completion <<<";
+    if (!fs.existsSync(filePath))
+        return false;
+    const current = fs.readFileSync(filePath, "utf8");
+    const startIndex = current.indexOf(start);
+    const endIndex = startIndex === -1 ? -1 : current.indexOf(end, startIndex);
+    if (startIndex === -1 || endIndex === -1)
+        return false;
+    const updated = (current.slice(0, startIndex) + current.slice(endIndex + end.length)).replace(/\n{3,}/g, "\n\n");
+    if (updated === current)
+        return false;
+    fs.writeFileSync(filePath, updated, { mode: 0o600 });
+    return true;
+}
+function removeCompletionFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    fs.unlinkSync(filePath);
+    return true;
+}
 export function installCompletion(shell, options = {}) {
     const homeDir = options.homeDir ?? os.homedir();
     const platform = options.platform ?? process.platform;
@@ -433,3 +456,31 @@ export function installCompletion(shell, options = {}) {
     ]);
     return { shell, completionPath, profilePath, profileUpdated };
 }
+function uninstallShellCompletion(shell, homeDir, platform) {
+    const completionDir = path.join(homeDir, ".config", "agent-memory", "completions");
+    if (shell === "fish") {
+        const completionPath = path.join(homeDir, ".config", "fish", "completions", "agent-memory.fish");
+        return { shell, completionPath, removed: removeCompletionFile(completionPath), profileUpdated: false };
+    }
+    const extension = shell === "powershell" ? "ps1" : shell;
+    const completionPath = path.join(completionDir, `agent-memory.${extension}`);
+    const removed = removeCompletionFile(completionPath);
+    if (shell === "bash") {
+        const profilePath = path.join(homeDir, ".bashrc");
+        return { shell, completionPath, removed, profilePath, profileUpdated: removeProfileBlock(profilePath) };
+    }
+    if (shell === "zsh") {
+        const profilePath = path.join(homeDir, ".zshrc");
+        return { shell, completionPath, removed, profilePath, profileUpdated: removeProfileBlock(profilePath) };
+    }
+    const profilePath = platform === "win32"
+        ? path.join(homeDir, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1")
+        : path.join(homeDir, ".config", "powershell", "Microsoft.PowerShell_profile.ps1");
+    return { shell, completionPath, removed, profilePath, profileUpdated: removeProfileBlock(profilePath) };
+}
+/** Reverse of {@link installCompletion} across every supported shell. */
+export function uninstallCompletion(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const platform = options.platform ?? process.platform;
+    return ["bash", "zsh", "fish", "powershell"].map((shell) => uninstallShellCompletion(shell, homeDir, platform));
+}

package/dist/core.js

@@ -872,6 +872,17 @@ export function installSkills() {
             destDir: path.join(homeDir, ".cursor", "skills", "agent-memory"),
             homeMarker: path.join(homeDir, ".cursor"),
         },
+        {
+            label: "Qoder skill",
+            srcDir: path.join(skillsDir, "qoder"),
+            destDir: path.join(homeDir, ".qoder", "skills", "agent-memory"),
+            homeMarker: path.join(homeDir, ".qoder"),
+            detectFiles: [
+                path.join(homeDir, ".qoder", "settings.json"),
+                path.join(homeDir, ".qoder", "settings.local.json"),
+            ],
+            detectCommand: "qoder",
+        },
         {
             label: "Agent CLI skill",
             srcDir: path.join(skillsDir, "agent"),

package/dist/hooks.d.ts

@@ -1,7 +1,13 @@
+import { execFileSync } from "node:child_process";
 import { type HookMode } from "./core.js";
+type ExecFileSyncFn = typeof execFileSync;
+/** Override the execFileSync implementation used by hook installers (for testing). */
+export declare function _setHookExecForTest(fn: ExecFileSyncFn): void;
+/** Reset the execFileSync implementation to the real one. */
+export declare function _resetHookExecForTest(): void;
 /** Override the detected home directory in deterministic tests. */
 export declare function _setHookHomeDirForTest(directory: string | null): void;
-export type HookAgentKey = "claude" | "codex" | "cursor" | "opencode" | "pi";
+export type HookAgentKey = "claude" | "codex" | "cursor" | "opencode" | "pi" | "qoder";
 export interface HookTargetInfo {
     key: HookAgentKey;
     label: string;
@@ -52,6 +58,13 @@ export interface InstallHooksReport {
     results: HookInstallResult[];
     error?: string;
 }
+export interface PiMemoryState {
+    lastAttemptAt: string;
+    ok: boolean;
+    detail: string;
+}
+/** Read the last recorded `pi install npm:pi-memory` attempt, if any. Never throws. */
+export declare function getPiMemoryState(): PiMemoryState | null;
 export declare function installHooks(agents: Set<HookAgentKey>, mode?: HookMode): InstallHooksReport;
 export interface UninstallHooksReport {
     ok: boolean;
@@ -60,3 +73,4 @@ export interface UninstallHooksReport {
     error?: string;
 }
 export declare function uninstallHooks(agents?: Set<HookAgentKey>): UninstallHooksReport;
+export {};

package/dist/hooks.js

@@ -1,7 +1,17 @@
+import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { writeHookMode } from "./core.js";
+import { getMemoryDir, writeHookMode } from "./core.js";
+let execFileSyncFn = execFileSync;
+/** Override the execFileSync implementation used by hook installers (for testing). */
+export function _setHookExecForTest(fn) {
+    execFileSyncFn = fn;
+}
+/** Reset the execFileSync implementation to the real one. */
+export function _resetHookExecForTest() {
+    execFileSyncFn = execFileSync;
+}
 let homeDirOverride = null;
 /** Override the detected home directory in deterministic tests. */
 export function _setHookHomeDirForTest(directory) {
@@ -80,12 +90,22 @@ function hookTargets(homeDir) {
         },
         {
             key: "pi",
-            label: "pi",
+            label: "pi (via pi-memory)",
             homeMarker: path.join(homeDir, ".pi"),
             detectFiles: [],
             detectCommand: "pi",
-            supported: false,
-            unsupportedReason: "no documented SessionStart hook mechanism",
+            supported: true,
+        },
+        {
+            key: "qoder",
+            label: "Qoder",
+            homeMarker: path.join(homeDir, ".qoder"),
+            detectFiles: [
+                path.join(homeDir, ".qoder", "settings.json"),
+                path.join(homeDir, ".qoder", "settings.local.json"),
+            ],
+            detectCommand: "qoder",
+            supported: true,
         },
     ];
 }
@@ -143,6 +163,14 @@ export function isHookInstalled(homeDir, key) {
             const instructionsPath = path.join(homeDir, ".agent-memory", "hooks", "opencode.md");
             return list.includes(instructionsPath);
         }
+        if (key === "pi") {
+            // Live filesystem state is authoritative — pi-memory can be installed or
+            // removed outside agent-memory (manually, or via `pi uninstall`) at any
+            // time, so a recorded delegate attempt must never override what's
+            // actually on disk. The state file is diagnostic-only (surfaced
+            // separately in `doctor`'s detail text), not a substitute for this check.
+            return fs.existsSync(path.join(homeDir, ".pi", "agent", "memory"));
+        }
     }
     catch {
         return false;
@@ -232,6 +260,68 @@ function writeJson(filePath, data) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 }
+function piMemoryStatePath() {
+    return path.join(getMemoryDir(), "pi-memory-state.json");
+}
+function writePiMemoryState(ok, detail) {
+    try {
+        writeJson(piMemoryStatePath(), { lastAttemptAt: new Date().toISOString(), ok, detail });
+    }
+    catch {
+        // best-effort bookkeeping only — never block the actual install/uninstall result on this.
+    }
+}
+/** Read the last recorded `pi install npm:pi-memory` attempt, if any. Never throws. */
+export function getPiMemoryState() {
+    try {
+        const filePath = piMemoryStatePath();
+        if (!fs.existsSync(filePath))
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (typeof parsed?.lastAttemptAt !== "string" || typeof parsed?.ok !== "boolean")
+            return null;
+        return { lastAttemptAt: parsed.lastAttemptAt, ok: parsed.ok, detail: String(parsed.detail ?? "") };
+    }
+    catch {
+        return null;
+    }
+}
+function installPiMemoryDelegate(homeDir) {
+    const memoryPath = path.join(homeDir, ".pi", "agent", "memory");
+    try {
+        const stdout = execFileSyncFn("pi", ["install", "npm:pi-memory"], {
+            encoding: "utf-8",
+            timeout: 30_000,
+        });
+        const detail = typeof stdout === "string" ? stdout.trim() : "";
+        writePiMemoryState(true, detail);
+        return { key: "pi", label: "pi (via pi-memory)", installed: true, path: memoryPath, reason: detail || undefined };
+    }
+    catch (err) {
+        const detail = err && typeof err === "object" && "stderr" in err && err.stderr
+            ? String(err.stderr).trim()
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        writePiMemoryState(false, detail);
+        return { key: "pi", label: "pi (via pi-memory)", installed: false, reason: detail };
+    }
+}
+function uninstallPiMemoryDelegate(homeDir) {
+    // agent-memory never owns this install, so it never runs `pi uninstall pi-memory` — but
+    // silently doing nothing would let an `agent-memory uninstall` report read as "fully cleaned
+    // up" while pi-memory keeps running. Phrase the reason distinctly when it's actually still
+    // active so callers (and cmdUninstall's step detail) can surface that honestly.
+    const stillActive = fs.existsSync(path.join(homeDir, ".pi", "agent", "memory"));
+    return {
+        key: "pi",
+        label: "pi (via pi-memory)",
+        installed: false,
+        reason: stillActive
+            ? "pi-memory left installed (not managed by agent-memory) — run `pi uninstall pi-memory` to remove it"
+            : "not installed",
+    };
+}
 /**
  * Idempotently upsert the agent-memory-managed hook group for `eventKey`
  * (SessionStart or UserPromptSubmit) with `command`. Returns `{ changed,
@@ -524,6 +614,93 @@ function installOpencodeInstructions(homeDir) {
     writeJson(configPath, config);
     return { key: "opencode", label: "opencode", installed: true, path: configPath, backup };
 }
+function installQoderHook(homeDir) {
+    const settingsPath = path.join(homeDir, ".qoder", "settings.json");
+    const backup = backupOnce(settingsPath);
+    const settings = readJsonConfig(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+    const command = "agent-memory context";
+    let managed = 0;
+    let updated = 0;
+    for (const group of sessionStart) {
+        if (!group || typeof group !== "object")
+            continue;
+        const g = group;
+        const list = Array.isArray(g.hooks) ? g.hooks : [];
+        for (const hook of list) {
+            if (!hook || typeof hook !== "object")
+                continue;
+            const managedHook = hook;
+            if (managedHook[HOOK_MARKER_JSON] !== true)
+                continue;
+            managed++;
+            if (managedHook.command !== command) {
+                managedHook.command = command;
+                updated++;
+            }
+        }
+    }
+    if (managed && !updated) {
+        return { key: "qoder", label: "Qoder", installed: false, path: settingsPath, reason: "already installed" };
+    }
+    if (updated) {
+        hooks.SessionStart = sessionStart;
+        settings.hooks = hooks;
+        writeJson(settingsPath, settings);
+        return { key: "qoder", label: "Qoder", installed: true, path: settingsPath, backup, reason: "updated" };
+    }
+    sessionStart.push({
+        hooks: [{ type: "command", command, [HOOK_MARKER_JSON]: true }],
+    });
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
+    writeJson(settingsPath, settings);
+    return { key: "qoder", label: "Qoder", installed: true, path: settingsPath, backup };
+}
+function uninstallQoderHook(homeDir) {
+    const settingsPath = path.join(homeDir, ".qoder", "settings.json");
+    if (!fs.existsSync(settingsPath)) {
+        return { key: "qoder", label: "Qoder", installed: false, reason: "not installed" };
+    }
+    const settings = readJsonConfig(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const sessionStart = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    let removed = 0;
+    const filtered = sessionStart
+        .map((group) => {
+        if (!group || typeof group !== "object")
+            return group;
+        const g = { ...group };
+        const list = Array.isArray(g.hooks) ? g.hooks : [];
+        const kept = list.filter((h) => {
+            const isOurs = h && typeof h === "object" && h[HOOK_MARKER_JSON] === true;
+            if (isOurs)
+                removed++;
+            return !isOurs;
+        });
+        g.hooks = kept;
+        return g;
+    })
+        .filter((group) => {
+        if (!group || typeof group !== "object")
+            return true;
+        const g = group;
+        return Array.isArray(g.hooks) && g.hooks.length > 0;
+    });
+    if (removed === 0) {
+        return { key: "qoder", label: "Qoder", installed: false, reason: "not installed" };
+    }
+    hooks.SessionStart = filtered;
+    if (filtered.length === 0)
+        delete hooks.SessionStart;
+    if (Object.keys(hooks).length === 0)
+        delete settings.hooks;
+    else
+        settings.hooks = hooks;
+    writeJson(settingsPath, settings);
+    return { key: "qoder", label: "Qoder", installed: true, path: settingsPath };
+}
 export function installHooks(agents, mode = "per-turn") {
     const { homeDir, targets } = detectHookAgents();
     if (!homeDir) {
@@ -566,6 +743,10 @@ export function installHooks(agents, mode = "per-turn") {
                 result = installCursorHook(homeDir);
             else if (target.key === "opencode")
                 result = installOpencodeInstructions(homeDir);
+            else if (target.key === "pi")
+                result = installPiMemoryDelegate(homeDir);
+            else if (target.key === "qoder")
+                result = installQoderHook(homeDir);
             else
                 continue;
             results.push(result);
@@ -711,7 +892,7 @@ export function uninstallHooks(agents) {
             error: "Home directory not found. Set HOME (or USERPROFILE on Windows) and retry.",
         };
     }
-    const keys = ["claude", "codex", "cursor", "opencode"];
+    const keys = ["claude", "codex", "cursor", "opencode", "pi", "qoder"];
     const results = [];
     for (const key of keys) {
         if (agents && !agents.has(key))
@@ -725,6 +906,10 @@ export function uninstallHooks(agents) {
                 results.push(uninstallCursorHook(homeDir));
             else if (key === "opencode")
                 results.push(uninstallOpencodeInstructions(homeDir));
+            else if (key === "pi")
+                results.push(uninstallPiMemoryDelegate(homeDir));
+            else if (key === "qoder")
+                results.push(uninstallQoderHook(homeDir));
         }
         catch (err) {
             results.push({

package/dist/plugin-host.d.ts

@@ -147,6 +147,7 @@ export interface PluginMcpToolInputSchema {
 export interface PluginMcpToolV1 {
     name: string;
     description: string;
+    requiredCapability: string;
     inputSchema: PluginMcpToolInputSchema;
     run(input: Record<string, unknown>): unknown | Promise<unknown>;
 }

package/dist/plugin-runtime.d.ts

@@ -34,6 +34,15 @@ export declare class InstalledPluginRuntimeV1 {
         signal: AbortSignal;
     }): Promise<PluginContextSectionV1[]>;
     getMcpTools(): PluginMcpToolV1[];
+    /**
+     * Invoke a registered MCP tool by name, re-checking entitlement on every
+     * call — matching `run()`'s behavior for commands. MCP tools are
+     * registered once at `serve --mcp` startup and the server process can
+     * live for a long session, so a tool's entitlement must be re-verified
+     * per-call rather than trusted from registration time (e.g. a trial
+     * expiring mid-session must actually stop the tool from working).
+     */
+    runMcpTool(name: string, input: Record<string, unknown>): Promise<unknown>;
     runMcpStartup(): Promise<void>;
     private createHost;
     private refreshEntitlement;

package/dist/plugin-runtime.js

@@ -186,6 +186,25 @@ export class InstalledPluginRuntimeV1 {
     getMcpTools() {
         return [...this.mcpTools];
     }
+    /**
+     * Invoke a registered MCP tool by name, re-checking entitlement on every
+     * call — matching `run()`'s behavior for commands. MCP tools are
+     * registered once at `serve --mcp` startup and the server process can
+     * live for a long session, so a tool's entitlement must be re-verified
+     * per-call rather than trusted from registration time (e.g. a trial
+     * expiring mid-session must actually stop the tool from working).
+     */
+    async runMcpTool(name, input) {
+        if (!(await this.load()))
+            return { error: `Unknown MCP tool: ${name}` };
+        const tool = this.mcpTools.find((candidate) => candidate.name === name);
+        if (!tool)
+            return { error: `Unknown MCP tool: ${name}` };
+        const entitlement = await this.refreshEntitlement();
+        if (!isPluginCapabilityEnabled(entitlement, tool.requiredCapability))
+            return { error: `Capability ${tool.requiredCapability} is not enabled for the ${name} tool` };
+        return tool.run(input);
+    }
     async runMcpStartup() {
         for (const hook of this.mcpStartupHooks)
             await hook();
@@ -238,6 +257,8 @@ export class InstalledPluginRuntimeV1 {
                 this.contextProviders.push({ provider, pluginId: manifest.id });
             },
             registerMcpTool: (tool) => {
+                if (!(manifest.capabilities ?? []).includes(tool.requiredCapability))
+                    throw new PluginBootstrapFailure("plugin_mcp_tool_invalid", `Plugin ${manifest.id} registered an MCP tool with an undeclared capability`);
                 if (!tool.name || this.mcpTools.some((existing) => existing.name === tool.name))
                     throw new PluginBootstrapFailure("plugin_mcp_tool_invalid", `Plugin MCP tool ${tool.name || "(unnamed)"} is invalid or already registered`);
                 this.mcpTools.push(tool);

package/dist/plugin-service.js

@@ -402,14 +402,8 @@ export class AgentMemoryServiceBackend {
             value.entitlement.state !== "active" ||
             value.entitlement.capabilities.recall?.enabled !== true ||
             !recallQuota ||
-            recallQuota.limit !== 20 ||
-            recallQuota.scope !== "device" ||
-            recallQuota.window !== "day" ||
             value.entitlement.capabilities.learning?.enabled !== true ||
             !learningQuota ||
-            learningQuota.limit !== 5 ||
-            learningQuota.scope !== "device" ||
-            learningQuota.window !== "day" ||
             value.entitlement.capabilities["session-index"]?.enabled !== true ||
             value.entitlement.capabilities["session-worker"]?.enabled !== false ||
             value.entitlement.capabilities["web-console"]?.enabled !== true)

package/dist/upgrade.d.ts

@@ -1,12 +1,18 @@
 /**
  * Upgrade orchestration for the `agent-memory` CLI and its official Pro plugin bundle.
  *
- * Two consumers:
+ * Three consumers:
  *   1. `agent-memory upgrade` — explicit user command; checks and (optionally) installs.
- *   2. `agent-memory hook session-start` — passive notice from a 24h-cached record.
+ *   2. `agent-memory upgrade --background` — detached, non-interactive; checks, then
+ *      installs any target whose `readUpgradePolicy()` value is `"auto"` (the default).
+ *      Spawned by `refreshUpgradeCacheBackground()` from `hook session-start`.
+ *   3. `agent-memory hook session-start` — passive notice from a 24h-cached record,
+ *      including the outcome of the last `--background` auto-install attempt.
  *
  * Network calls always have a hard timeout and always fail closed (upgrade is a
- * quality-of-life feature; a flaky registry must never break the CLI).
+ * quality-of-life feature; a flaky registry must never break the CLI). Same fail-closed
+ * contract applies to auto-install: a failed background install is recorded, never
+ * retried before the next cache refresh, and never thrown.
  */
 import { type SpawnOptions } from "node:child_process";
 export type InstallManager = "bun" | "npm" | "pnpm" | "yarn" | "unknown";
@@ -24,6 +30,17 @@ export interface UpgradeCache {
     cliLatest: string | null;
     pluginCurrent: string | null;
     pluginLatest: string | null;
+    /** Outcome of the most recent `--background` auto-upgrade attempt, if any. */
+    cliAuto?: AutoUpgradeOutcome;
+    pluginAuto?: AutoUpgradeOutcome;
+}
+export interface AutoUpgradeOutcome {
+    at: string;
+    ok: boolean;
+    /** Version installed (ok) or the previous/current version (failure). */
+    version: string | null;
+    /** Failure reason; absent when ok. */
+    error?: string;
 }
 export interface UpgradeStatus {
     cli: {
@@ -42,6 +59,24 @@ export interface UpgradeStatus {
 export declare function readUpgradeCache(): UpgradeCache | null;
 export declare function writeUpgradeCache(record: UpgradeCache): void;
 export declare function isCacheFresh(record: UpgradeCache | null, now?: number): boolean;
+export type UpgradePolicyValue = "off" | "notify" | "auto";
+export interface UpgradePolicy {
+    cli: UpgradePolicyValue;
+    plugin: UpgradePolicyValue;
+}
+/**
+ * Resolve the persisted auto-upgrade policy.
+ * Precedence per target: `AGENT_MEMORY_AUTO_UPGRADE_{CLI,PLUGIN}` env var →
+ * `<memoryDir>/state/upgrade-policy.json` → default `"auto"`.
+ *
+ * `existed` tells callers whether the policy file was already on disk —
+ * used to fire a one-time "auto-upgrade is on" notice on first read.
+ */
+export declare function readUpgradePolicy(): UpgradePolicy & {
+    existed: boolean;
+};
+/** Atomically persist the auto-upgrade policy. Merges with whatever is already on disk. */
+export declare function writeUpgradePolicy(patch: Partial<UpgradePolicy>): UpgradePolicy;
 /**
  * Best-effort detection of how `myagentmemory` was installed. Path signatures
  * are heuristic but cover the common managers. On no match we fall back to
@@ -58,8 +93,10 @@ export interface InstallResult {
 export declare function runInstaller(method: InstallMethod, opts?: SpawnOptions): InstallResult;
 /**
  * Fire-and-forget: spawn a detached child that runs `agent-memory upgrade
- * --check --refresh --quiet` so the next session-start has a fresh cache.
- * Never awaits, never throws.
+ * --background --refresh --quiet` so the next session-start has a fresh
+ * cache. Unlike a plain check, `--background` also installs any target whose
+ * policy is `"auto"` (see `readUpgradePolicy`) — this is the one place
+ * auto-upgrade actually happens. Never awaits, never throws.
  */
 export declare function refreshUpgradeCacheBackground(): void;
 export interface CheckOptions {
@@ -77,4 +114,12 @@ export interface CheckOptions {
     pluginUpgradeAvailable?: boolean;
 }
 export declare function checkForUpgrades(opts: CheckOptions): Promise<UpgradeStatus>;
-export declare function formatUpgradeNotice(status: UpgradeStatus): string | null;
+/**
+ * `cache` (when passed) lets this distinguish a plain "notify" signal from the
+ * outcome of the last `--background` auto-install attempt for that target:
+ *   - succeeded, but this process is running older code than what's on disk
+ *     (e.g. a long-running `serve --mcp`) → "auto-upgraded, restart to use it"
+ *   - failed → surface the error and point at the manual command
+ *   - succeeded and already caught up (this process's own version matches) → silent
+ */
+export declare function formatUpgradeNotice(status: UpgradeStatus, cache?: UpgradeCache | null): string | null;