@askthew/mcp-plugin 0.4.0 → 0.4.2

package/dist/index.test.js

@@ -1,8 +1,113 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { codingSessionSignalSchema, createAskTheWMcpServer, normalizeInstallTokenInput, redactCodingSessionSignal, redactProvenanceSignal, } from "./index.js";
+import { LocalStore } from "./lib/local-store.js";
+import { credentialsPath, writePrivateJson } from "./lib/paths.js";
+function toolResultJson(result) {
+    return JSON.parse(result.content[0].text);
+}
+async function withFreeEnv(fn) {
+    const previous = {
+        ASKTHEW_CLI_TOKEN: process.env.ASKTHEW_CLI_TOKEN,
+        ASKTHEW_USER_ID: process.env.ASKTHEW_USER_ID,
+        ASKTHEW_CLI_TOKEN_ID: process.env.ASKTHEW_CLI_TOKEN_ID,
+        ASKTHEW_DATA_DIR: process.env.ASKTHEW_DATA_DIR,
+        ASKTHEW_INSTALL_TOKEN: process.env.ASKTHEW_INSTALL_TOKEN,
+        ASKTHEW_FREE_MODE: process.env.ASKTHEW_FREE_MODE,
+    };
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-free-tools-"));
+    process.env.ASKTHEW_CLI_TOKEN = "cli_free_token";
+    process.env.ASKTHEW_USER_ID = "local-user";
+    process.env.ASKTHEW_CLI_TOKEN_ID = "cli-token-id";
+    process.env.ASKTHEW_DATA_DIR = dataDir;
+    delete process.env.ASKTHEW_INSTALL_TOKEN;
+    delete process.env.ASKTHEW_FREE_MODE;
+    try {
+        return await fn();
+    }
+    finally {
+        for (const [key, value] of Object.entries(previous)) {
+            if (value === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = value;
+            }
+        }
+        fs.rmSync(dataDir, { recursive: true, force: true });
+    }
+}
+async function withPendingFreeEnv(fn) {
+    const previous = {
+        ASKTHEW_CLI_TOKEN: process.env.ASKTHEW_CLI_TOKEN,
+        ASKTHEW_USER_ID: process.env.ASKTHEW_USER_ID,
+        ASKTHEW_CLI_TOKEN_ID: process.env.ASKTHEW_CLI_TOKEN_ID,
+        ASKTHEW_DATA_DIR: process.env.ASKTHEW_DATA_DIR,
+        ASKTHEW_INSTALL_TOKEN: process.env.ASKTHEW_INSTALL_TOKEN,
+        ASKTHEW_FREE_MODE: process.env.ASKTHEW_FREE_MODE,
+    };
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-pending-free-tools-"));
+    process.env.ASKTHEW_FREE_MODE = "1";
+    process.env.ASKTHEW_DATA_DIR = dataDir;
+    delete process.env.ASKTHEW_CLI_TOKEN;
+    delete process.env.ASKTHEW_USER_ID;
+    delete process.env.ASKTHEW_CLI_TOKEN_ID;
+    delete process.env.ASKTHEW_INSTALL_TOKEN;
+    try {
+        return await fn();
+    }
+    finally {
+        for (const [key, value] of Object.entries(previous)) {
+            if (value === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = value;
+            }
+        }
+        fs.rmSync(dataDir, { recursive: true, force: true });
+    }
+}
+async function withInstalledFreeEnv(fn) {
+    const previous = {
+        ASKTHEW_CLI_TOKEN: process.env.ASKTHEW_CLI_TOKEN,
+        ASKTHEW_USER_ID: process.env.ASKTHEW_USER_ID,
+        ASKTHEW_CLI_TOKEN_ID: process.env.ASKTHEW_CLI_TOKEN_ID,
+        ASKTHEW_DATA_DIR: process.env.ASKTHEW_DATA_DIR,
+        ASKTHEW_INSTALL_TOKEN: process.env.ASKTHEW_INSTALL_TOKEN,
+        ASKTHEW_FREE_MODE: process.env.ASKTHEW_FREE_MODE,
+    };
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-installed-free-tools-"));
+    process.env.ASKTHEW_FREE_MODE = "1";
+    process.env.ASKTHEW_DATA_DIR = dataDir;
+    delete process.env.ASKTHEW_CLI_TOKEN;
+    delete process.env.ASKTHEW_USER_ID;
+    delete process.env.ASKTHEW_CLI_TOKEN_ID;
+    delete process.env.ASKTHEW_INSTALL_TOKEN;
+    writePrivateJson(credentialsPath(), {
+        email: "ymtest89+test5@gmail.com",
+        userId: "local-user",
+        cliToken: "cli_free_token",
+        cliTokenId: "cli-token-id",
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        for (const [key, value] of Object.entries(previous)) {
+            if (value === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = value;
+            }
+        }
+        fs.rmSync(dataDir, { recursive: true, force: true });
+    }
+}
 test("install token normalization accepts copied shell-quoted values", () => {
     assert.equal(normalizeInstallTokenInput("'atw_mcp_token'"), "atw_mcp_token");
     assert.equal(normalizeInstallTokenInput('"atw_mcp_token"'), "atw_mcp_token");
@@ -38,6 +143,19 @@ test("coding session signal redaction removes obvious secrets", () => {
     assert.match(redacted.commandsRun[0] ?? "", /\[REDACTED\]/);
     assert.deepEqual(redacted.metadata, { nested: { token: "[REDACTED]" } });
 });
+test("capture redactor catches documented capture-path patterns", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 11,
+        kind: "session_checkpoint",
+        summary: "OPENAI_API_KEY=sk-proj_abcdefghijklmnopqrstuvwxyz123456 Bearer abc.def-ghi user@example.com AKIA1234567890ABCDEF eyJabcdefghijklmnopqrstuv.abcdefghijklmnopqrstuv.abcdefghijklmnopqrstuv",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: [],
+        metadata: {},
+    });
+    assert.equal(redacted.summary, "[REDACTED] [REDACTED] [REDACTED] [REDACTED] [REDACTED]");
+});
 test("redacts ATW hyphen-segmented install tokens in commands", () => {
     const redacted = redactCodingSessionSignal({
         sessionId: "session-1",
@@ -168,6 +286,13 @@ test("happy-path MCP source exposes capture_session_signal and v1 API tools", ()
         "create_decision",
         "update_decision",
         "delete_decision",
+        "review_decisions",
+        "review_session",
+        "recap",
+        "coach",
+        "promote_signal_to_decision",
+        "list_decision_candidates",
+        "search_trail",
         "list_outcomes",
         "get_outcome",
         "list_outcome_signals",
@@ -178,6 +303,7 @@ test("happy-path MCP source exposes capture_session_signal and v1 API tools", ()
         "update_north_star",
         "list_signals",
         "get_signal",
+        "find_signal_by_summary",
     ]) {
         assert.match(source, new RegExp(`"${toolName}"`));
     }
@@ -187,6 +313,65 @@ test("happy-path MCP source exposes capture_session_signal and v1 API tools", ()
     assert.doesNotMatch(source, /server\.tool\(\s*"get_session_decisions"/);
     assert.doesNotMatch(source, /server\.tool\(\s*"link_outcome"/);
     assert.doesNotMatch(source, /server\.tool\(\s*"get_decision_feed"/);
+    assert.doesNotMatch(source, /server\.tool\(\s*"analyze_session"/);
+});
+test("schema-handler contract registers every documented MCP tool", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const tools = server._registeredTools;
+        const expected = [
+            "capture_session_signal",
+            "list_signals",
+            "get_signal",
+            "find_signal_by_summary",
+            "list_decisions",
+            "get_decision",
+            "create_decision",
+            "update_decision",
+            "delete_decision",
+            "review_decisions",
+            "review_session",
+            "view_timeline",
+            "recap",
+            "coach",
+            "promote_signal_to_decision",
+            "list_decision_candidates",
+            "search_trail",
+            "list_outcomes",
+            "get_outcome",
+            "list_outcome_signals",
+            "create_outcome",
+            "update_outcome",
+            "delete_outcome",
+            "get_north_star",
+            "update_north_star",
+            "export_decisions",
+        ];
+        for (const toolName of expected) {
+            assert.equal(typeof tools[toolName]?.handler, "function", `${toolName} handler`);
+            assert.ok(tools[toolName]?.inputSchema, `${toolName} schema`);
+        }
+    });
+});
+test("every write tool accepts an idempotency key parameter", () => {
+    const source = fs.readFileSync(path.resolve(process.cwd(), "src/index.ts"), "utf8");
+    for (const toolName of [
+        "capture_session_signal",
+        "create_decision",
+        "update_decision",
+        "delete_decision",
+        "create_outcome",
+        "update_outcome",
+        "delete_outcome",
+        "update_north_star",
+        "promote_signal_to_decision",
+    ]) {
+        const start = source.indexOf(`"${toolName}"`);
+        assert.notEqual(start, -1, `${toolName} registered`);
+        const nextTool = source.indexOf("server.tool(", start + 1);
+        const block = source.slice(start, nextTool === -1 ? undefined : nextTool);
+        assert.match(block, /idempotencyKey/, `${toolName} idempotencyKey`);
+    }
 });
 test("v1 API MCP tools dispatch to expected HTTP routes with install-token auth", async () => {
     const calls = [];
@@ -213,21 +398,22 @@ test("v1 API MCP tools dispatch to expected HTTP routes with install-token auth"
     });
     const tools = server._registeredTools;
     const cases = [
-        { name: "list_decisions", payload: { limit: 5, cursor: "c1" }, method: "GET", path: "/api/decisions?limit=5&cursor=c1" },
+        { name: "list_decisions", payload: { limit: 5, cursor: "c1" }, method: "GET", path: "/api/decisions?limit=5&cursor=c1&compact=true&max_chars=8000" },
         { name: "get_decision", payload: { id: "d1" }, method: "GET", path: "/api/decisions/d1" },
-        { name: "create_decision", payload: { content: "Adopt Bun" }, method: "POST", path: "/api/decisions" },
-        { name: "update_decision", payload: { id: "d1", headline: "Adopt Bun v2" }, method: "PATCH", path: "/api/decisions/d1" },
+        { name: "create_decision", payload: { content: "Adopt Bun", idempotencyKey: "idem-create" }, method: "POST", path: "/api/decisions?response_shape=v2" },
+        { name: "update_decision", payload: { id: "d1", headline: "Adopt Bun v2", idempotencyKey: "idem-update" }, method: "PATCH", path: "/api/decisions/d1?response_shape=v2" },
         { name: "delete_decision", payload: { id: "d1", confirmText: "Adopt Bun v2" }, method: "DELETE", path: "/api/decisions/d1" },
         { name: "list_outcomes", payload: { limit: 10 }, method: "GET", path: "/api/outcomes?limit=10" },
         { name: "get_outcome", payload: { id: "o1" }, method: "GET", path: "/api/outcomes/o1" },
         { name: "list_outcome_signals", payload: { id: "o1" }, method: "GET", path: "/api/outcomes/o1/signals" },
         { name: "create_outcome", payload: { name: "Reduce churn" }, method: "POST", path: "/api/outcomes" },
-        { name: "update_outcome", payload: { id: "o1", summary: "New summary" }, method: "PATCH", path: "/api/outcomes/o1" },
+        { name: "update_outcome", payload: { id: "o1", summary: "New summary", idempotencyKey: "idem-outcome" }, method: "PATCH", path: "/api/outcomes/o1?response_shape=v2" },
         { name: "delete_outcome", payload: { id: "o1", confirmText: "Reduce churn" }, method: "DELETE", path: "/api/outcomes/o1" },
         { name: "get_north_star", payload: {}, method: "GET", path: "/api/north-star" },
         { name: "update_north_star", payload: { metric: "Active users", current: "10", target: "100", reason: "API smoke" }, method: "POST", path: "/api/north-star" },
-        { name: "list_signals", payload: { limit: 25, cursor: "2026-01-01T00:00:00.000Z" }, method: "GET", path: "/api/signals?limit=25&cursor=2026-01-01T00%3A00%3A00.000Z" },
+        { name: "list_signals", payload: { limit: 25, cursor: "2026-01-01T00:00:00.000Z" }, method: "GET", path: "/api/signals?limit=25&cursor=2026-01-01T00%3A00%3A00.000Z&compact=true&max_chars=8000" },
         { name: "get_signal", payload: { id: "s1" }, method: "GET", path: "/api/signals/s1" },
+        { name: "find_signal_by_summary", payload: { query: "adopt", limit: 5 }, method: "GET", path: "/api/signals?query=adopt&limit=5&compact=true&max_chars=8000" },
     ];
     for (const entry of cases) {
         assert.ok(tools[entry.name], `${entry.name} should be registered`);
@@ -240,6 +426,7 @@ test("v1 API MCP tools dispatch to expected HTTP routes with install-token auth"
         assert.equal(call.url, `https://askthew.example.com${entry.path}`);
         assert.deepEqual(call.headers, {
             ...(entry.method === "GET" ? {} : { "Content-Type": "application/json" }),
+            ...(entry.payload.idempotencyKey ? { "Idempotency-Key": entry.payload.idempotencyKey } : {}),
             Authorization: "Bearer atw_mcp_tools",
         });
         if (entry.method !== "GET") {
@@ -266,6 +453,25 @@ test("v1 API MCP tools return server errors as JSON text", async () => {
     assert.equal(parsed.status, 500);
     assert.equal(parsed.code, "nope");
 });
+test("compact write tools relay upstream errors instead of pretending success", async () => {
+    const server = createAskTheWMcpServer({
+        apiBaseUrl: "https://askthew.example.com",
+        sendStartupHeartbeat: false,
+        credentials: {
+            installToken: "atw_mcp_tools",
+            clientId: "codex",
+        },
+        fetchImpl: (async () => new Response(JSON.stringify({ ok: false, code: "invalid_input", field: "content", hint: "Provide content." }), {
+            status: 422,
+        })),
+    });
+    const result = await server._registeredTools.create_decision.handler({ content: " " });
+    const parsed = toolResultJson(result);
+    assert.equal(parsed.ok, false);
+    assert.equal(parsed.status, 422);
+    assert.equal(parsed.code, "invalid_input");
+    assert.equal(parsed.field, "content");
+});
 test("createAskTheWMcpServer sends startup heartbeat and automated setup signal", async () => {
     const calls = [];
     createAskTheWMcpServer({
@@ -341,9 +547,406 @@ test("createAskTheWMcpServer accepts hosted connector identity overrides", async
         commandsRun: [],
         metadata: {},
     });
-    assert.equal(calls[0]?.url, "https://askthew.example.com/api/ingest/mcp");
+    assert.equal(calls[0]?.url, "https://askthew.example.com/api/ingest/mcp?response_shape=v2");
     assert.equal(calls[0]?.body.installToken, "atw_mcp_remote");
     assert.equal(calls[0]?.body.clientId, "claude_remote");
     assert.equal(calls[0]?.body.clientLabel, "Claude Desktop / Cowork");
     assert.equal(calls[0]?.body.sessionSignal.metadata.connector_mode, "remote_mcp");
 });
+test("free capture defaults to compact response and echo full returns full local payload", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const capture = server._registeredTools.capture_session_signal;
+        const basePayload = {
+            sessionId: "session-compact",
+            sequence: 1,
+            kind: "implementation_update",
+            summary: "Updated compact response shape.",
+            evidence: [],
+            filesTouched: ["src/index.ts"],
+            commandsRun: ["npm test"],
+            metadata: {},
+        };
+        const compact = toolResultJson(await capture.handler(basePayload));
+        assert.equal(compact.ok, true);
+        assert.equal(compact.sessionId, "session-compact");
+        assert.equal(compact.sequence, 1);
+        assert.equal(typeof compact.id, "number");
+        assert.ok(JSON.stringify(compact).length < 1024);
+        assert.equal("signal" in compact, false);
+        const full = toolResultJson(await capture.handler({ ...basePayload, sequence: 2, echo: "full" }));
+        assert.equal(full.ok, true);
+        assert.equal(full.signal.summary, "Updated compact response shape.");
+        assert.equal(full.signal.sessionId, "session-compact");
+    });
+});
+test("stale free install without identity self-heals into local capture without hosted workspace calls", async () => {
+    await withPendingFreeEnv(async () => {
+        const calls = [];
+        const server = createAskTheWMcpServer({
+            apiBaseUrl: "https://askthew.example.com",
+            fetchImpl: async (url) => {
+                calls.push({ url: String(url) });
+                return new Response(JSON.stringify({ ok: true }), { status: 200 });
+            },
+        });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        const tools = server._registeredTools;
+        const capture = toolResultJson(await tools.capture_session_signal.handler({
+            sessionId: "session-pending",
+            sequence: 1,
+            kind: "setup_complete",
+            summary: "Stale free install should capture locally.",
+            evidence: [],
+            filesTouched: [],
+            commandsRun: [],
+            metadata: {},
+        }));
+        assert.equal(capture.ok, true);
+        assert.equal(capture.id, 1);
+        assert.equal(calls.length, 1);
+        assert.match(calls[0].url, /\/api\/cli\/v1\/free-installs\/register$/);
+        const store = LocalStore.open();
+        try {
+            const stats = store.stats();
+            assert.equal(stats.signals, 1);
+            assert.equal(stats.decisions, 0);
+        }
+        finally {
+            store.close();
+        }
+    });
+});
+test("authenticated free mode keeps capture, decisions, and review local without hosted calls", async () => {
+    await withFreeEnv(async () => {
+        const calls = [];
+        const server = createAskTheWMcpServer({
+            apiBaseUrl: "https://askthew.example.com",
+            fetchImpl: async (url) => {
+                calls.push({ url: String(url) });
+                return new Response(JSON.stringify({ ok: true }), { status: 200 });
+            },
+        });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        const tools = server._registeredTools;
+        const capture = toolResultJson(await tools.capture_session_signal.handler({
+            sessionId: "session-local-only",
+            sequence: 1,
+            kind: "implementation_update",
+            summary: "Captured locally after free auth.",
+            evidence: [],
+            filesTouched: ["packages/mcp-plugin/src/index.ts"],
+            commandsRun: [],
+            metadata: {},
+        }));
+        const decision = toolResultJson(await tools.create_decision.handler({ content: "Keep free mode local-only." }));
+        const review = toolResultJson(await tools.review_session.handler({ sessionId: "session-local-only", format: "json" }));
+        assert.equal(capture.ok, true);
+        assert.match(decision.id, /^d_/);
+        assert.equal(review.ok, true);
+        assert.equal(calls.length, 0);
+        const store = LocalStore.open();
+        try {
+            const stats = store.stats();
+            assert.equal(stats.signals, 1);
+            assert.equal(stats.decisions, 1);
+        }
+        finally {
+            store.close();
+        }
+    });
+});
+test("installed free mode with credential file captures locally even if hosted app would return local-only 403", async () => {
+    await withInstalledFreeEnv(async () => {
+        const calls = [];
+        const server = createAskTheWMcpServer({
+            apiBaseUrl: "https://askthew.example.com",
+            fetchImpl: async (url) => {
+                calls.push({ url: String(url) });
+                return new Response(JSON.stringify({
+                    ok: false,
+                    code: "local_only_free_feature",
+                    message: "This free MCP token is local-only and cannot read or write the shared Ask The W workspace.",
+                }), { status: 403 });
+            },
+        });
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        const tools = server._registeredTools;
+        const capture = toolResultJson(await tools.capture_session_signal.handler({
+            sessionId: "session-installed-free",
+            sequence: 1,
+            kind: "setup_complete",
+            summary: "Installed free mode should write this locally.",
+            evidence: [],
+            filesTouched: [],
+            commandsRun: [],
+            metadata: {},
+        }));
+        assert.equal(capture.ok, true);
+        assert.equal(capture.sessionId, "session-installed-free");
+        assert.equal("code" in capture, false);
+        assert.equal(JSON.stringify(capture).includes("local_only_free_feature"), false);
+        assert.equal(calls.length, 0);
+        const store = LocalStore.open();
+        try {
+            const signals = store.listSignals({ sessionId: "session-installed-free", limit: 10 });
+            assert.equal(signals.length, 1);
+            assert.equal(signals[0]?.summary, "Installed free mode should write this locally.");
+        }
+        finally {
+            store.close();
+        }
+    });
+});
+test("free decisions, recap, coach, and promote return human-readable compact outputs", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const tools = server._registeredTools;
+        await tools.capture_session_signal.handler({
+            sessionId: "session-free",
+            sequence: 1,
+            kind: "implementation_update",
+            summary: "Implemented the trial onboarding CTA.",
+            evidence: [],
+            filesTouched: ["apps/app/page.tsx"],
+            commandsRun: [],
+            metadata: {},
+        });
+        await tools.capture_session_signal.handler({
+            sessionId: "session-free",
+            sequence: 2,
+            kind: "verification_result",
+            summary: "npm test passed.",
+            evidence: [],
+            filesTouched: ["apps/app/page.tsx"],
+            commandsRun: ["npm test"],
+            metadata: {},
+        });
+        const created = toolResultJson(await tools.create_decision.handler({ content: "Keep the direct onboarding CTA." }));
+        assert.equal(created.ok, true);
+        assert.match(created.id, /^d_/);
+        assert.equal(created.sequence, 1);
+        const promoted = toolResultJson(await tools.promote_signal_to_decision.handler({ signalId: 1, status: "committed", why: "The captured implementation signal explains the change." }));
+        assert.equal(promoted.ok, true);
+        assert.equal(promoted.linkedSignalId, 1);
+        assert.equal(promoted.decision.rawContent, "Implemented the trial onboarding CTA.");
+        assert.deepEqual(promoted.decision.sourceSignalIds, [1]);
+        const digest = toolResultJson(await tools.recap.handler({ format: "digest" }));
+        const standup = toolResultJson(await tools.recap.handler({ format: "standup" }));
+        const share = toolResultJson(await tools.recap.handler({ format: "share" }));
+        assert.notEqual(digest.rendered, standup.rendered);
+        assert.notEqual(standup.rendered, share.rendered);
+        const coach = toolResultJson(await tools.coach.handler({ scope: "session" }));
+        assert.equal(coach.ok, true);
+        assert.equal(typeof coach.qualityScore, "number");
+        assert.match(coach.biggestGap, /\w/);
+        for (const scope of ["week", "patterns"]) {
+            const response = toolResultJson(await tools.coach.handler({ scope }));
+            assert.equal(response.ok, false);
+            assert.equal(response.code, "free_tier_paid_feature");
+            assert.equal(response.tool, "coach");
+            assert.match(response.upgradeUrl, /askthew\.com\/mcp/);
+        }
+    });
+});
+test("free local tools surface decision candidates, compact views, search, traversal, conflicts, and max_chars", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const tools = server._registeredTools;
+        const captured = toolResultJson(await tools.capture_session_signal.handler({
+            sessionId: "session-candidates",
+            sequence: 1,
+            kind: "direction_change",
+            summary: "Let's go with token-budgeted local search because recap output is too large.",
+            evidence: [{
+                    role: "assistant",
+                    kind: "diff",
+                    excerpt: "Changed search behavior.",
+                    diff: "- old recap only\n+ new local search",
+                }],
+            filesTouched: ["packages/mcp-plugin/src/index.ts"],
+            commandsRun: [],
+            metadata: {},
+        }));
+        const candidates = toolResultJson(await tools.list_decision_candidates.handler({ sessionId: "session-candidates" }));
+        assert.equal(candidates.ok, true);
+        assert.equal(candidates.decisionCandidates.length, 1);
+        assert.equal(candidates.decisionCandidates[0].signalId, captured.id);
+        const promoted = toolResultJson(await tools.promote_signal_to_decision.handler({
+            signalId: captured.id,
+            status: "committed",
+            why: "The direction change has the rationale.",
+        }));
+        assert.equal(promoted.ok, true);
+        assert.equal(promoted.decision.contributingSignals[0].id, captured.id);
+        assert.equal(Boolean(promoted.decision.committedAt), true);
+        const signal = toolResultJson(await tools.get_signal.handler({ id: String(captured.id) }));
+        assert.equal(signal.signal.decision.id, promoted.id);
+        const decision = toolResultJson(await tools.get_decision.handler({ id: promoted.id }));
+        assert.equal(decision.decision.contributingSignals[0].id, captured.id);
+        const compact = toolResultJson(await tools.list_signals.handler({ sessionId: "session-candidates", compact: true }));
+        assert.deepEqual(Object.keys(compact.signals[0]).sort(), ["decisionId", "files", "id", "kind", "summary"]);
+        const found = toolResultJson(await tools.find_signal_by_summary.handler({ query: "token-budgeted" }));
+        assert.equal(found.ok, true);
+        assert.equal(found.signals[0].id, captured.id);
+        const search = toolResultJson(await tools.search_trail.handler({ query: "local search", compact: true }));
+        assert.equal(search.ok, true);
+        assert.equal(search.matches.length >= 1, true);
+        const conflict = toolResultJson(await tools.create_decision.handler({
+            content: "Drop token-budgeted local search.",
+        }));
+        assert.equal(conflict.ok, true);
+        assert.equal(conflict.warnings[0].code, "possible_conflict");
+        assert.equal(conflict.warnings[0].conflictingDecisionId, promoted.id);
+        const budgeted = toolResultJson(await tools.review_session.handler({
+            sessionId: "session-candidates",
+            format: "json",
+            max_chars: 500,
+        }));
+        assert.equal(budgeted.ok, true);
+        assert.equal(budgeted.truncated, true);
+        assert.equal(JSON.stringify(budgeted, null, 2).length <= 700, true);
+    });
+});
+test("free-tier smoke covers every free tool without overflow or silent failures", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const tools = server._registeredTools;
+        const results = {};
+        const capture = toolResultJson(await tools.capture_session_signal.handler({
+            sessionId: "session-smoke",
+            sequence: 1,
+            kind: "implementation_update",
+            summary: "Implemented every free tool smoke path.",
+            evidence: [],
+            filesTouched: ["packages/mcp-plugin/src/index.ts"],
+            commandsRun: ["npm test --workspace @askthew/mcp-plugin"],
+            metadata: {},
+        }));
+        results.capture_session_signal = capture;
+        assert.equal(capture.ok, true);
+        results.list_signals = toolResultJson(await tools.list_signals.handler({ limit: 10 }));
+        assert.equal(results.list_signals.ok, true);
+        assert.equal(results.list_signals.signals.length, 1);
+        results.get_signal = toolResultJson(await tools.get_signal.handler({ id: String(capture.id) }));
+        assert.equal(results.get_signal.ok, true);
+        assert.equal(results.get_signal.signal.summary, "Implemented every free tool smoke path.");
+        const created = toolResultJson(await tools.create_decision.handler({ content: "Keep free-tool smoke coverage explicit.", echo: "summary" }));
+        results.create_decision = created;
+        assert.equal(created.ok, true);
+        assert.match(created.id, /^d_/);
+        results.get_decision = toolResultJson(await tools.get_decision.handler({ id: created.id }));
+        assert.equal(results.get_decision.ok, true);
+        results.update_decision = toolResultJson(await tools.update_decision.handler({
+            id: created.id,
+            headline: "Keep free-tool smoke coverage explicit",
+            why: "Acceptance requires every free tool to run.",
+            status: "committed",
+            echo: "summary",
+        }));
+        assert.equal(results.update_decision.ok, true);
+        results.list_decisions = toolResultJson(await tools.list_decisions.handler({ limit: 10 }));
+        assert.equal(results.list_decisions.ok, true);
+        assert.equal(results.list_decisions.decisions.length >= 1, true);
+        results.review_decisions = toolResultJson(await tools.review_decisions.handler({ format: "markdown", limit: 10 }));
+        assert.equal(results.review_decisions.ok, true);
+        assert.match(results.review_decisions.rendered, /# Decisions/);
+        results.review_session = toolResultJson(await tools.review_session.handler({ sessionId: "session-smoke", format: "markdown" }));
+        assert.equal(results.review_session.ok, true);
+        assert.match(results.review_session.rendered, /Session Review/);
+        results.view_timeline = toolResultJson(await tools.view_timeline.handler({ scope: "session" }));
+        assert.equal(results.view_timeline.ok, true);
+        assert.equal(results.view_timeline.points.some((point) => point.x === "Other"), false);
+        results.recap = toolResultJson(await tools.recap.handler({ sessionId: "session-smoke", format: "digest" }));
+        assert.equal(results.recap.ok, true);
+        assert.match(results.recap.rendered, /Session Digest/);
+        results.coach = toolResultJson(await tools.coach.handler({ sessionId: "session-smoke", scope: "session" }));
+        assert.equal(results.coach.ok, true);
+        assert.match(results.coach.rendered, /Decision quality score/);
+        results.promote_signal_to_decision = toolResultJson(await tools.promote_signal_to_decision.handler({
+            signalId: capture.id,
+            status: "committed",
+            why: "The signal records the implementation.",
+        }));
+        assert.equal(results.promote_signal_to_decision.ok, true);
+        assert.equal(results.promote_signal_to_decision.linkedSignalId, capture.id);
+        results.delete_decision = toolResultJson(await tools.delete_decision.handler({
+            id: created.id,
+            confirmText: created.id,
+        }));
+        assert.equal(results.delete_decision.ok, true);
+        for (const [toolName, result] of Object.entries(results)) {
+            assert.equal(result.ok, true, toolName);
+            assert.equal(JSON.stringify(result).length < 15000, true, `${toolName} should stay compact`);
+        }
+    });
+});
+test("free review_session markdown is capped and json is cursor-paginated with a 3-session limit", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const tools = server._registeredTools;
+        for (let sessionIndex = 1; sessionIndex <= 4; sessionIndex += 1) {
+            for (let sequence = 1; sequence <= 55; sequence += 1) {
+                await tools.capture_session_signal.handler({
+                    sessionId: `session-${sessionIndex}`,
+                    sequence,
+                    kind: sequence % 5 === 0 ? "verification_result" : "session_checkpoint",
+                    summary: `Signal ${sequence} for session ${sessionIndex}`,
+                    evidence: [],
+                    filesTouched: [],
+                    commandsRun: [],
+                    metadata: {},
+                });
+            }
+        }
+        const markdown = toolResultJson(await tools.review_session.handler({ sessionId: "session-4", format: "markdown" }));
+        assert.equal(markdown.ok, true);
+        assert.equal(markdown.rendered.split("\n").length <= 300, true);
+        assert.match(markdown.rendered, /Signals By Kind/);
+        assert.equal("signals" in markdown, false);
+        const json = toolResultJson(await tools.review_session.handler({ sessionId: "session-4", format: "json" }));
+        assert.equal(json.ok, true);
+        assert.equal(json.signals.length, 50);
+        assert.equal(typeof json.nextCursor, "string");
+        const capped = toolResultJson(await tools.review_session.handler({ sessionId: "session-1", format: "markdown" }));
+        assert.equal(capped.ok, false);
+        assert.equal(capped.code, "free_tier_limit");
+        assert.equal(capped.limit, 3);
+        assert.match(capped.upgradeUrl, /askthew\.com\/mcp/);
+    });
+});
+test("paid tools return canonical paywall envelope before transport in free mode", async () => {
+    await withFreeEnv(async () => {
+        const server = createAskTheWMcpServer({ sendStartupHeartbeat: false });
+        const tools = server._registeredTools;
+        for (const toolName of [
+            "list_outcomes",
+            "get_outcome",
+            "list_outcome_signals",
+            "create_outcome",
+            "update_outcome",
+            "delete_outcome",
+            "get_north_star",
+            "update_north_star",
+            "export_decisions",
+        ]) {
+            const payload = toolName === "get_outcome" || toolName === "list_outcome_signals"
+                ? { id: "o1" }
+                : toolName === "create_outcome"
+                    ? { name: "Reduce churn" }
+                    : toolName === "update_outcome"
+                        ? { id: "o1", summary: "New" }
+                        : toolName === "delete_outcome"
+                            ? { id: "o1", confirmText: "Reduce churn" }
+                            : toolName === "update_north_star"
+                                ? { metric: "Active users", current: "1", target: "10", reason: "test" }
+                                : {};
+            const response = toolResultJson(await tools[toolName].handler(payload));
+            assert.equal(response.ok, false, toolName);
+            assert.equal(response.code, "free_tier_paid_feature", toolName);
+            assert.equal(response.tool, toolName, toolName);
+            assert.match(response.upgradeUrl, /askthew\.com\/mcp/, toolName);
+            assert.equal(response.supportEmail, "support@askthew.com", toolName);
+        }
+    });
+});