@askthew/mcp-plugin 0.4.7 → 0.4.9

package/dist/install.js

@@ -1,12 +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") {
@@ -19,21 +51,29 @@ export function resolveSettingsPath(input) {
 }
 export function createServerEntry(input) {
     const scope = resolvePluginScope(input.cwd ?? process.cwd());
+    const env = {
+        ASKTHEW_API_URL: input.apiUrl,
+        ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
+        ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
+        ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
+        ASKTHEW_HOST_TYPE: input.hostType,
+        ASKTHEW_SERVER_NAME: input.serverName,
+        ASKTHEW_REPO_NAME: scope.repoName,
+        ...(scope.repoRoot ? { ASKTHEW_REPO_ROOT: scope.repoRoot } : {}),
+        ...(scope.appPath ? { ASKTHEW_APP_PATH: scope.appPath } : {}),
+        ...(scope.serviceName ? { ASKTHEW_SERVICE_NAME: scope.serviceName } : {}),
+    };
+    if (input.serverEntrypoint) {
+        return {
+            command: "node",
+            args: [path.resolve(input.serverEntrypoint)],
+            env,
+        };
+    }
     return {
         command: "npx",
-        args: ["-y", "--prefer-online", "--package", "@askthew/mcp-plugin@latest", "askthew-mcp"],
-        env: {
-            ASKTHEW_API_URL: input.apiUrl,
-            ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
-            ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
-            ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
-            ASKTHEW_HOST_TYPE: input.hostType,
-            ASKTHEW_SERVER_NAME: input.serverName,
-            ASKTHEW_REPO_NAME: scope.repoName,
-            ...(scope.repoRoot ? { ASKTHEW_REPO_ROOT: scope.repoRoot } : {}),
-            ...(scope.appPath ? { ASKTHEW_APP_PATH: scope.appPath } : {}),
-            ...(scope.serviceName ? { ASKTHEW_SERVICE_NAME: scope.serviceName } : {}),
-        },
+        args: ["-y", "--package", packageSpecFromPin(), "askthew-mcp"],
+        env,
     };
 }
 export function createHostConfigSnippet(input) {
@@ -81,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 : {};
@@ -96,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,
@@ -117,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,
@@ -150,6 +251,9 @@ export function formatInstallCommand(input) {
             parts.push("--email", JSON.stringify(input.email));
         }
     }
