minutes-mcp 0.13.2 → 0.14.0

package/dist/capabilities.d.ts

@@ -0,0 +1,74 @@
+/**
+ * CLI capabilities feature-detection probe.
+ *
+ * Phase 2 of #183: instead of guessing which MCP tools to expose based on
+ * version strings, ask the CLI directly via `minutes capabilities --json`.
+ * Tools whose backing CLI subcommand the report confirms get registered;
+ * tools whose subcommand is missing (or whose feature key is absent, or
+ * whose probe failed entirely) are hidden from the MCP tool list.
+ *
+ * The probe is synchronous so tool registration at module load can consult
+ * it. If the CLI is missing, older, or crashes, the probe returns `null`
+ * and `hasFeature(null, ...)` returns `false` — fail-closed. For the
+ * specific features this module gates (new in 0.14.0), that matches
+ * ground truth: a CLI too old to respond to `capabilities` is also too
+ * old to have the backing subcommand, so hiding the tool is correct.
+ *
+ * The alternative (fail-open) was rejected because it produced tools that
+ * fail at call time with "unknown subcommand" errors on older CLIs — the
+ * exact UX problem #183 Phase 2 is meant to eliminate.
+ */
+export type CapabilityReport = {
+    /** Semver of the CLI, e.g. "0.14.0". */
+    version: string;
+    /** Wire-contract version. Bumps only on breaking changes. */
+    api_version: number;
+    /** Feature name to whether the CLI supports it. */
+    features: Record<string, boolean>;
+};
+/**
+ * Probe the installed CLI for its capability report. Synchronous so it
+ * runs before tool registrations at module load.
+ *
+ * Returns `null` if:
+ * - the binary does not exist on PATH or at the resolved path,
+ * - the CLI is too old to have a `capabilities` subcommand,
+ * - the output is not valid JSON,
+ * - the output does not match the expected shape.
+ *
+ * A `null` return is a soft signal meaning "proceed optimistically"; the
+ * caller should register all tools as if every feature is supported.
+ */
+export declare function probeCapabilitiesSync(binPath: string, options?: {
+    timeoutMs?: number;
+}): CapabilityReport | null;
+/**
+ * The newest wire-contract version this MCP server understands. A report
+ * whose `api_version` exceeds this value is rejected (treated as null by
+ * the caller) so a future breaking CLI schema cannot be silently trusted
+ * by an older MCP.
+ *
+ * Add a new compatibility branch here, don't just bump this number, when
+ * the CLI schema changes in a non-additive way.
+ */
+export declare const MAX_SUPPORTED_API_VERSION = 1;
+/**
+ * Parse a capability report JSON payload with shape validation.
+ *
+ * Exposed separately from the probe so unit tests can exercise the
+ * parser without spawning a subprocess.
+ */
+export declare function parseCapabilityReport(raw: string): CapabilityReport | null;
+/**
+ * Decide whether to expose a feature-gated MCP tool.
+ *
+ * Fail-closed contract:
+ * - `report === null`: probe failed or CLI is old/missing. Return `false`.
+ *   The gated tool is hidden. For the Phase 2 gate set (features new in
+ *   the same CLI release that introduced the `capabilities` subcommand),
+ *   this matches ground truth: an old CLI is missing both the probe and
+ *   the backing subcommand.
+ * - `report !== null` and feature key is present and `true`: Return `true`.
+ * - `report !== null` and feature key is `false` or missing: Return `false`.
+ */
+export declare function hasFeature(report: CapabilityReport | null, name: string): boolean;

package/dist/capabilities.js

