@askthew/mcp-plugin 0.4.8 → 0.4.9

package/dist/cli.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { createAskTheWMcpServer } from "./index.js";
+import { createAskTheWMcpServer, runInitializeHandshake } from "./index.js";
 import { askTheWDataDir, ensureAskTheWDataDir, identityPath } from "./lib/paths.js";
 import { loadCliCredentials } from "./lib/free-tier-policy.js";
 import { describeFreeIdentity, tryRegisterFreeInstall } from "./lib/free-install-registration.js";
@@ -13,17 +13,21 @@ import { LocalStore } from "./lib/local-store.js";
 import { buildTelemetryPayload } from "./lib/telemetry.js";
 import { syncDryRun, uploadLocalStore } from "./lib/upgrade-sync.js";
 import { installPreCommitHook, localScopeKey, preCommitDecisionGap, stagedFiles, writeWeeklyDigest, } from "./lib/cli-actions.js";
-import { createHostConfigSnippet, findInstallReceipts, formatInstallCommand, installBehaviorInstructions, installHostConfig, removeInstallReceipts, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, writeInstallReceipt, } from "./install.js";
+import { createHostConfigSnippet, defaultServerNameForTier, findInstallReceipts, formatInstallCommand, installBehaviorInstructions, installHostConfig, packageVersion, removeInstallReceipts, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, upgradePinnedHostConfig, writeInstallReceipt, } from "./install.js";
 function usage() {
     return [
         "Ask The W Coding Agent Connector",
         "",
         "Usage:",
-        "  askthew-mcp",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> --server-name <name> [--client-id <id>] [--client-label <label>] [--server-entrypoint <path>] [--dry-run] [--no-agent-instructions]",
-        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>]",
+        "  askthew-mcp [stdio MCP server when stdin is piped]",
+        "  askthew-mcp --version",
+        "  askthew-mcp doctor [--server-entrypoint <path>]",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --token <install-token> --api-url <url> [--server-name <name>] [--client-id <id>] [--client-label <label>] [--server-entrypoint <path>] [--dry-run] [--no-agent-instructions]",
+        "  askthew-mcp install --host <claude_code|codex|cursor> --free [--email <email>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>] [--dry-run]",
         "  askthew-mcp refresh --host <claude_code|codex|cursor> [--free] [--token <install-token>] [--api-url <url>] [--server-name <name>] [--server-entrypoint <path>] [--dry-run]",
         "  askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>] [--dry-run] [--keep-local-data] [--keep-auth] [--keep-agent-instructions]",
+        "  askthew-mcp upgrade --host <claude_code|codex|cursor> [--server-name <name>] [--version <version>] [--dry-run]",
+        "  askthew-mcp upgrade --browser",
         "  askthew-mcp identify --email <email> [--no-telemetry]",
         "  askthew-mcp identity status",
         "  askthew-mcp auth login --email <email> [--no-telemetry]",
@@ -43,6 +47,7 @@ function parseInstallArgs(argv) {
     let token = normalizeInstallToken(process.env.ASKTHEW_INSTALL_TOKEN) || "";
     let apiUrl = process.env.ASKTHEW_API_URL?.trim() || "";
     let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "";
+    let serverNameExplicit = Boolean(serverName);
     let dryRun = false;
     let installAgentInstructions = true;
     let free = false;
@@ -96,6 +101,7 @@ function parseInstallArgs(argv) {
         }
         if (argument === "--server-name") {
             serverName = next;
+            serverNameExplicit = true;
             index += 1;
             continue;
         }
@@ -121,7 +127,7 @@ function parseInstallArgs(argv) {
         apiUrl = "https://app.askthew.com";
     }
     if (!serverName) {
-        serverName = "askthew";
+        serverName = defaultServerNameForTier(free);
     }
     return {
         hostType,
@@ -130,6 +136,7 @@ function parseInstallArgs(argv) {
         token,
         apiUrl,
         serverName,
+        serverNameExplicit,
         dryRun,
         installAgentInstructions,
         free,
@@ -140,16 +147,6 @@ function parseInstallArgs(argv) {
 function normalizeInstallToken(token) {
     return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
 }
-function packageVersion() {
-    try {
-        const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
-        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-        return typeof parsed.version === "string" ? parsed.version : "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
 function detectLoginEmail() {
     for (const value of [
         process.env.ASKTHEW_EMAIL,
@@ -189,6 +186,14 @@ async function main() {
         console.log(usage());
         return;
     }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(packageVersion());
+        return;
+    }
+    if (command === "doctor") {
+        await runDoctorCommand(argv);
+        return;
+    }
     if (command === "print-config") {
         const options = parseInstallArgs(argv);
         const snippet = createHostConfigSnippet(options);
@@ -196,6 +201,7 @@ async function main() {
         return;
     }
     if (command === "install") {
+        console.error(`Downloading @askthew/mcp-plugin@${packageVersion()}...`);
         const options = parseInstallArgs(argv);
         let freeIdentity = null;
         if (options.free && !options.dryRun) {
@@ -228,11 +234,14 @@ async function main() {
         console.log(result.wroteFile ? "Ask The W plugin install complete." : "Ask The W plugin dry run complete.");
         console.log(`Settings path: ${result.settingsPath}`);
         if (instructions) {
-            console.log(`Agent instructions: ${instructions.paths?.join(", ") ?? instructions.path}`);
+            console.log(`${options.dryRun ? "Would update agent instructions" : "Agent instructions"}: ${instructions.paths?.join(", ") ?? instructions.path}`);
         }
         if (receipt) {
             console.log(`Install receipt: ${receipt.hostType}/${receipt.serverName} at ${receipt.cwd}`);
         }
+        else if (options.dryRun) {
+            console.log(`Would write install receipt: ${options.hostType}/${options.serverName} at ${process.cwd()}`);
+        }
         console.log(`Install command: ${formatInstallCommand(options)}`);
         if (result.wroteFile) {
             if (freeIdentity) {
@@ -257,6 +266,7 @@ async function main() {
         console.log(`Next step: ${result.nextStep}`);
         if (!result.wroteFile) {
             console.log("");
+            console.log("Planned host config:");
             console.log(result.json);
         }
         return;
@@ -306,22 +316,24 @@ async function main() {
         return;
     }
     if (command === "upgrade") {
-        console.log("Open https://askthew.com/plugin to upgrade, then run `askthew-mcp upgrade --finalize`.");
-        if (argv.includes("--finalize")) {
-            console.log("Finalize will rewrite host config after a paid workspace token is available in the web app.");
-        }
+        await runUpgradeCommand(argv);
         return;
     }
     if (command) {
         throw new Error(`Unknown command "${command}".\n\n${usage()}`);
     }
+    if (process.stdin.isTTY) {
+        console.log(usage());
+        return;
+    }
     const server = createAskTheWMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
 async function runUninstallCommand(argv) {
     let hostType;
-    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || "askthew";
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || undefined;
+    let serverNameExplicit = Boolean(serverName);
     let dryRun = false;
     let keepLocalData = false;
     let keepAuth = false;
@@ -357,6 +369,7 @@ async function runUninstallCommand(argv) {
         }
         if (argument === "--server-name") {
             serverName = next;
+            serverNameExplicit = true;
             index += 1;
             continue;
         }
@@ -366,7 +379,12 @@ async function runUninstallCommand(argv) {
         throw new Error("Usage: askthew-mcp uninstall --host <claude_code|codex|cursor> [--server-name <name>]");
     }
     const receipts = findInstallReceipts({ hostType, serverName });
-    const config = uninstallHostConfig({ hostType, serverName, dryRun });
+    const config = uninstallHostConfig({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+        dryRun,
+        cwds: Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)])),
+    });
     const instructionCwds = Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)]));
     const instructionPaths = keepAgentInstructions
         ? []
@@ -419,6 +437,9 @@ async function runRefreshCommand(argv) {
     const options = {
         ...parsed,
         free: !isPaidRefresh,
+        serverName: parsed.serverNameExplicit
+            ? parsed.serverName
+            : defaultServerNameForTier(!isPaidRefresh),
     };
     const existingIdentity = loadLocalIdentity();
     let freeIdentity = existingIdentity;
@@ -497,6 +518,98 @@ async function runRefreshCommand(argv) {
         console.log(install.json);
     }
 }
+async function runDoctorCommand(argv) {
+    const serverEntrypoint = argValue(argv, "--server-entrypoint")?.trim();
+    const result = await runInitializeHandshake({
+        entrypoint: serverEntrypoint ? path.resolve(serverEntrypoint) : undefined,
+    });
+    const expectedVersion = packageVersion();
+    if (result.serverInfoVersion !== expectedVersion) {
+        throw new Error(`MCP initialize version mismatch: package.json=${expectedVersion} serverInfo.version=${result.serverInfoVersion ?? "missing"}`);
+    }
+    console.log("Ask The W MCP doctor passed.");
+    console.log(`Package version: ${expectedVersion}`);
+    console.log(`serverInfo.version: ${result.serverInfoVersion}`);
+}
+async function runUpgradeCommand(argv) {
+    if (argv.includes("--browser")) {
+        console.log("Open https://askthew.com/plugin to manage workspace upgrades.");
+        return;
+    }
+    let hostType = process.env.ASKTHEW_HOST_TYPE?.trim();
+    if (hostType !== "claude_code" && hostType !== "codex" && hostType !== "cursor") {
+        hostType = undefined;
+    }
+    let serverName = process.env.ASKTHEW_SERVER_NAME?.trim() || undefined;
+    let serverNameExplicit = Boolean(serverName);
+    let version = process.env.ASKTHEW_PIN?.trim() || packageVersion();
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next)
+            throw new Error(`Missing value for ${argument}.`);
+        if (argument === "--host") {
+            if (next !== "claude_code" && next !== "codex" && next !== "cursor") {
+                throw new Error(`Unsupported host "${next}". Expected claude_code, codex, or cursor.`);
+            }
+            hostType = next;
+            index += 1;
+            continue;
+        }
+        if (argument === "--server-name") {
+            serverName = next;
+            serverNameExplicit = true;
+            index += 1;
+            continue;
+        }
+        if (argument === "--version" || argument === "--pin") {
+            version = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+    if (!hostType) {
+        throw new Error("Usage: askthew-mcp upgrade --host <claude_code|codex|cursor> [--server-name <name>] [--version <version>] [--dry-run]");
+    }
+    const packageSpec = version.startsWith("@askthew/mcp-plugin@")
+        ? version
+        : `@askthew/mcp-plugin@${version}`;
+    if (!dryRun) {
+        const handshake = await runInitializeHandshake();
+        if (handshake.serverInfoVersion !== packageVersion()) {
+            throw new Error(`Refusing to upgrade pinned host config: MCP initialize returned ${handshake.serverInfoVersion ?? "missing"} but package.json is ${packageVersion()}.`);
+        }
+    }
+    const receipts = findInstallReceipts({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+    });
+    const result = upgradePinnedHostConfig({
+        hostType,
+        serverName: serverNameExplicit ? serverName : undefined,
+        packageSpec,
+        dryRun,
+        cwds: Array.from(new Set([process.cwd(), ...receipts.map((receipt) => receipt.cwd)])),
+    });
+    console.log(dryRun ? "Ask The W plugin upgrade dry run complete." : "Ask The W plugin upgrade complete.");
+    console.log(`Settings path: ${result.settingsPath}`);
+    console.log(`Pinned package: ${result.packageSpec}`);
+    console.log(result.upgradedServer
+        ? `${dryRun ? "Would update" : "Updated"} MCP server pin${result.upgradedServerNames.length ? `: ${result.upgradedServerNames.join(", ")}` : "."}`
+        : result.foundConfigFile
+            ? "No Ask The W MCP server pins needed an update."
+            : "No host config file found.");
+    if (dryRun && result.json) {
+        console.log("");
+        console.log(result.json);
+    }
+}
 function argValue(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 ? argv[index + 1] : undefined;

package/dist/index.d.ts

@@ -160,6 +160,9 @@ export declare function normalizeInstallTokenInput(token: string | undefined): s
 export declare function createAskTheWMcpServer(options?: AskTheWMcpServerOptions): McpServer;
 export declare function runInitializeHandshake(input?: {
     entrypoint?: string;
+    env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
-}): Promise<void>;
+}): Promise<{
+    serverInfoVersion?: string;
+}>;
 export {};

package/dist/index.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { spawn } from "node:child_process";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
@@ -10,9 +11,18 @@ import { resolveMcpMode } from "./lib/free-tier-policy.js";
 import { LocalStore } from "./lib/local-store.js";
 import { buildTelemetryPayload, flushTelemetryOutbox } from "./lib/telemetry.js";
 import { ensureLocalIdentity } from "./lib/local-identity.js";
-import { buildLocalTimeline, buildTimelineInsights as buildLocalTimelineInsights, renderTimelineMarkdown as renderLocalTimelineMarkdown } from "./lib/timeline-insights.js";
 import { paidDescription, paidFeatureNudge, toolJson } from "./lib/upgrade-nudge.js";
 import { configPath, readJsonFile } from "./lib/paths.js";
+const requirePackageJson = createRequire(import.meta.url);
+function packageVersion() {
+    try {
+        const manifest = requirePackageJson("../package.json");
+        return typeof manifest.version === "string" ? manifest.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 const evidenceRoleSchema = z.enum(["user", "assistant", "system"]);
 const evidenceEntrySchema = z.object({
     role: evidenceRoleSchema,
@@ -570,7 +580,7 @@ export function createAskTheWMcpServer(options = {}) {
     }
     const server = new McpServer({
         name: "Ask The W Coding Agent Connector",
-        version: "0.4.7",
+        version: packageVersion(),
     });
     if (options.sendStartupHeartbeat !== false && mode.mode === "paid") {
         void sendStartupSignals(options);
@@ -656,6 +666,89 @@ export function createAskTheWMcpServer(options = {}) {
         }
         return null;
     };
+    const localSessionAnalysisResponse = (payload) => {
+        if (!localStore) {
+            return localToolError({
+                code: "local_store_unavailable",
+                message: "The local Ask The W store is unavailable.",
+                retryable: true,
+                hint: "Retry after restarting the plugin host.",
+            });
+        }
+        const loginRequired = requireFreeIdentity();
+        if (loginRequired)
+            return loginRequired;
+        const scopeKey = currentScopeKey();
+        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
+        const allSessionIds = localStore.listSessionIds({ limit: 100000, scopeKey });
+        const allowedSessionIds = new Set(allSessionIds.slice(0, 3));
+        if (sessionId && allSessionIds.length > 3 && !allowedSessionIds.has(sessionId)) {
+            return localToolError({
+                code: "free_tier_limit",
+                message: "The free plugin can analyze the latest three local sessions.",
+                retryable: false,
+                hint: "Upgrade to review more than three sessions in the workspace dashboard.",
+                extra: {
+                    tool: "analyze_session",
+                    limit: 3,
+                    upgradeUrl: "https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=analyze_session",
+                    cta: "Upgrade to analyze more than three sessions in the workspace dashboard.",
+                },
+            });
+        }
+        const limit = Math.min(50, payload.limit ?? 50);
+        const signals = sessionId
+            ? localStore.listSignals({ sessionId, scopeKey, cursor: payload.cursor, limit })
+            : [];
+        const allSignals = sessionId ? localStore.listSignals({ sessionId, scopeKey, limit: 100000 }) : [];
+        const decisions = sessionId
+            ? localStore.listDecisions({ sessionId, scopeKey, limit: 100000 })
+            : [];
+        const decisionCandidates = listDecisionCandidates({ store: localStore, sessionId, scopeKey, limit: 25 }).candidates;
+        const counts = signals.reduce((accumulator, signal) => {
+            accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
+            return accumulator;
+        }, {});
+        const allCounts = allSignals.reduce((accumulator, signal) => {
+            accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
+            return accumulator;
+        }, {});
+        const nextCursor = signals.length >= limit ? signals.at(-1)?.capturedAt ?? null : null;
+        if ((payload.format ?? "markdown") === "json") {
+            return budgetedLocalResponse({
+                ok: true,
+                tier: "free",
+                sessionId,
+                format: "json",
+                signals: payload.compact
+                    ? signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id)))
+                    : signals.map((signal) => signalWithDecision(localStore, signal)),
+                decisions: payload.compact
+                    ? decisions.map((decision) => ({ id: decision.id, headline: decision.headline, status: decision.status, signalIds: decision.sourceSignalIds }))
+                    : decisions.map((decision) => decisionWithSignals(localStore, decision)),
+                decisionCandidates,
+                nextCursor,
+                counts: {
+                    totalSignals: allSignals.length,
+                    byKind: allCounts,
+                },
+            }, payload.max_chars);
+        }
+        return budgetedLocalResponse({
+            ok: true,
+            tier: "free",
+            sessionId,
+            format: "markdown",
+            rendered: renderSessionMarkdown({ sessionId, signals: allSignals, decisions, decisionCandidates }),
+            ...(payload.compact
+                ? { signals: allSignals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id))) }
+                : {}),
+            counts: {
+                totalSignals: allSignals.length,
+                byKind: Object.keys(allCounts).length ? allCounts : counts,
+            },
+        }, payload.max_chars);
+    };
     server.tool("capture_session_signal", {
         sessionId: z.string().min(1),
         sequence: z.number().int().nonnegative(),
@@ -974,18 +1067,7 @@ export function createAskTheWMcpServer(options = {}) {
         idempotencyKey: idempotencyKeySchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
-            const loginRequired = requireFreeIdentity();
-            if (loginRequired)
-                return loginRequired;
-            if (payload.confirmText !== payload.id) {
-                return localToolError({
-                    code: "confirmation_required",
-                    message: "confirmText must match the decision id.",
-                    retryable: false,
-                    hint: "Pass the exact decision id as confirmText.",
-                });
-            }
-            return localResponse({ ok: localStore.deleteDecision(payload.id), tier: "free" });
+            return localResponse(paidFeatureNudge("delete_decision"));
         }
         return apiToolResponse(`/api/decisions/${encodeURIComponent(payload.id)}`, {
             confirmText: payload.confirmText,
@@ -1139,31 +1221,7 @@ export function createAskTheWMcpServer(options = {}) {
         max_chars: maxCharsSchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
-            const loginRequired = requireFreeIdentity();
-            if (loginRequired)
-                return loginRequired;
-            const normalizedQuery = payload.query.toLowerCase();
-            const signals = localStore
-                .listSignals({
-                limit: 100000,
-                sessionId: payload.sessionId,
-                scopeKey: currentScopeKey(),
-            })
-                .filter((signal) => [
-                signal.summary,
-                signal.kind,
-                ...signal.filesTouched,
-                ...signal.commandsRun,
-            ].join("\n").toLowerCase().includes(normalizedQuery))
-                .slice(0, payload.limit);
-            return budgetedLocalResponse({
-                ok: true,
-                tier: "free",
-                query: payload.query,
-                signals: payload.compact === false
-                    ? signals.map((signal) => signalWithDecision(localStore, signal))
-                    : signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id))),
-            }, payload.max_chars ?? 8000);
+            return localResponse(paidFeatureNudge("find_signal_by_summary"));
         }
         return apiToolResponse(routeWithQuery("/api/signals", {
             query: payload.query,
@@ -1202,6 +1260,8 @@ export function createAskTheWMcpServer(options = {}) {
         compact: z.boolean().optional(),
         max_chars: maxCharsSchema,
     }, async (payload) => {
+        if (mode.mode !== "paid")
+            return localResponse(paidFeatureNudge("review_decisions"));
         if (mode.mode === "paid") {
             return apiToolResponse(routeWithQuery("/api/decisions", {
                 since: payload.since,
@@ -1213,42 +1273,7 @@ export function createAskTheWMcpServer(options = {}) {
                 max_chars: payload.max_chars,
             }));
         }
-        if (!localStore) {
-            return localToolError({
-                code: "local_store_unavailable",
-                message: "The local Ask The W store is unavailable.",
-                retryable: true,
-                hint: "Retry after restarting the plugin host.",
-            });
-        }
-        const loginRequired = requireFreeIdentity();
-        if (loginRequired)
-            return loginRequired;
-        const decisions = localStore.listDecisions({
-            since: payload.since,
-            status: payload.status,
-            limit: payload.limit,
-            cursor: payload.cursor,
-            sessionId: payload.sessionId,
-            scopeKey: currentScopeKey(),
-        });
-        return budgetedLocalResponse({
-            ok: true,
-            tier: "free",
-            format: payload.format,
-            rendered: renderDecisionDigest(decisions),
-            decisions: payload.compact
-                ? decisions.map((decision) => ({
-                    id: decision.id,
-                    headline: decision.headline,
-                    status: decision.status,
-                    signalIds: decision.sourceSignalIds,
-                }))
-                : decisions.map((decision) => decisionWithSignals(localStore, decision)),
-            count: decisions.length,
-            nextCursor: decisions.length >= payload.limit ? decisions.at(-1)?.createdAt ?? null : null,
-            copyHint: "Copy this output to back up your decisions - `export_decisions` is a paid feature.",
-        }, payload.max_chars);
+        return localResponse(paidFeatureNudge("review_decisions"));
     });
     server.tool("review_session", "Review the current session trail. Use for natural prompts like: Show me my session trail.", {
         sessionId: z.string().optional(),
@@ -1258,6 +1283,8 @@ export function createAskTheWMcpServer(options = {}) {
         compact: z.boolean().optional(),
         max_chars: maxCharsSchema,
     }, async (payload) => {
+        if (mode.mode !== "paid")
+            return localResponse(paidFeatureNudge("review_session"));
         if (!localStore || mode.mode === "paid") {
             return apiToolResponse(routeWithQuery("/api/signals", {
                 sessionId: payload.sessionId,
@@ -1267,79 +1294,26 @@ export function createAskTheWMcpServer(options = {}) {
                 max_chars: payload.max_chars,
             }));
         }
-        const loginRequired = requireFreeIdentity();
-        if (loginRequired)
-            return loginRequired;
-        const scopeKey = currentScopeKey();
-        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
-        const allSessionIds = localStore.listSessionIds({ limit: 100000, scopeKey });
-        const allowedSessionIds = new Set(allSessionIds.slice(0, 3));
-        if (sessionId && allSessionIds.length > 3 && !allowedSessionIds.has(sessionId)) {
-            return localToolError({
-                code: "free_tier_limit",
-                message: "The free plugin can review the latest three local sessions.",
-                retryable: false,
-                hint: "Upgrade to review more than three sessions in the workspace dashboard.",
-                extra: {
-                    tool: "review_session",
-                    limit: 3,
-                    upgradeUrl: "https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=review_session",
-                    cta: "Upgrade to review more than three sessions in the workspace dashboard.",
-                },
-            });
-        }
-        const limit = Math.min(50, payload.limit ?? 50);
-        const signals = sessionId
-            ? localStore.listSignals({ sessionId, scopeKey, cursor: payload.cursor, limit })
-            : [];
-        const allSignals = sessionId ? localStore.listSignals({ sessionId, scopeKey, limit: 100000 }) : [];
-        const decisions = sessionId
-            ? localStore.listDecisions({ sessionId, scopeKey, limit: 100000 })
-            : [];
-        const decisionCandidates = listDecisionCandidates({ store: localStore, sessionId, scopeKey, limit: 25 }).candidates;
-        const counts = signals.reduce((accumulator, signal) => {
-            accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
-            return accumulator;
-        }, {});
-        const allCounts = allSignals.reduce((accumulator, signal) => {
-            accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
-            return accumulator;
-        }, {});
-        const nextCursor = signals.length >= limit ? signals.at(-1)?.capturedAt ?? null : null;
-        if (payload.format === "json") {
-            return budgetedLocalResponse({
-                ok: true,
-                tier: "free",
-                sessionId,
-                format: "json",
-                signals: payload.compact
-                    ? signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id)))
-                    : signals.map((signal) => signalWithDecision(localStore, signal)),
-                decisions: payload.compact
-                    ? decisions.map((decision) => ({ id: decision.id, headline: decision.headline, status: decision.status, signalIds: decision.sourceSignalIds }))
-                    : decisions.map((decision) => decisionWithSignals(localStore, decision)),
-                decisionCandidates,
-                nextCursor,
-                counts: {
-                    totalSignals: allSignals.length,
-                    byKind: allCounts,
-                },
-            }, payload.max_chars);
+        return localResponse(paidFeatureNudge("review_session"));
+    });
+    server.tool("analyze_session", "Analyze the latest local coding-agent session.", {
+        sessionId: z.string().optional(),
+        format: z.enum(["markdown", "json"]).default("markdown"),
+        cursor: cursorSchema,
+        limit: z.number().int().positive().max(50).default(50),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
+    }, async (payload) => {
+        if (!localStore || mode.mode === "paid") {
+            return apiToolResponse(routeWithQuery("/api/signals", {
+                sessionId: payload.sessionId,
+                cursor: payload.cursor,
+                limit: payload.limit,
+                compact: payload.compact,
+                max_chars: payload.max_chars,
+            }));
         }
-        return budgetedLocalResponse({
-            ok: true,
-            tier: "free",
-            sessionId,
-            format: "markdown",
-            rendered: renderSessionMarkdown({ sessionId, signals: allSignals, decisions, decisionCandidates }),
-            ...(payload.compact
-                ? { signals: allSignals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id))) }
-                : {}),
-            counts: {
-                totalSignals: allSignals.length,
-                byKind: Object.keys(allCounts).length ? allCounts : counts,
-            },
-        }, payload.max_chars);
+        return localSessionAnalysisResponse(payload);
     });
     server.tool("recap", "Summarize the latest local coding-agent session as a digest, standup, or share-ready recap.", {
         format: z.enum(["digest", "standup", "share"]).default("digest"),
@@ -1475,27 +1449,14 @@ export function createAskTheWMcpServer(options = {}) {
         cursor: cursorSchema,
         max_chars: maxCharsSchema,
     }, async (payload) => {
-        if (!localStore || mode.mode === "paid")
+        if (mode.mode !== "paid")
             return localResponse(paidFeatureNudge("list_decision_candidates"));
-        const loginRequired = requireFreeIdentity();
-        if (loginRequired)
-            return loginRequired;
-        const scopeKey = currentScopeKey();
-        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
-        const result = listDecisionCandidates({
-            store: localStore,
-            sessionId,
-            scopeKey,
+        return apiToolResponse(routeWithQuery("/api/signals/decision-candidates", {
+            sessionId: payload.sessionId,
             limit: payload.limit,
             cursor: payload.cursor,
-        });
-        return budgetedLocalResponse({
-            ok: true,
-            tier: "free",
-            sessionId,
-            decisionCandidates: result.candidates,
-            nextCursor: result.nextCursor,
-        }, payload.max_chars);
+            max_chars: payload.max_chars,
+        }));
     });
     server.tool("search_trail", "Search local signals and decisions together.", {
         query: z.string().min(1),
@@ -1505,27 +1466,16 @@ export function createAskTheWMcpServer(options = {}) {
         compact: z.boolean().optional(),
         max_chars: maxCharsSchema,
     }, async (payload) => {
-        if (!localStore || mode.mode === "paid")
+        if (mode.mode !== "paid")
             return localResponse(paidFeatureNudge("search_trail"));
-        const loginRequired = requireFreeIdentity();
-        if (loginRequired)
-            return loginRequired;
-        const result = searchTrail({
-            store: localStore,
+        return apiToolResponse(routeWithQuery("/api/search/trail", {
             query: payload.query,
-            scopeKey: currentScopeKey(),
             sessionId: payload.sessionId,
             limit: payload.limit,
             cursor: payload.cursor,
             compact: payload.compact,
-        });
-        return budgetedLocalResponse({
-            ok: true,
-            tier: "free",
-            query: payload.query,
-            matches: result.matches,
-            nextCursor: result.nextCursor,
-        }, payload.max_chars);
+            max_chars: payload.max_chars,
+        }));
     });
     server.tool("export_decisions", paidDescription("Export decisions from your workspace.", mode.mode), {
         format: z.enum(["json", "markdown", "jsonl"]).default("json"),
@@ -1563,44 +1513,7 @@ export function createAskTheWMcpServer(options = {}) {
                 signalSource: payload.signalSource,
             }));
         }
-        if (!localStore) {
-            return localToolError({
-                code: "local_store_unavailable",
-                message: "The local Ask The W store is unavailable.",
-                retryable: true,
-                hint: "Retry after restarting the plugin host.",
-            });
-        }
-        const loginRequired = requireFreeIdentity();
-        if (loginRequired)
-            return loginRequired;
-        const scopeKey = currentScopeKey();
-        const points = buildLocalTimeline({
-            scope: payload.scope,
-            signals: localStore.listSignals({ scopeKey, limit: 100000 }),
-            decisions: localStore.listDecisions({ scopeKey, limit: 100000 }),
-            limit: payload.limit,
-        });
-        const totals = points.reduce((accumulator, point) => ({
-            signals: accumulator.signals + point.signalCount,
-            decisions: accumulator.decisions + point.decisionCount,
-        }), { signals: 0, decisions: 0 });
-        return budgetedLocalResponse({
-            ok: true,
-            tier: "free",
-            scope: payload.scope,
-            period: {
-                start: points[0]?.startedAt ?? points[0]?.x ?? "",
-                end: points.at(-1)?.endedAt ?? points.at(-1)?.x ?? "",
-                label: "Local timeline",
-                tz: "UTC",
-            },
-            points,
-            totals,
-            insights: buildLocalTimelineInsights(points),
-            narrative: `Local timeline: ${totals.signals} signals, ${totals.decisions} decisions.`,
-            markdownTable: renderLocalTimelineMarkdown(points, payload.scope),
-        }, payload.max_chars);
+        return localResponse(paidFeatureNudge("view_timeline"));
     });
     return server;
 }
@@ -1919,7 +1832,7 @@ export async function runInitializeHandshake(input = {}) {
     const modulePath = input.entrypoint ?? fileURLToPath(import.meta.url);
     const child = spawn(process.execPath, [modulePath], {
         cwd: process.cwd(),
-        env: process.env,
+        env: input.env ?? process.env,
         stdio: ["pipe", "pipe", "pipe"],
     });
     let stdout = "";
@@ -1944,7 +1857,7 @@ export async function runInitializeHandshake(input = {}) {
     };
     child.stdin.write(`${JSON.stringify(initialize)}\n`);
     try {
-        await new Promise((resolve, reject) => {
+        return await new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 reject(new Error(`Timed out waiting for initialize response. stdout=${stdout} stderr=${stderr}`));
             }, input.timeoutMs ?? 3000);
@@ -1963,7 +1876,11 @@ export async function runInitializeHandshake(input = {}) {
                     reject(new Error(`Unexpected initialize response: ${JSON.stringify(response)}`));
                     return;
                 }
-                resolve();
+                resolve({
+                    serverInfoVersion: typeof response.result?.serverInfo?.version === "string"
+                        ? response.result.serverInfo.version
+                        : undefined,
+                });
             };
             child.stdout.on("data", check);
             child.once("exit", failOnExit);

package/dist/install.d.ts

@@ -19,10 +19,13 @@ interface InstallHostConfigInput extends HostConfigInput {
 interface UninstallHostConfigInput {
     hostType: SupportedHostType;
     serverName?: string;
+    cwds?: string[];
     dryRun?: boolean;
     homeDirectory?: string;
     cwd?: string;
 }
+export declare const DEFAULT_FREE_SERVER_NAME = "askthew-free";
+export declare const DEFAULT_WORKSPACE_SERVER_NAME = "askthew-workspace";
 export interface InstallReceipt {
     hostType: SupportedHostType;
     serverName: string;
@@ -34,6 +37,8 @@ export interface InstallReceipt {
     installedAt: string;
     packageVersion?: string;
 }
+export declare function packageVersion(): string;
+export declare function defaultServerNameForTier(free?: boolean): "askthew-free" | "askthew-workspace";
 export declare function resolveSettingsPath(input: {
     hostType: SupportedHostType;
     homeDirectory?: string;
@@ -137,10 +142,28 @@ export declare function uninstallHostConfig(input: UninstallHostConfigInput): {
     settingsPath: string;
     json: string;
     removedServerName: string;
+    removedServerNames: string[];
     foundConfigFile: boolean;
     removedServer: boolean;
     wroteFile: boolean;
 };
+export declare function upgradePinnedHostConfig(input: {
+    hostType: SupportedHostType;
+    serverName?: string;
+    packageSpec?: string;
+    dryRun?: boolean;
+    homeDirectory?: string;
+    cwd?: string;
+    cwds?: string[];
+}): {
+    settingsPath: string;
+    json: string;
+    packageSpec: string;
+    foundConfigFile: boolean;
+    upgradedServer: boolean;
+    upgradedServerNames: string[];
+    wroteFile: boolean;
+};
 export declare function sendInstallHeartbeat(input: HostConfigInput & {
     cwd?: string;
     fetchImpl?: typeof fetch;

package/dist/install.js

@@ -1,14 +1,44 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { askTheWDataDir, installReceiptsPath, readJsonFile, writePrivateJson } from "./lib/paths.js";
 import { resolvePluginScope } from "./scope.js";
-const ASKTHEW_INSTRUCTIONS_START = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_START -->";
-const ASKTHEW_INSTRUCTIONS_END = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_END -->";
+export const DEFAULT_FREE_SERVER_NAME = "askthew-free";
+export const DEFAULT_WORKSPACE_SERVER_NAME = "askthew-workspace";
+const LEGACY_DEFAULT_SERVER_NAME = "askthew";
+const ASKTHEW_INSTRUCTIONS_START = "<!-- @askthew/mcp-plugin v1 - managed block, do not hand-edit -->";
+const ASKTHEW_INSTRUCTIONS_END = "<!-- /@askthew/mcp-plugin v1 -->";
+const LEGACY_ASKTHEW_INSTRUCTIONS_START = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_START -->";
+const LEGACY_ASKTHEW_INSTRUCTIONS_END = "<!-- ASKTHEW_PLUGIN_INSTRUCTIONS_END -->";
 const INSTALL_RECEIPTS_SCHEMA_VERSION = 1;
+const requirePackageJson = createRequire(import.meta.url);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+export function packageVersion() {
+    try {
+        const manifest = requirePackageJson("../package.json");
+        return typeof manifest.version === "string" ? manifest.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function defaultServerNameForTier(free) {
+    return free ? DEFAULT_FREE_SERVER_NAME : DEFAULT_WORKSPACE_SERVER_NAME;
+}
+function defaultServerNamesToRemove() {
+    return [DEFAULT_FREE_SERVER_NAME, DEFAULT_WORKSPACE_SERVER_NAME, LEGACY_DEFAULT_SERVER_NAME];
+}
+function packageSpecFromPin(env = process.env) {
+    const pin = env.ASKTHEW_PIN?.trim() || packageVersion();
+    if (!pin || pin === "unknown")
+        return "@askthew/mcp-plugin@latest";
+    if (pin.startsWith("@askthew/mcp-plugin@"))
+        return pin;
+    return `@askthew/mcp-plugin@${pin}`;
+}
 export function resolveSettingsPath(input) {
     const homeDirectory = input.homeDirectory ?? os.homedir();
     if (input.hostType === "codex") {
@@ -42,7 +72,7 @@ export function createServerEntry(input) {
     }
     return {
         command: "npx",
-        args: ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"],
+        args: ["-y", "--package", packageSpecFromPin(), "askthew-mcp"],
         env,
     };
 }
@@ -91,14 +121,75 @@ function removeCodexTomlServer(content, serverName) {
     const sectionPattern = new RegExp(`\\n?\\[mcp_servers\\.(?:${escapedServerName}|${quotedServerName})\\]\\n[\\s\\S]*?(?=\\n\\[[^\\]]+\\]|$)`, "g");
     return content.replace(sectionPattern, "").trimEnd();
 }
+function serverNamesForRemoval(serverName) {
+    const trimmed = serverName?.trim();
+    if (!trimmed)
+        return defaultServerNamesToRemove();
+    return trimmed === LEGACY_DEFAULT_SERVER_NAME
+        ? [LEGACY_DEFAULT_SERVER_NAME]
+        : [trimmed, LEGACY_DEFAULT_SERVER_NAME];
+}
 function mergeCodexSettings(input) {
     let next = input.existingSettings.trimEnd();
-    if (input.serverName !== "askthew") {
-        next = removeCodexTomlServer(next, "askthew");
+    if (input.serverName !== LEGACY_DEFAULT_SERVER_NAME) {
+        next = removeCodexTomlServer(next, LEGACY_DEFAULT_SERVER_NAME);
     }
     next = removeCodexTomlServer(next, input.serverName);
     return `${next}${next ? "\n\n" : ""}${createCodexTomlSection(input)}\n`;
 }
+function expandHome(inputPath, homeDirectory = os.homedir()) {
+    if (inputPath === "~")
+        return homeDirectory;
+    if (inputPath.startsWith("~/"))
+        return path.join(homeDirectory, inputPath.slice(2));
+    return inputPath;
+}
+function pathAliases(inputPath, homeDirectory = os.homedir()) {
+    const aliases = new Set();
+    const expanded = expandHome(inputPath, homeDirectory);
+    const resolved = path.resolve(expanded);
+    aliases.add(resolved);
+    if (resolved.startsWith("/private/tmp/"))
+        aliases.add(`/tmp/${resolved.slice("/private/tmp/".length)}`);
+    if (resolved.startsWith("/tmp/"))
+        aliases.add(`/private/tmp/${resolved.slice("/tmp/".length)}`);
+    try {
+        aliases.add(fs.realpathSync.native(resolved));
+    }
+    catch {
+        try {
+            aliases.add(fs.realpathSync(resolved));
+        }
+        catch {
+            // The project may have been deleted; lexical aliases are still useful.
+        }
+    }
+    return aliases;
+}
+function equivalentProjectPath(left, right, homeDirectory = os.homedir()) {
+    const leftAliases = pathAliases(left, homeDirectory);
+    const rightAliases = pathAliases(right, homeDirectory);
+    for (const alias of leftAliases) {
+        if (rightAliases.has(alias))
+            return true;
+    }
+    return false;
+}
+function claudeProjectKeys(input) {
+    const homeDirectory = input.homeDirectory ?? os.homedir();
+    const cwdAliases = new Set();
+    for (const cwd of input.cwds) {
+        for (const alias of pathAliases(cwd, homeDirectory)) {
+            cwdAliases.add(alias);
+        }
+    }
+    for (const projectKey of Object.keys(input.existingProjects)) {
+        if (input.cwds.some((cwd) => equivalentProjectPath(projectKey, cwd, homeDirectory))) {
+            cwdAliases.add(projectKey);
+        }
+    }
+    return Array.from(cwdAliases);
+}
 function mergeClaudeCodeSettings(input) {
     const cwd = path.resolve(input.cwd ?? process.cwd());
     const existingSettings = isRecord(input.existingSettings) ? input.existingSettings : {};
@@ -106,8 +197,8 @@ function mergeClaudeCodeSettings(input) {
     const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
     const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
     const nextMcpServers = { ...existingMcpServers };
-    if (input.serverName !== "askthew" && "askthew" in nextMcpServers) {
-        delete nextMcpServers.askthew;
+    if (input.serverName !== LEGACY_DEFAULT_SERVER_NAME && LEGACY_DEFAULT_SERVER_NAME in nextMcpServers) {
+        delete nextMcpServers[LEGACY_DEFAULT_SERVER_NAME];
     }
     return {
         ...existingSettings,
@@ -127,8 +218,8 @@ export function mergeHostSettings(input) {
     const existingSettings = isRecord(input.existingSettings) ? input.existingSettings : {};
     const existingMcpServers = isRecord(existingSettings.mcpServers) ? existingSettings.mcpServers : {};
     const nextMcpServers = { ...existingMcpServers };
-    if (input.serverName !== "askthew" && "askthew" in nextMcpServers) {
-        delete nextMcpServers.askthew;
+    if (input.serverName !== LEGACY_DEFAULT_SERVER_NAME && LEGACY_DEFAULT_SERVER_NAME in nextMcpServers) {
+        delete nextMcpServers[LEGACY_DEFAULT_SERVER_NAME];
     }
     return {
         ...existingSettings,
@@ -292,7 +383,7 @@ export function uninstallHostConfig(input) {
         hostType: input.hostType,
         homeDirectory: input.homeDirectory,
     });
-    const serverName = input.serverName?.trim() || "askthew";
+    const serverNames = serverNamesForRemoval(input.serverName);
     let json = "";
     let foundConfigFile = false;
     let removedServer = false;
@@ -300,43 +391,55 @@ export function uninstallHostConfig(input) {
         foundConfigFile = true;
         const raw = fs.readFileSync(settingsPath, "utf8");
         if (input.hostType === "codex") {
-            removedServer = raw !== removeCodexTomlServer(raw, serverName) || (serverName !== "askthew" && raw !== removeCodexTomlServer(raw, "askthew"));
-            json = removeCodexTomlServer(raw, serverName);
-            if (serverName !== "askthew") {
-                json = removeCodexTomlServer(json, "askthew");
+            json = raw;
+            for (const serverName of serverNames) {
+                const before = json;
+                json = removeCodexTomlServer(json, serverName);
+                removedServer = removedServer || before !== json;
             }
             json = json ? `${json}\n` : "";
         }
         else {
             const parsed = raw.trim() ? JSON.parse(raw) : {};
             if (input.hostType === "claude_code") {
-                const cwd = path.resolve(input.cwd ?? process.cwd());
+                const cwdInputs = input.cwds && input.cwds.length > 0 ? input.cwds : [input.cwd ?? process.cwd()];
                 const existingProjects = isRecord(parsed.projects) ? parsed.projects : {};
-                const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
-                const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
-                const nextServers = { ...existingMcpServers };
-                removedServer = serverName in nextServers || (serverName !== "askthew" && "askthew" in nextServers);
-                delete nextServers[serverName];
-                if (serverName !== "askthew")
-                    delete nextServers.askthew;
-                json = JSON.stringify({
-                    ...parsed,
-                    projects: {
-                        ...existingProjects,
-                        [cwd]: {
+                const nextProjects = { ...existingProjects };
+                const projectKeys = claudeProjectKeys({
+                    existingProjects,
+                    cwds: cwdInputs,
+                    homeDirectory: input.homeDirectory,
+                });
+                for (const cwd of projectKeys) {
+                    const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
+                    const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
+                    const nextServers = { ...existingMcpServers };
+                    const beforeCount = Object.keys(nextServers).length;
+                    for (const serverName of serverNames) {
+                        delete nextServers[serverName];
+                    }
+                    const removedHere = Object.keys(nextServers).length !== beforeCount;
+                    removedServer = removedServer || removedHere;
+                    if (removedHere || isRecord(existingProjects[cwd])) {
+                        nextProjects[cwd] = {
                             ...existingProject,
                             mcpServers: nextServers,
-                        },
-                    },
+                        };
+                    }
+                }
+                json = JSON.stringify({
+                    ...parsed,
+                    projects: nextProjects,
                 }, null, 2);
             }
             else {
                 const existingMcpServers = isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
                 const nextServers = { ...existingMcpServers };
-                removedServer = serverName in nextServers || (serverName !== "askthew" && "askthew" in nextServers);
-                delete nextServers[serverName];
-                if (serverName !== "askthew")
-                    delete nextServers.askthew;
+                const beforeCount = Object.keys(nextServers).length;
+                for (const serverName of serverNames) {
+                    delete nextServers[serverName];
+                }
+                removedServer = Object.keys(nextServers).length !== beforeCount;
                 json = JSON.stringify({ ...parsed, mcpServers: nextServers }, null, 2);
             }
             json = `${json}\n`;
@@ -348,12 +451,147 @@ export function uninstallHostConfig(input) {
     return {
         settingsPath,
         json,
-        removedServerName: serverName,
+        removedServerName: serverNames.join(", "),
+        removedServerNames: serverNames,
         foundConfigFile,
         removedServer,
         wroteFile: !input.dryRun && foundConfigFile,
     };
 }
+function updateNpxPackageArgs(args, packageSpec) {
+    let changed = false;
+    const nextArgs = args.map((arg, index) => {
+        if (typeof arg !== "string")
+            return arg;
+        if (arg === "--package" && typeof args[index + 1] === "string")
+            return arg;
+        if (index > 0 && args[index - 1] === "--package" && arg.startsWith("@askthew/mcp-plugin@")) {
+            changed = changed || arg !== packageSpec;
+            return packageSpec;
+        }
+        if (arg.startsWith("@askthew/mcp-plugin@")) {
+            changed = changed || arg !== packageSpec;
+            return packageSpec;
+        }
+        return arg;
+    });
+    return { args: nextArgs, changed };
+}
+function updateServerEntryPackage(entry, packageSpec) {
+    if (!isRecord(entry) || !Array.isArray(entry.args))
+        return { entry, changed: false };
+    const updated = updateNpxPackageArgs(entry.args, packageSpec);
+    if (!updated.changed)
+        return { entry, changed: false };
+    return {
+        entry: {
+            ...entry,
+            args: updated.args,
+        },
+        changed: true,
+    };
+}
+function updateCodexPackageSpec(input) {
+    let changed = false;
+    let next = input.content;
+    for (const serverName of input.serverNames) {
+        const escapedServerName = serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const quotedServerName = escapeTomlString(serverName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const sectionPattern = new RegExp(`(\\n?\\[mcp_servers\\.(?:${escapedServerName}|${quotedServerName})\\]\\n[\\s\\S]*?)(?=\\n\\[[^\\]]+\\]|$)`, "g");
+        next = next.replace(sectionPattern, (section) => {
+            const updated = section.replace(/@askthew\/mcp-plugin@[^"',\]\s]+/g, input.packageSpec);
+            changed = changed || updated !== section;
+            return updated;
+        });
+    }
+    return { json: next, changed };
+}
+export function upgradePinnedHostConfig(input) {
+    const settingsPath = resolveSettingsPath({
+        hostType: input.hostType,
+        homeDirectory: input.homeDirectory,
+    });
+    const packageSpec = input.packageSpec?.trim() || packageSpecFromPin();
+    const serverNames = serverNamesForRemoval(input.serverName);
+    let json = "";
+    let foundConfigFile = false;
+    let upgradedServer = false;
+    const upgradedServerNames = new Set();
+    if (fs.existsSync(settingsPath)) {
+        foundConfigFile = true;
+        const raw = fs.readFileSync(settingsPath, "utf8");
+        if (input.hostType === "codex") {
+            const updated = updateCodexPackageSpec({ content: raw, serverNames, packageSpec });
+            json = updated.json;
+            upgradedServer = updated.changed;
+            if (updated.changed) {
+                for (const serverName of serverNames)
+                    upgradedServerNames.add(serverName);
+            }
+        }
+        else {
+            const parsed = raw.trim() ? JSON.parse(raw) : {};
+            if (input.hostType === "claude_code") {
+                const existingProjects = isRecord(parsed.projects) ? parsed.projects : {};
+                const cwdInputs = input.cwds && input.cwds.length > 0 ? input.cwds : [input.cwd ?? process.cwd()];
+                const projectKeys = claudeProjectKeys({
+                    existingProjects,
+                    cwds: cwdInputs,
+                    homeDirectory: input.homeDirectory,
+                });
+                const nextProjects = { ...existingProjects };
+                for (const cwd of projectKeys) {
+                    const existingProject = isRecord(existingProjects[cwd]) ? existingProjects[cwd] : {};
+                    const existingMcpServers = isRecord(existingProject.mcpServers) ? existingProject.mcpServers : {};
+                    const nextServers = { ...existingMcpServers };
+                    let touchedProject = false;
+                    for (const serverName of serverNames) {
+                        const updated = updateServerEntryPackage(nextServers[serverName], packageSpec);
+                        if (updated.changed) {
+                            nextServers[serverName] = updated.entry;
+                            upgradedServer = true;
+                            touchedProject = true;
+                            upgradedServerNames.add(serverName);
+                        }
+                    }
+                    if (touchedProject) {
+                        nextProjects[cwd] = {
+                            ...existingProject,
+                            mcpServers: nextServers,
+                        };
+                    }
+                }
+                json = JSON.stringify({ ...parsed, projects: nextProjects }, null, 2);
+            }
+            else {
+                const existingMcpServers = isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
+                const nextServers = { ...existingMcpServers };
+                for (const serverName of serverNames) {
+                    const updated = updateServerEntryPackage(nextServers[serverName], packageSpec);
+                    if (updated.changed) {
+                        nextServers[serverName] = updated.entry;
+                        upgradedServer = true;
+                        upgradedServerNames.add(serverName);
+                    }
+                }
+                json = JSON.stringify({ ...parsed, mcpServers: nextServers }, null, 2);
+            }
+            json = `${json}\n`;
+        }
+        if (!input.dryRun && upgradedServer) {
+            fs.writeFileSync(settingsPath, json.endsWith("\n") ? json : `${json}\n`, "utf8");
+        }
+    }
+    return {
+        settingsPath,
+        json,
+        packageSpec,
+        foundConfigFile,
+        upgradedServer,
+        upgradedServerNames: Array.from(upgradedServerNames),
+        wroteFile: !input.dryRun && foundConfigFile && upgradedServer,
+    };
+}
 export async function sendInstallHeartbeat(input) {
     const fetcher = input.fetchImpl ?? fetch;
     const scope = resolvePluginScope(input.cwd ?? process.cwd());
@@ -424,6 +662,16 @@ function behaviorInstructions(hostType, cwd = process.cwd()) {
         `- If the tool is unavailable, tell the user to restart or reload ${hostLabel}; do not use \`list_mcp_resources\` or \`list_mcp_resource_templates\` as pass/fail checks.`,
         "- If you realize later in the conversation that the startup call was missed, send it immediately with `metadata.recovered_missed_startup=true`.",
         "",
+        "Schema:",
+        "- `sessionId` (string, required): stable across one session. Derive as `<repo-name>-<YYYYMMDD>-<git-HEAD-short>`. Reuse for every call in the session.",
+        "- `sequence` (integer >= 0, required): start at 0, increment by 1 per call within the same `sessionId`.",
+        "- `kind` (enum, required): one of `setup_complete`, `session_checkpoint`, `direction_change`, `implementation_update`, `verification_result`, `final_summary`.",
+        "- `summary` (string <= 2000, required).",
+        "- `evidence`, `filesTouched`, `commandsRun`, `metadata`: optional.",
+        "",
+        "Example:",
+        '{ "sessionId": "thesisengine-20260508-a1b2c3d", "sequence": 0, "kind": "setup_complete", "summary": "..." }',
+        "",
         "Send an update:",
         "- after the user accepts or rejects product, architecture, or implementation direction",
         "- before using tools that write files, after meaningful implementation changes",
@@ -431,7 +679,7 @@ function behaviorInstructions(hostType, cwd = process.cwd()) {
         "- at the final summary",
         ...(stackGuidance.length > 0 ? ["", "Stack-specific nudges:", ...stackGuidance] : []),
         "",
-        "Keep updates compact: short summary, minimal evidence excerpts, files touched, commands run, and useful metadata. Do not send full transcripts. Redact obvious secrets before sending.",
+        "Keep updates compact: short summary, minimal evidence excerpts, files touched, commands run, and useful metadata. Do not send full transcripts. Redact obvious secrets in evidence excerpts (commands, file paths, log lines). Server-side redaction (AWS, Stripe, GitHub, JWT, PEM, OpenAI/Anthropic, DSNs, emails, SSN) runs as a safety net, but agent-side redaction is still preferred.",
         "",
         ASKTHEW_INSTRUCTIONS_END,
         "",
@@ -448,10 +696,15 @@ function cursorBehaviorInstructions(cwd = process.cwd()) {
     ].join("\n");
 }
 function upsertMarkedBlock(existing, block) {
-    const startIndex = existing.indexOf(ASKTHEW_INSTRUCTIONS_START);
-    const endIndex = existing.indexOf(ASKTHEW_INSTRUCTIONS_END);
-    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
-        const afterEnd = endIndex + ASKTHEW_INSTRUCTIONS_END.length;
+    for (const [startMarker, endMarker] of [
+        [ASKTHEW_INSTRUCTIONS_START, ASKTHEW_INSTRUCTIONS_END],
+        [LEGACY_ASKTHEW_INSTRUCTIONS_START, LEGACY_ASKTHEW_INSTRUCTIONS_END],
+    ]) {
+        const startIndex = existing.indexOf(startMarker);
+        const endIndex = existing.indexOf(endMarker);
+        if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex)
+            continue;
+        const afterEnd = endIndex + endMarker.length;
         return `${existing.slice(0, startIndex).trimEnd()}\n\n${block.trimEnd()}\n${existing.slice(afterEnd).trimStart()}`.trimEnd() + "\n";
     }
     return `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block.trimEnd()}\n`;
@@ -495,7 +748,14 @@ export function uninstallBehaviorInstructions(input) {
         if (!fs.existsSync(instructionsPath))
             continue;
         const existing = fs.readFileSync(instructionsPath, "utf8");
-        const next = existing.replace(new RegExp(`\\n?${ASKTHEW_INSTRUCTIONS_START}[\\s\\S]*?${ASKTHEW_INSTRUCTIONS_END}\\n?`, "g"), "\n").trimEnd() + "\n";
+        let next = existing;
+        for (const [startMarker, endMarker] of [
+            [ASKTHEW_INSTRUCTIONS_START, ASKTHEW_INSTRUCTIONS_END],
+            [LEGACY_ASKTHEW_INSTRUCTIONS_START, LEGACY_ASKTHEW_INSTRUCTIONS_END],
+        ]) {
+            next = next.replace(new RegExp(`\\n?${startMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${endMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "g"), "\n");
+        }
+        next = next.trimEnd() + "\n";
         if (!input.dryRun)
             fs.writeFileSync(instructionsPath, next, "utf8");
         touchedPaths.push(instructionsPath);

package/dist/lib/local-store.js

@@ -497,10 +497,21 @@ export class LocalStore {
     openDatabase() {
         const loaded = tryRequireBetterSqlite3();
         if (loaded) {
-            fs.mkdirSync(path.dirname(this.storePath), { recursive: true, mode: 0o700 });
-            this.db = new loaded(this.storePath);
-            this.migrate();
-            return;
+            try {
+                fs.mkdirSync(path.dirname(this.storePath), { recursive: true, mode: 0o700 });
+                this.db = new loaded(this.storePath);
+                this.migrate();
+                return;
+            }
+            catch {
+                try {
+                    this.db?.close();
+                }
+                catch {
+                    // Ignore close failures while falling back to the JSON store.
+                }
+                this.db = null;
+            }
         }
         this.jsonMode = true;
         this.jsonPath = jsonFallbackStorePath();

package/dist/lib/upgrade-nudge.js

@@ -22,7 +22,7 @@ export function paidFeatureNudge(tool) {
         pricingUrl: PRICING_URL,
         upgradeUrl: `https://askthew.com/plugin?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=${encodeURIComponent(tool)}`,
         supportEmail: SUPPORT_EMAIL,
-        cta: "Run: npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp upgrade",
+        cta: "Run: npx -y --prefer-online --package @askthew/mcp-plugin@latest askthew-mcp upgrade --browser",
     };
 }
 export function toolJson(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askthew/mcp-plugin",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "private": false,
   "description": "Ask The W plugin connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",