+    if (input.serverEntrypoint) {
+        parts.push("--server-entrypoint", JSON.stringify(input.serverEntrypoint));
+    }
     return parts.join(" ");
 }
 export function verificationNextStep(hostType) {
@@ -188,6 +292,7 @@ export function installHostConfig(input) {
         clientLabel: input.clientLabel,
         free: input.free,
         cwd: input.cwd,
+        serverEntrypoint: input.serverEntrypoint,
     };
     const json = input.hostType === "codex"
         ? mergeCodexSettings({
@@ -211,12 +316,74 @@ export function installHostConfig(input) {
         nextStep: verificationNextStep(input.hostType),
     };
 }
+function normalizeInstructionPaths(paths) {
+    return Array.from(new Set(paths.map((entry) => path.resolve(entry))));
+}
+function normalizeReceipt(receipt) {
+    return {
+        ...receipt,
+        settingsPath: path.resolve(receipt.settingsPath),
+        cwd: path.resolve(receipt.cwd),
+        instructionPaths: normalizeInstructionPaths(receipt.instructionPaths ?? []),
+        dataDir: path.resolve(receipt.dataDir || askTheWDataDir()),
+        serverEntrypoint: receipt.serverEntrypoint ? path.resolve(receipt.serverEntrypoint) : undefined,
+    };
+}
+function receiptKey(receipt) {
+    return `${receipt.hostType}\u0000${receipt.serverName}\u0000${path.resolve(receipt.cwd)}`;
+}
+export function readInstallReceipts(env = process.env) {
+    const parsed = readJsonFile(installReceiptsPath(env));
+    if (!parsed || parsed.schemaVersion !== INSTALL_RECEIPTS_SCHEMA_VERSION || !Array.isArray(parsed.installs)) {
+        return [];
+    }
+    return parsed.installs
+        .filter((receipt) => Boolean(receipt?.hostType && receipt.serverName && receipt.settingsPath && receipt.cwd))
+        .map(normalizeReceipt);
+}
+export function writeInstallReceipt(receipt, env = process.env) {
+    const nextReceipt = normalizeReceipt({
+        ...receipt,
+        dataDir: receipt.dataDir ?? askTheWDataDir(env),
+        installedAt: receipt.installedAt ?? new Date().toISOString(),
+    });
+    const receipts = readInstallReceipts(env).filter((entry) => receiptKey(entry) !== receiptKey(nextReceipt));
+    receipts.push(nextReceipt);
+    receipts.sort((left, right) => left.installedAt.localeCompare(right.installedAt));
+    writePrivateJson(installReceiptsPath(env), {
+        schemaVersion: INSTALL_RECEIPTS_SCHEMA_VERSION,
+        installs: receipts,
+    });
+    return nextReceipt;
+}
+export function findInstallReceipts(input, env = process.env) {
+    return readInstallReceipts(env).filter((receipt) => receipt.hostType === input.hostType &&
+        (!input.serverName || receipt.serverName === input.serverName));
+}
+export function removeInstallReceipts(input, env = process.env) {
+    const cwd = input.cwd ? path.resolve(input.cwd) : undefined;
+    const receipts = readInstallReceipts(env);
+    const next = receipts.filter((receipt) => {
+        if (receipt.hostType !== input.hostType)
+            return true;
+        if (input.serverName && receipt.serverName !== input.serverName)
+            return true;
+        if (cwd && receipt.cwd !== cwd)
+            return true;
+        return false;
+    });
+    writePrivateJson(installReceiptsPath(env), {
+        schemaVersion: INSTALL_RECEIPTS_SCHEMA_VERSION,
+        installs: next,
+    });
+    return receipts.length - next.length;
+}
 export function uninstallHostConfig(input) {
     const settingsPath = resolveSettingsPath({
         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;
@@ -224,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`;
@@ -272,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());
@@ -348,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",
@@ -355,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,
         "",
@@ -372,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`;
@@ -419,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/paths.d.ts

@@ -1,8 +1,10 @@
 export declare function askTheWDataDir(env?: NodeJS.ProcessEnv): string;
+export declare function askTheWStateDir(env?: NodeJS.ProcessEnv): string;
 export declare function ensureAskTheWDataDir(env?: NodeJS.ProcessEnv): string;
 export declare function localStorePath(env?: NodeJS.ProcessEnv): string;
 export declare function identityPath(env?: NodeJS.ProcessEnv): string;
 export declare function configPath(env?: NodeJS.ProcessEnv): string;
 export declare function jsonFallbackStorePath(env?: NodeJS.ProcessEnv): string;
+export declare function installReceiptsPath(env?: NodeJS.ProcessEnv): string;
 export declare function writePrivateJson(filePath: string, value: unknown): void;
 export declare function readJsonFile<T>(filePath: string): T | null;

package/dist/lib/paths.js

@@ -12,6 +12,17 @@ export function askTheWDataDir(env = process.env) {
     }
     return path.join(os.homedir(), ".askthew");
 }
+export function askTheWStateDir(env = process.env) {
+    const explicit = env.ASKTHEW_STATE_DIR?.trim();
+    if (explicit) {
+        return path.resolve(explicit);
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome) {
+        return path.join(path.resolve(xdgStateHome), "askthew");
+    }
+    return path.join(os.homedir(), ".local", "state", "askthew");
+}
 export function ensureAskTheWDataDir(env = process.env) {
     const dir = askTheWDataDir(env);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -29,6 +40,9 @@ export function configPath(env = process.env) {
 export function jsonFallbackStorePath(env = process.env) {
     return path.join(askTheWDataDir(env), "store.json");
 }
+export function installReceiptsPath(env = process.env) {
+    return path.join(askTheWStateDir(env), "install-receipts.json");
+}
 export function writePrivateJson(filePath, value) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
     fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });

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.7",
+  "version": "0.4.9",
   "private": false,
   "description": "Ask The W plugin connector for local-first coding-agent decisions, signals, and review.",
   "type": "module",