@@ -0,0 +1,131 @@
+/**
+ * CLI capabilities feature-detection probe.
+ *
+ * Phase 2 of #183: instead of guessing which MCP tools to expose based on
+ * version strings, ask the CLI directly via `minutes capabilities --json`.
+ * Tools whose backing CLI subcommand the report confirms get registered;
+ * tools whose subcommand is missing (or whose feature key is absent, or
+ * whose probe failed entirely) are hidden from the MCP tool list.
+ *
+ * The probe is synchronous so tool registration at module load can consult
+ * it. If the CLI is missing, older, or crashes, the probe returns `null`
+ * and `hasFeature(null, ...)` returns `false` — fail-closed. For the
+ * specific features this module gates (new in 0.14.0), that matches
+ * ground truth: a CLI too old to respond to `capabilities` is also too
+ * old to have the backing subcommand, so hiding the tool is correct.
+ *
+ * The alternative (fail-open) was rejected because it produced tools that
+ * fail at call time with "unknown subcommand" errors on older CLIs — the
+ * exact UX problem #183 Phase 2 is meant to eliminate.
+ */
+import { execFileSync } from "child_process";
+/**
+ * Probe the installed CLI for its capability report. Synchronous so it
+ * runs before tool registrations at module load.
+ *
+ * Returns `null` if:
+ * - the binary does not exist on PATH or at the resolved path,
+ * - the CLI is too old to have a `capabilities` subcommand,
+ * - the output is not valid JSON,
+ * - the output does not match the expected shape.
+ *
+ * A `null` return is a soft signal meaning "proceed optimistically"; the
+ * caller should register all tools as if every feature is supported.
+ */
+export function probeCapabilitiesSync(binPath, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 2000;
+    let stdout;
+    try {
+        stdout = execFileSync(binPath, ["capabilities", "--json"], {
+            timeout: timeoutMs,
+            encoding: "utf-8",
+            // Silence stderr so the MCP console stays quiet when the CLI is
+            // old (and prints an unknown-subcommand error to stderr).
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return null;
+    }
+    return parseCapabilityReport(stdout);
+}
+/**
+ * The newest wire-contract version this MCP server understands. A report
+ * whose `api_version` exceeds this value is rejected (treated as null by
+ * the caller) so a future breaking CLI schema cannot be silently trusted
+ * by an older MCP.
+ *
+ * Add a new compatibility branch here, don't just bump this number, when
+ * the CLI schema changes in a non-additive way.
+ */
+export const MAX_SUPPORTED_API_VERSION = 1;
+/**
+ * Parse a capability report JSON payload with shape validation.
+ *
+ * Exposed separately from the probe so unit tests can exercise the
+ * parser without spawning a subprocess.
+ */
+export function parseCapabilityReport(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    // Object.create(null) would be ideal for the target map; we guard
+    // against `__proto__`/`constructor`/`prototype` pollution below.
+    const obj = parsed;
+    if (typeof obj.version !== "string")
+        return null;
+    if (typeof obj.api_version !== "number")
+        return null;
+    // Reject reports from a future CLI with a wire contract we do not
+    // understand. Treating this as null triggers the fail-closed path so
+    // no tools get silently enabled based on a schema we cannot verify.
+    if (!Number.isInteger(obj.api_version) ||
+        obj.api_version < 1 ||
+        obj.api_version > MAX_SUPPORTED_API_VERSION) {
+        return null;
+    }
+    if (!obj.features || typeof obj.features !== "object")
+        return null;
+    // Coerce feature map values to booleans; drop non-boolean entries so
+    // a misformed payload never accidentally enables a tool. Use a
+    // null-prototype object so polluted keys (__proto__, constructor,
+    // prototype) cannot reach anything via the prototype chain.
+    const rawFeatures = obj.features;
+    const features = Object.create(null);
+    for (const [name, value] of Object.entries(rawFeatures)) {
+        if (name === "__proto__" || name === "constructor" || name === "prototype") {
+            continue;
+        }
+        if (typeof value === "boolean") {
+            features[name] = value;
+        }
+    }
+    return {
+        version: obj.version,
+        api_version: obj.api_version,
+        features,
+    };
+}
+/**
+ * Decide whether to expose a feature-gated MCP tool.
+ *
+ * Fail-closed contract:
+ * - `report === null`: probe failed or CLI is old/missing. Return `false`.
+ *   The gated tool is hidden. For the Phase 2 gate set (features new in
+ *   the same CLI release that introduced the `capabilities` subcommand),
+ *   this matches ground truth: an old CLI is missing both the probe and
+ *   the backing subcommand.
+ * - `report !== null` and feature key is present and `true`: Return `true`.
+ * - `report !== null` and feature key is `false` or missing: Return `false`.
+ */
+export function hasFeature(report, name) {
+    if (report === null)
+        return false;
+    return report.features[name] === true;
+}

package/dist/index.d.ts

@@ -11,6 +11,9 @@
  *   - get_meeting: Get full transcript of a specific meeting
  *   - process_audio: Process an audio file through the pipeline
  *   - add_note: Add a timestamped note to a recording or meeting
+ *   - activity_summary: Summarize meeting-adjacent desktop context for a session/path/window
+ *   - search_context: Search app and captured window-title desktop context
+ *   - get_moment: Show the local rewind around a linked artifact, session, or timestamp
  *   - consistency_report: Flag conflicting decisions and stale commitments
  *   - get_person_profile: Rich relationship profile for a person (graph index)
  *   - track_commitments: List open/stale commitments, filter by person
@@ -32,4 +35,5 @@ export type KnowledgeConfigStatus = {
     adapter: string;
     engine: string;
 };
+export declare function shouldRunMainEntry(argv1: string | null | undefined, moduleFilename: string): boolean;
 export declare function parseKnowledgeConfig(configContent: string): KnowledgeConfigStatus | null;

package/dist/index.js

@@ -11,6 +11,9 @@
  *   - get_meeting: Get full transcript of a specific meeting
  *   - process_audio: Process an audio file through the pipeline
  *   - add_note: Add a timestamped note to a recording or meeting
+ *   - activity_summary: Summarize meeting-adjacent desktop context for a session/path/window
+ *   - search_context: Search app and captured window-title desktop context
+ *   - get_moment: Show the local rewind around a linked artifact, session, or timestamp
  *   - consistency_report: Flag conflicting decisions and stale commitments
  *   - get_person_profile: Rich relationship profile for a person (graph index)
  *   - track_commitments: List open/stale commitments, filter by person
@@ -37,14 +40,83 @@ import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, EXTENSION_ID,
 import { z } from "zod";
 import { execFile, spawn } from "child_process";
 import { promisify } from "util";
-import { existsSync } from "fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from "fs";
 import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import { delimiter, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import * as reader from "minutes-sdk";
 import { canonicalizeRoot, expandHomeLikePath, validatePathInDirectories, validatePathInDirectory, } from "./paths.js";
+import { isCliCompatible } from "./version.js";
+import { hasFeature, probeCapabilitiesSync, } from "./capabilities.js";
 crashTrace("imports-complete");
+// ── Demo mode (--demo flag) ────────────────────────────────
+// `npx minutes-mcp --demo` is a one-shot setup: copies bundled fixture
+// meetings to ~/.minutes/demo/, prints the MCP config snippet with an explicit
+// MEETINGS_DIR env override, prints suggested questions, and exits 0.
+//
+// The printed config uses env:{ MEETINGS_DIR } pointing at the demo dir. No
+// separate --demo flag at runtime. The MCP host just launches standard
+// `minutes-mcp`; the env override is what routes it at the demo corpus. This
+// avoids the TTY-detection ambiguity that an earlier dual-mode design had.
+//
+// Guarded on `--demo` AND on being the actual entry point so importers don't
+// trigger disk side effects by mistake. Use the same realpath-aware guard as
+// `main()` so npm/.bin shims and symlinked entrypoints still execute demo mode.
+if (process.argv.includes("--demo") && shouldRunMainEntry(process.argv[1], fileURLToPath(import.meta.url))) {
+    handleDemoSetup();
+}
+function handleDemoSetup() {
+    const demoDir = join(homedir(), ".minutes", "demo");
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Package layout after build: dist/index.js; fixtures live at
+    // <pkg>/fixtures/demo/ next to dist/.
+    const fixturesSrc = resolve(here, "..", "fixtures", "demo");
+    if (!existsSync(fixturesSrc)) {
+        console.error(`[minutes-mcp --demo] bundled fixtures not found at ${fixturesSrc}. ` +
+            `This build of minutes-mcp is missing the demo corpus. ` +
+            `Try upgrading with: npm install -g minutes-mcp@latest`);
+        process.exit(1);
+    }
+    mkdirSync(demoDir, { recursive: true });
+    for (const entry of readdirSync(fixturesSrc)) {
+        if (!entry.endsWith(".md"))
+            continue;
+        copyFileSync(join(fixturesSrc, entry), join(demoDir, entry));
+    }
+    // The config snippet embeds the fully-resolved demoDir so users don't have
+    // to fill it in manually. MCP hosts inject this env when launching the
+    // server; the server's existing MEETINGS_DIR logic (line ~800) picks it up.
+    const configSnippet = JSON.stringify({
+        mcpServers: {
+            "minutes-demo": {
+                command: "npx",
+                args: ["minutes-mcp"],
+                env: {
+                    MEETINGS_DIR: demoDir,
+                },
+            },
+        },
+    }, null, 2);
+    console.log("");
+    console.log("Demo corpus ready at: " + demoDir);
+    console.log("5 fixture meetings with a pricing reversal, a customer commitment that slips, and a feature cut.");
+    console.log("");
+    console.log("═══ MCP config (paste into Claude Desktop, Cursor, Claude Code, or any MCP client) ═══");
+    console.log(configSnippet);
+    console.log("");
+    console.log("═══ Try asking your agent ═══");
+    console.log("  • List the meetings in this corpus.");
+    console.log("  • What did we decide about pricing? Which decision is current?");
+    console.log("  • What got killed in the last product prioritization meeting?");
+    console.log("  • What action items are still open, and who owns each?");
+    console.log("  • Summarize the Northwind customer thread.");
+    console.log("");
+    console.log("Note: some structured tools (consistency report, person profile) auto-install the Minutes CLI on first use.");
+    console.log("Full setup (real audio capture, transcription, real meetings): https://useminutes.app");
+    console.log("");
+    process.exit(0);
+}
 const UI_RESOURCE_URI = "ui://minutes/dashboard";
 const MCP_TOOLS_DOCS_BASE_URL = "https://useminutes.app/docs/mcp/tools";
 export const MEETING_INSIGHT_KINDS = ["decision", "commitment", "question"];
@@ -146,6 +218,22 @@ async function triggerQmdIndex() {
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+function canonicalEntrypointPath(filePath) {
+    if (!filePath)
+        return null;
+    const resolved = resolve(filePath);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+export function shouldRunMainEntry(argv1, moduleFilename) {
+    const entryPath = canonicalEntrypointPath(argv1);
+    const modulePath = canonicalEntrypointPath(moduleFilename);
+    return !!entryPath && !!modulePath && entryPath === modulePath;
+}
 // ── Extension runtime detection ───────────────────────────────
 // When running as a Claude Desktop extension (.mcpb), Claude uses its built-in
 // Node.js runtime.  Child processes spawned from that runtime land in a
@@ -198,9 +286,31 @@ function findMinutesBinary() {
     return "minutes";
 }
 let MINUTES_BIN = findMinutesBinary();
-// ── Expected CLI version (must match this MCP server release) ──
-const MCP_SERVER_VERSION = "0.13.2";
-const EXPECTED_CLI_VERSION = MCP_SERVER_VERSION;
+// ── Capability probe (Phase 2 of #183) ────────────────────────
+// Ask the CLI what it supports instead of inferring from version strings.
+// Synchronous so it can run before tool registrations at module load.
+// A `null` report means we could not probe (missing or old CLI): the
+// `hasFeature` helper treats that as "optimistic yes" so we preserve
+// backward compatibility with pre-0.14.0 CLIs that have no `capabilities`
+// subcommand.
+const CLI_CAPABILITIES = probeCapabilitiesSync(MINUTES_BIN);
+if (CLI_CAPABILITIES) {
+    crashTrace("cli-capabilities-probed", {
+        cliVersion: CLI_CAPABILITIES.version,
+        apiVersion: CLI_CAPABILITIES.api_version,
+        featureCount: Object.keys(CLI_CAPABILITIES.features).length,
+    });
+}
+else {
+    crashTrace("cli-capabilities-unknown");
+}
+// ── MCP server version ────────────────────────────────────────
+// Kept for capabilities handshake and user-facing log messages.
+// The compatibility decision against the installed CLI lives in
+// `./version.ts` (see issue #183). Hosted `.mcpb` bundles will run
+// against CLIs with different minor/patch numbers within the same
+// major; that is explicitly supported.
+const MCP_SERVER_VERSION = "0.14.0";
 export function parseKnowledgeConfig(configContent) {
     const knowledgeMatch = configContent.match(/\[knowledge\][\s\S]*?(?=\n\[|$)/);
     if (!knowledgeMatch) {
@@ -218,8 +328,10 @@ export function parseKnowledgeConfig(configContent) {
         engine: engineMatch?.[1] || "none",
     };
 }
-const RELEASE_TAG = `v${EXPECTED_CLI_VERSION}`;
 // ── CLI auto-install ────────────────────────────────────────
+// Auto-install fetches from the GitHub `releases/latest/download/` redirect,
+// not a pinned tag, so hosted `.mcpb` bundles self-heal across our release
+// cadence. See issue #183 for context.
 // When installed via MCPB or `npx minutes-mcp`, the Rust CLI binary
 // may not be present. We attempt to install it automatically so
 // non-technical users don't hit a "binary not found" dead end.
@@ -253,12 +365,12 @@ async function tryAutoInstall() {
     const binaryName = getReleaseBinaryName();
     if (binaryName) {
         try {
-            const url = `https://github.com/silverstein/minutes/releases/download/${RELEASE_TAG}/${binaryName}`;
+            const url = `https://github.com/silverstein/minutes/releases/latest/download/${binaryName}`;
             const installDir = getInstallDir();
             const isWindows = process.platform === "win32";
             const targetName = isWindows ? "minutes.exe" : "minutes";
             const targetPath = join(installDir, targetName);
-            console.error(`[Minutes] Downloading ${binaryName} from ${RELEASE_TAG} release...`);
+            console.error(`[Minutes] Downloading ${binaryName} from latest release...`);
             // Ensure install directory exists
             await execFileAsync("mkdir", ["-p", installDir], { timeout: 5000 }).catch(() => { });
             // Download with curl (available on macOS, Linux, and modern Windows)
@@ -310,21 +422,26 @@ async function tryAutoInstall() {
 async function checkCliVersion() {
     try {
         const { stdout } = await execFileAsync(MINUTES_BIN, ["--version"], { timeout: 5000, env: augmentedEnv() });
-        // Output is like "minutes 0.8.0" or just "0.8.0"
+        // Output is like "minutes 0.8.0" or just "0.8.0".
         const match = stdout.trim().match(/(\d+\.\d+\.\d+)/);
-        if (match) {
-            const installedVersion = match[1];
-            if (installedVersion !== EXPECTED_CLI_VERSION) {
-                console.error(`[Minutes] ⚠ CLI version mismatch: installed ${installedVersion}, server expects ${EXPECTED_CLI_VERSION}. ` +
-                    `Update with: brew upgrade minutes (or cargo install minutes-cli)`);
-            }
-            else {
-                console.error(`[Minutes] CLI v${installedVersion} — up to date`);
-            }
+        if (!match)
+            return;
+        const installedVersion = match[1];
+        const result = isCliCompatible(installedVersion, MCP_SERVER_VERSION);
+        // Only surface logs the user should see. Same-major skew is silent-
+        // compatible, which is the whole point of issue #183 fix: hosted `.mcpb`
+        // bundles frequently run against a CLI with a different minor/patch
+        // and that is fine.
+        if (result.severity === "error") {
+            console.error(`[Minutes] ${result.message}`);
         }
+        else if (result.severity === "ok") {
+            console.error(`[Minutes] ${result.message}`);
+        }
+        // "info" severity (compatible skew, unparseable version) stays silent.
     }
     catch {
-        // Version check is best-effort — don't block on failure
+        // Version check is best-effort. Don't block on failure.
     }
 }
 // ── Auto-setup: download whisper model if missing ───────────
@@ -1086,6 +1203,129 @@ registerDocsAppTool(server, "search_meetings", {
         _meta: { ui: { resourceUri: UI_RESOURCE_URI }, view: "dashboard" },
     };
 });
+// ── Tool: activity_summary ──────────────────────────────────
+// Feature-gated (#183 phase 2). Hidden when the CLI does not report
+// activity_summary in its capability probe. On an older CLI that has no
+// `capabilities` subcommand, the probe returns null and `hasFeature`
+// resolves to true, so the tool is still exposed and any runtime call
+// surfaces a clear CLI error rather than silently disappearing.
+if (hasFeature(CLI_CAPABILITIES, "activity_summary"))
+    registerDocsAppTool(server, "activity_summary", {
+        description: "Summarize meeting-adjacent desktop context for a linked artifact, context session, or explicit time window.",
+        inputSchema: {
+            session_id: z.string().optional().describe("Explicit desktop-context session id"),
+            path: z.string().optional().describe("Linked artifact path, such as a meeting markdown file or live transcript JSONL"),
+            start: z.string().optional().describe("Window start (RFC3339); use with end when no session/path is provided"),
+            end: z.string().optional().describe("Window end (RFC3339); use with start when no session/path is provided"),
+        },
+        annotations: { title: "Activity Summary", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        _meta: { ui: { resourceUri: UI_RESOURCE_URI } },
+    }, async ({ session_id, path, start, end }) => {
+        if (!(await isCliAvailable())) {
+            return { content: [{ type: "text", text: `Desktop-context summaries require the full CLI.\n\n${CLI_INSTALL_MSG}` }] };
+        }
+        const args = ["context", "activity-summary", "--json"];
+        if (session_id)
+            args.push("--session", session_id);
+        if (path)
+            args.push("--path", path);
+        if (start)
+            args.push("--start", start);
+        if (end)
+            args.push("--end", end);
+        const { stdout, stderr } = await runMinutes(args);
+        const parsed = parseJsonOutput(stdout);
+        if (!parsed || typeof parsed !== "object") {
+            return { content: [{ type: "text", text: stderr || stdout }] };
+        }
+        const apps = Array.isArray(parsed.top_apps) ? parsed.top_apps : [];
+        const windows = Array.isArray(parsed.top_windows) ? parsed.top_windows : [];
+        const events = Array.isArray(parsed.events) ? parsed.events : [];
+        const lines = [
+            `Desktop context summary: ${parsed.window?.start || "?"} -> ${parsed.window?.end || "?"}`,
+            apps.length ? `Top apps: ${apps.map((entry) => `${entry.name} (${entry.count})`).join(", ")}` : "",
+            windows.length ? `Top windows: ${windows.map((entry) => `${entry.name} (${entry.count})`).join(", ")}` : "",
+            events.length ? `Events: ${events.length}` : "Events: 0",
+        ].filter(Boolean);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: { ...parsed, kind: "activity_summary", view: "context" },
+            _meta: { ui: { resourceUri: UI_RESOURCE_URI }, view: "context", kind: "activity_summary" },
+        };
+    });
+// ── Tool: search_context ────────────────────────────────────
+// Feature-gated (#183 phase 2). See activity_summary comment above.
+if (hasFeature(CLI_CAPABILITIES, "search_context"))
+    registerDocsAppTool(server, "search_context", {
+        description: "Search desktop-context events across app focus and captured window titles, including opted-in browser titles.",
+        inputSchema: {
+            query: z.string().describe("Text query for app names, bundle ids, or captured window titles"),
+            limit: z.number().optional().default(20).describe("Maximum results"),
+        },
+        annotations: { title: "Search Context", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        _meta: { ui: { resourceUri: UI_RESOURCE_URI } },
+    }, async ({ query, limit }) => {
+        if (!(await isCliAvailable())) {
+            return { content: [{ type: "text", text: `Desktop-context search requires the full CLI.\n\n${CLI_INSTALL_MSG}` }] };
+        }
+        const { stdout, stderr } = await runMinutes(["context", "search", query, "--limit", String(limit), "--json"]);
+        const parsed = parseJsonOutput(stdout);
+        if (!parsed || typeof parsed !== "object") {
+            return { content: [{ type: "text", text: stderr || stdout }] };
+        }
+        const results = Array.isArray(parsed.results) ? parsed.results : [];
+        const text = results.length === 0
+            ? `No desktop-context events found for "${query}".`
+            : results
+                .map((event) => `${event.observed_at} — ${event.app_name || event.bundle_id || "unknown"}${event.window_title ? ` :: ${event.window_title}` : ""}`)
+                .join("\n");
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { query, results, view: "context", kind: "search_context" },
+            _meta: { ui: { resourceUri: UI_RESOURCE_URI }, view: "context", kind: "search_context" },
+        };
+    });
+// ── Tool: get_moment ────────────────────────────────────────
+// Feature-gated (#183 phase 2). See activity_summary comment above.
+if (hasFeature(CLI_CAPABILITIES, "get_moment"))
+    registerDocsAppTool(server, "get_moment", {
+        description: "Show the local rewind around a linked artifact, context session, or explicit timestamp.",
+        inputSchema: {
+            session_id: z.string().optional().describe("Explicit desktop-context session id"),
+            path: z.string().optional().describe("Linked artifact path, such as a meeting markdown file or live transcript JSONL"),
+            at: z.string().optional().describe("Explicit anchor timestamp (RFC3339)"),
+            before_minutes: z.number().optional().default(10).describe("Minutes before the anchor"),
+            after_minutes: z.number().optional().default(10).describe("Minutes after the anchor"),
+        },
+        annotations: { title: "Get Moment", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        _meta: { ui: { resourceUri: UI_RESOURCE_URI } },
+    }, async ({ session_id, path, at, before_minutes, after_minutes }) => {
+        if (!(await isCliAvailable())) {
+            return { content: [{ type: "text", text: `Desktop-context rewind requires the full CLI.\n\n${CLI_INSTALL_MSG}` }] };
+        }
+        const args = ["context", "get-moment", "--json", "--before-minutes", String(before_minutes), "--after-minutes", String(after_minutes)];
+        if (session_id)
+            args.push("--session", session_id);
+        if (path)
+            args.push("--path", path);
+        if (at)
+            args.push("--at", at);
+        const { stdout, stderr } = await runMinutes(args);
+        const parsed = parseJsonOutput(stdout);
+        if (!parsed || typeof parsed !== "object") {
+            return { content: [{ type: "text", text: stderr || stdout }] };
+        }
+        const events = Array.isArray(parsed.events) ? parsed.events : [];
+        const text = [
+            `Moment window: ${parsed.window?.start || "?"} -> ${parsed.window?.end || "?"}`,
+            ...events.map((event) => `${event.observed_at} — ${event.app_name || event.bundle_id || "unknown"}${event.window_title ? ` :: ${event.window_title}` : ""}`),
+        ].join("\n");
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { ...parsed, view: "context", kind: "get_moment" },
+            _meta: { ui: { resourceUri: UI_RESOURCE_URI }, view: "context", kind: "get_moment" },
+        };
+    });
 // ── Tool: consistency_report ───────────────────────────────
 registerDocsAppTool(server, "consistency_report", {
     description: "Flag conflicting decisions and stale commitments across meetings using structured intent data.",
@@ -2134,9 +2374,9 @@ crashTrace("pre-main-guard", {
     argv1: process.argv[1] ?? null,
     resolvedArgv1: process.argv[1] ? resolve(process.argv[1]) : null,
     __filename,
-    match: process.argv[1] ? resolve(process.argv[1]) === __filename : false,
+    match: shouldRunMainEntry(process.argv[1], __filename),
 });
-if (process.argv[1] && resolve(process.argv[1]) === __filename) {
+if (shouldRunMainEntry(process.argv[1], __filename)) {
     main().catch((error) => {
         crashTrace("main-rejected", error);
         console.error("Fatal error:", error);

package/dist/version.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI/MCP version compatibility.
+ *
+ * Replaces the historical strict-equality check with same-major semver
+ * compatibility. See issue #183 for the rationale: hosted `.mcpb` bundles
+ * ship a frozen MCP server version, while users' CLI versions advance
+ * independently via brew/cargo/auto-install. Strict equality turned every
+ * version skew into scary user-facing warnings and broke auto-install when
+ * the pinned GitHub release tag no longer matched.
+ */
+export type VersionParts = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export type CompatibilitySeverity = "ok" | "info" | "error";
+export type CompatibilityResult = {
+    ok: boolean;
+    severity: CompatibilitySeverity;
+    message: string;
+};
+export declare function parseVersion(raw: string): VersionParts | null;
+/**
+ * Decide whether a CLI version is compatible with the running MCP server.
+ *
+ * Rules (Phase 1 of #183):
+ * - Unparseable version string: proceed, log informationally. Old CLIs may
+ *   not emit a parseable `--version` but usually still work.
+ * - Major-version mismatch: not compatible. Emit one clear error with an
+ *   upgrade command.
+ * - Same major, same version: ok, one-line info log.
+ * - Same major, different minor/patch: ok. Older CLI with newer MCP, or
+ *   vice-versa, is backward-compatible within a major per our contract.
+ */
+export declare function isCliCompatible(cliVersion: string, serverVersion: string): CompatibilityResult;