pi-cursor-sdk 0.5.2 → 0.5.4

package/dist/cursor-state.js

@@ -1,7 +1,8 @@
-import { buildCursorToolManifestText, CURSOR_TOOL_MANIFEST_ENV, resolveCursorToolManifestEnabled, } from "./cursor-tool-manifest.js";
+import { CURSOR_HOST_TOOL_MANIFEST_SUMMARY, CURSOR_TOOL_MANIFEST_ENV, resolveCursorToolManifestEnabled, } from "./cursor-tool-manifest.js";
 import { runCursorSessionAgentCleanupCommand } from "./cursor-session-agent-cleanup.js";
 import { CURSOR_HTTP1_ENTRY_TYPE, getStoredCursorHttp1Enabled, isCursorHttp1EntryData, setCursorHttp1GlobalPreferenceAuthoritative, setStoredCursorHttp1Enabled, } from "./cursor-http1.js";
-import { buildCursorPiToolBridgeSnapshot, CURSOR_PI_TOOL_BRIDGE_ENV, resolveCursorPiToolBridgeEnabled, } from "./cursor-pi-tool-bridge-snapshot.js";
+import { buildCursorPiToolBridgeSnapshot, CURSOR_PI_TOOL_BRIDGE_ENV, resolveCursorPiToolBridgeBuiltinsEnabled, resolveCursorPiToolBridgeEnabled, } from "./cursor-pi-tool-bridge-snapshot.js";
+import { CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV } from "./cursor-pi-tool-bridge-diagnostics.js";
 import { CURSOR_SETTING_SOURCES_ENV, DEFAULT_CURSOR_SETTING_SOURCES, resolveCursorSettingSources, } from "./cursor-setting-sources.js";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
@@ -12,8 +13,7 @@ import { cursorSettingsScopeForContext, getCursorSessionSettings, registerCursor
 import { refreshSessionCursorAgentConfig } from "./cursor-session-agent.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
 import { cursorFastDefaultsFromConfig, getCursorSdkUserConfigPath, loadCursorSdkUserConfig, mergeCursorSdkConfigForUpdate, resolveCursorFastDefault, resolveCursorLocalStoreRoot, updateCursorSdkConfig, } from "./cursor-config.js";
-import { CURSOR_RUNTIME_ENTRY_TYPE, formatCursorStatus, registerCursorCloudRuntimeControls, resetCursorRuntimeStateForTests, resolveCursorStatusRuntime, restoreCursorCliState, restoreSessionCursorRuntimeState, } from "./cursor-runtime-state.js";
-export { consumeCursorLocalForceOverride, getCursorCliConfig, getCursorSessionConfig, } from "./cursor-runtime-state.js";
+import { formatCursorStatus, registerCursorCloudRuntimeControls, resetCursorRuntimeStateForTests, resolveCursorStatusRuntime, restoreCursorCliState, restoreSessionCursorRuntimeState, } from "./cursor-runtime-state.js";
 export const CURSOR_FOOTER_ENV = "PI_CURSOR_FOOTER";
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const MODE_ENTRY_TYPE = "cursor-mode-state";
@@ -21,10 +21,10 @@ const DEFAULT_CURSOR_AGENT_MODE = "agent";
 const authoritativeGlobalFastPreferenceIds = new Set();
 let globalFastPreferences = new Map();
 const invalidCursorModeNotifiedSessionScopeKeys = new Set();
-export function isCursorAgentMode(value) {
+function isCursorAgentMode(value) {
     return value === "agent" || value === "plan";
 }
-export function parseCursorAgentMode(raw) {
+function parseCursorAgentMode(raw) {
     if (typeof raw !== "string")
         return undefined;
     const mode = raw.trim();
@@ -42,14 +42,11 @@ function getCursorFastEntryModelId(data) {
 function isCursorModeEntryData(value) {
     return isCursorAgentMode(asRecord(value)?.mode);
 }
-function getConfigPath() {
-    return getCursorSdkUserConfigPath();
-}
 function loadGlobalFastPreferences() {
     return cursorFastDefaultsFromConfig(loadCursorSdkUserConfig());
 }
 function saveGlobalFastPreference(modelId, fast) {
-    updateCursorSdkConfig(getConfigPath(), (current) => {
+    updateCursorSdkConfig(getCursorSdkUserConfigPath(), (current) => {
         const fastDefaults = { ...asRecord(current.fastDefaults), [modelId]: fast };
         return {
             ...current,
@@ -58,7 +55,7 @@ function saveGlobalFastPreference(modelId, fast) {
     }, { newFileMode: 0o600 });
 }
 function saveGlobalCursorHttp1Enabled(enabled) {
-    updateCursorSdkConfig(getConfigPath(), (current) => mergeCursorSdkConfigForUpdate(current, {
+    updateCursorSdkConfig(getCursorSdkUserConfigPath(), (current) => mergeCursorSdkConfigForUpdate(current, {
         local: { useHttp1ForAgent: enabled },
     }), { newFileMode: 0o600 });
 }
@@ -133,10 +130,10 @@ function getEffectiveFast(modelId, scopeKey) {
 function formatInvalidCursorMode(raw) {
     return `Invalid --cursor-mode "${raw}". Use "agent" or "plan".`;
 }
-export function getStoredCursorAgentMode(scopeKey) {
+function getStoredCursorAgentMode(scopeKey) {
     return getCursorSessionSettings(scopeKey).mode ?? DEFAULT_CURSOR_AGENT_MODE;
 }
-export function resolveCursorAgentMode(scopeKey) {
+function resolveCursorAgentMode(scopeKey) {
     const cliCursorModeState = getCursorSessionSettings(scopeKey).cli.mode;
     switch (cliCursorModeState.kind) {
         case "valid":
@@ -270,11 +267,12 @@ function formatEffectiveCursorSettingSourcesLabel(raw = process.env[CURSOR_SETTI
     const rawLabel = raw?.trim() ? raw.trim() : `(unset → ${DEFAULT_CURSOR_SETTING_SOURCES.join(",")})`;
     return `${rawLabel} (effective: ${effectiveLabel})`;
 }
-export function formatCursorToolsDebugReport(pi, env = process.env) {
+function formatCursorToolsDebugReport(pi) {
+    const env = process.env;
     const bridgeEnabled = resolveCursorPiToolBridgeEnabled(env);
     const manifestEnabled = resolveCursorToolManifestEnabled(env);
     const lines = [
-        "Cursor tool surfaces (current session):",
+        "Cursor tool surfaces (current registry snapshot; not a live run):",
         `${CURSOR_PI_TOOL_BRIDGE_ENV}: ${bridgeEnabled ? "enabled" : "disabled"}`,
         `${CURSOR_TOOL_MANIFEST_ENV}: ${manifestEnabled ? "enabled" : "disabled"}`,
         `${CURSOR_SETTING_SOURCES_ENV}: ${formatEffectiveCursorSettingSourcesLabel(env[CURSOR_SETTING_SOURCES_ENV])}`,
@@ -282,13 +280,23 @@ export function formatCursorToolsDebugReport(pi, env = process.env) {
     let bridgeSnapshot;
     if (bridgeEnabled) {
         try {
-            bridgeSnapshot = buildCursorPiToolBridgeSnapshot(pi);
+            bridgeSnapshot = buildCursorPiToolBridgeSnapshot(pi, {
+                exposeOverlappingBuiltins: resolveCursorPiToolBridgeBuiltinsEnabled(env),
+            });
         }
         catch {
             lines.push("Pi bridge snapshot: unavailable (extension tool APIs required).");
         }
     }
-    lines.push(buildCursorToolManifestText({ bridgeSnapshot, piBridgeEnabled: bridgeEnabled }));
+    lines.push(`Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`, "Pi tool toggles affect pi tools/bridge exposure only; they do not disable Cursor host/configured MCP tools.");
+    if (!bridgeEnabled) {
+        lines.push("Pi bridge: disabled (PI_CURSOR_PI_TOOL_BRIDGE=0).");
+    }
+    else if (bridgeSnapshot) {
+        const names = bridgeSnapshot.tools.map((tool) => tool.mcpToolName).sort();
+        lines.push(`Pi bridge exposure eligibility: ${names.length ? names.join(", ") : "no eligible pi__* tools"}.`);
+    }
+    lines.push("This snapshot does not prove a run's endpoint attachment, MCP initialization, catalog fetch, or tool calls.", `For per-run observations, enable ${CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV}=1 before the turn.`, "run_created/tools_exposed record exposure only; mcp_initialized records a validated notifications/initialized receipt; mcp_tools_list records catalog-handler output (toolCount), not client/model consumption or ongoing connection health.", "request_queued/resolved/rejected record actual bridge call handling; absent receipts do not diagnose why a client/model made no request.", "Not callable: cursor-replay-* IDs, pi history names, transcript labels.");
     return lines.join("\n");
 }
 function emitCursorToolsDebugReport(pi, ctx) {
@@ -364,7 +372,7 @@ export function registerCursorRuntimeControls(pi) {
         },
     });
     pi.registerCommand("cursor-tools", {
-        description: "Show live Cursor tool surfaces for this session (maintainer debug)",
+        description: "Show current-registry Cursor tool exposure eligibility (maintainer debug)",
         handler: async (_args, ctx) => {
             emitCursorToolsDebugReport(pi, ctx);
         },
@@ -517,16 +525,5 @@ function resetCursorModeStateForTests() {
     authoritativeGlobalFastPreferenceIds.clear();
 }
 export const __testUtils = {
-    FAST_ENTRY_TYPE,
-    MODE_ENTRY_TYPE,
-    CURSOR_HTTP1_ENTRY_TYPE,
-    RUNTIME_ENTRY_TYPE: CURSOR_RUNTIME_ENTRY_TYPE,
-    DEFAULT_CURSOR_AGENT_MODE,
-    getConfigPath,
-    loadGlobalFastPreferences,
-    get sessionFastPreferences() { return getCursorSessionSettings().fast; },
-    getSessionCursorAgentMode: () => getCursorSessionSettings().mode,
-    getCliCursorAgentMode: () => { const mode = getCursorSessionSettings().cli.mode; return mode.kind === "valid" ? mode.mode : undefined; },
-    getCliCursorModeState: () => getCursorSessionSettings().cli.mode,
     resetCursorModeStateForTests,
 };

package/dist/cursor-tool-lifecycle.js

@@ -82,9 +82,6 @@ function buildCursorToolLifecycleLabelFromVisibility(visibility, apiKey) {
             return undefined;
     }
 }
-export function buildCursorToolLifecycleLabel(toolCall, apiKey) {
-    return buildCursorToolLifecycleLabelFromVisibility(classifyCursorToolVisibility(toolCall), apiKey);
-}
 export function formatCursorToolLifecycleProgressText(toolCall, apiKey) {
     const visibility = classifyCursorToolVisibility(toolCall);
     const label = buildCursorToolLifecycleLabelFromVisibility(visibility, apiKey);

package/dist/cursor-tool-manifest.js

@@ -13,7 +13,9 @@ export function buildCursorToolManifestText(options = {}) {
     const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
     const lines = [
         "Callable tool surfaces this run:",
-        `- Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`,
+        options.nativeToolsEnabled === false
+            ? "- Cursor native tools (including task/subagents): disabled (PI_CURSOR_NATIVE_TOOLS=0). MCP remains available; configured MCP depends on Cursor settings."
+            : `- Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`,
         "- Pi tool toggles affect pi tools/bridge exposure only; they do not disable Cursor host/configured MCP tools.",
     ];
     const bridgeTools = includePiBridgeGuidance ? options.bridgeSnapshot?.tools ?? [] : [];

package/dist/cursor-tool-presentation-registry.js

@@ -7,13 +7,12 @@ import { formatReplaySemSearchQuery, readCursorReplaySummaryString, summarizeRep
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { getCursorTaskActivityTitle } from "./cursor-task-presentation.js";
 import { buildCreatePlanReplaySummaryArgs, buildDeleteReplayDetailFields, buildDeleteReplaySummaryArgs, buildGenerateImageReplayDetailFields, buildGenerateImageReplaySummaryArgs, buildMcpReplaySummaryArgs, buildReadLintsReplaySummaryArgs, buildRecordScreenReplaySummaryArgs, buildSemSearchReplaySummaryArgs, buildTaskReplaySummaryArgs, buildTodoReplaySummaryArgs, buildWebFetchReplaySummaryArgs, buildWebSearchReplaySummaryArgs, } from "./cursor-replay-activity-builders.js";
-import { CURSOR_REPLAY_SOURCE_TOOL_NAMES } from "./cursor-replay-source-names.js";
 export const CURSOR_REPLAY_ACTIVITY_TOOL_NAME = "cursor";
 const EMPTY_REPLAY_DETAIL_FIELDS = () => ({});
 const COLLAPSED_REPLAY_DETAIL_FIELDS = () => ({ collapseDetailsByDefault: true });
 const WEB_SEARCH_NAME_PATTERN = /^(?:web[-_ ]?search|search[-_ ]?web|websearch|browser[-_ ]?search)$/i;
 const WEB_FETCH_NAME_PATTERN = /^(?:web[-_ ]?fetch|fetch[-_ ]?web|webfetch|browser[-_ ]?fetch|fetch[-_ ]?url)$/i;
-export const CURSOR_TOOL_PRESENTATION_SPECS = [
+const CURSOR_TOOL_PRESENTATION_SPECS = [
     {
         normalizedName: "read",
         nameAliases: ["read_file"],
@@ -218,8 +217,7 @@ const WEB_KIND_BY_PATTERN = CURSOR_TOOL_PRESENTATION_SPECS.flatMap((spec) => {
         return [];
     return webNamePatterns.map((pattern) => ({ pattern, webKind }));
 });
-export const CURSOR_KNOWN_NORMALIZED_TOOL_NAMES = CURSOR_REPLAY_SOURCE_TOOL_NAMES;
-export function getCursorToolPresentationSpec(name) {
+function getCursorToolPresentationSpec(name) {
     const trimmed = name.trim();
     if (!trimmed)
         return undefined;

package/dist/cursor-tool-visibility.js

@@ -23,6 +23,3 @@ export function classifyCursorToolVisibility(toolCall) {
         fastLocalDiscovery: config?.fastLocalDiscovery ?? false,
     };
 }
-export function isFastLocalDiscoveryTool(toolCall) {
-    return classifyCursorToolVisibility(toolCall).fastLocalDiscovery;
-}

package/dist/cursor-transcript-tool-specs.js

@@ -1,4 +1,4 @@
-import { CURSOR_KNOWN_NORMALIZED_TOOL_NAMES, CURSOR_REPLAY_ACTIVITY_TOOL_NAME, getCursorReplayCallSummary, getCursorToolActivityTitle, getCursorToolActivityReplaySpec, getCursorToolGenerateImageReplaySpec, } from "./cursor-tool-presentation-registry.js";
+import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME, getCursorReplayCallSummary, getCursorToolActivityTitle, getCursorToolActivityReplaySpec, getCursorToolGenerateImageReplaySpec, } from "./cursor-tool-presentation-registry.js";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
 import { assembleCursorReplayActivityDetails, assembleCursorReplayGenerateImageDetails, CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME, } from "./cursor-replay-tool-details.js";
 import { asRecord, getNumber, getString } from "./cursor-record-utils.js";
@@ -264,7 +264,6 @@ const TOOL_DISPLAY_IMPLEMENTATIONS = {
         buildPiToolDisplay: (context) => buildActivityReplayDisplay("webFetch", context),
     },
 };
-export const CURSOR_TOOL_DISPLAY_SPEC_KEYS = CURSOR_KNOWN_NORMALIZED_TOOL_NAMES;
 function getToolDisplaySpec(name) {
     if (Object.hasOwn(TOOL_DISPLAY_IMPLEMENTATIONS, name))
         return TOOL_DISPLAY_IMPLEMENTATIONS[name];

package/dist/index.js

@@ -14,14 +14,35 @@ import { registerCursorFallbackIssueWarning } from "./cursor-fallback-warning.js
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context-registration.js";
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
+import { installCursorSdkProcessOutputFilter } from "./cursor-sdk-output-filter.js";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
 import { registerCursorUsageLedger } from "./cursor-usage-ledger.js";
 import { registerCursorUsageCommand } from "./cursor-usage-command.js";
 export default async function (pi) {
+    installCursorSdkProcessOutputFilter();
     // Session cwd must register before other session_start listeners that depend on it.
     registerCursorSessionScope(pi);
     registerCursorUsageLedger(pi);
     registerCursorUsageCommand(pi);
+    pi.registerCommand("cursor-abort", {
+        description: "Abort this session's pending local Cursor run without undoing completed work",
+        handler: async (_args, ctx) => {
+            const run = cursorLiveRuns.getActiveForScope(getCursorSessionScopeSnapshot(pi).scopeKey);
+            if (run && !run.disposed) {
+                if (!ctx.isIdle() && ctx.model?.provider === "cursor")
+                    ctx.abort();
+                await cursorLiveRuns.release(run);
+            }
+            const message = run
+                ? "Pending local Cursor run released. Retry under the current policy; already-executed work was not undone."
+                : "No pending local Cursor run in this session.";
+            if (ctx.hasUI)
+                ctx.ui.notify(message, "info");
+            else
+                process.stderr.write(`${message}\n`);
+        },
+    });
     let fallbackIssue;
     const registerCursorProvider = registerCursorProviderBinding(pi);
     const setFallbackWarning = registerCursorFallbackIssueWarning(pi);

package/dist/model-discovery.js

@@ -41,9 +41,9 @@ function mapComparableLevel(parameter, level) {
 }
 function getThinkingLevelMap(item) {
     const reasoningParameter = getParameter(item, "reasoning");
-    const effortParameter = getParameter(item, "effort");
+    const effortParameter = getParameter(item, "effort") ?? getParameter(item, "reasoning_effort");
     const thinkingParameter = getParameter(item, "thinking");
-    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter ?? getParameter(item, "reasoning_effort");
+    const valueParameter = effortParameter ?? reasoningParameter ?? thinkingParameter;
     if (!valueParameter)
         return undefined;
     if (valueParameter.id === "thinking" && hasBooleanValues(valueParameter)) {
@@ -196,10 +196,12 @@ function applyThinkingLevel(metadata, params, level) {
     const mapped = metadata.thinkingLevelMap?.[level];
     if (mapped === undefined || mapped === null)
         return;
+    const effortId = metadata.parameterIds.effort ? "effort" : metadata.parameterIds.reasoning_effort ? "reasoning_effort" : undefined;
     if (level === "off") {
         if (metadata.parameterIds.thinking && mapped === "false") {
             setParam(params, "thinking", mapped);
-            deleteParam(params, "effort");
+            if (effortId)
+                deleteParam(params, effortId);
             return;
         }
         if (metadata.parameterIds.reasoning) {
@@ -207,10 +209,10 @@ function applyThinkingLevel(metadata, params, level) {
         }
         return;
     }
-    if (metadata.parameterIds.effort) {
+    if (effortId) {
         if (metadata.parameterIds.thinking)
             setParam(params, "thinking", "true");
-        setParam(params, "effort", mapped);
+        setParam(params, effortId, mapped);
         return;
     }
     if (metadata.parameterIds.reasoning) {
@@ -220,9 +222,6 @@ function applyThinkingLevel(metadata, params, level) {
     if (metadata.parameterIds.thinking) {
         setParam(params, "thinking", mapped);
     }
-    else if (metadata.parameterIds.reasoning_effort) {
-        setParam(params, "reasoning_effort", mapped);
-    }
 }
 export function buildCursorModelSelection(modelId, thinkingLevel, fastEnabled) {
     const metadata = getCursorModelMetadata(modelId);
@@ -291,7 +290,7 @@ export async function discoverModels(options = {}) {
     try {
         const { Cursor } = await loadCursorSdk();
         options.signal?.throwIfAborted();
-        // SDK 1.0.36 CursorRequestOptions has no caller signal. A late response
+        // SDK 1.0.37 CursorRequestOptions has no caller signal. A late response
         // still cannot publish outside the native generation that requested it.
         const models = await Cursor.models.list({ apiKey });
         options.signal?.throwIfAborted();
@@ -325,6 +324,5 @@ export async function discoverModels(options = {}) {
     }
 }
 export const __testUtils = {
-    parseContextWindow,
     registerModelItems,
 };

package/dist/model-list-cache.js

@@ -13,10 +13,10 @@ const TTL_ENV_VAR = "PI_CURSOR_SDK_MODEL_CACHE_TTL_MS";
 function getCachePath() {
     return join(getAgentDir(), MODEL_LIST_CACHE_FILE);
 }
-export function isModelCacheDisabled() {
+function isModelCacheDisabled() {
     return parseEnvBoolean(process.env[DISABLE_ENV_VAR], false);
 }
-export function getModelCacheTtlMs() {
+function getModelCacheTtlMs() {
     const raw = process.env[TTL_ENV_VAR];
     if (raw === undefined)
         return DEFAULT_TTL_MS;
@@ -105,7 +105,8 @@ function readCacheFile() {
 }
 // Return cached models only when caching is enabled, the key matches, and the
 // entry is within the TTL. Used on the hot startup path to skip the network.
-export function loadFreshCachedModels(keyFingerprint, now = Date.now()) {
+export function loadFreshCachedModels(keyFingerprint) {
+    const now = Date.now();
     if (isModelCacheDisabled())
         return undefined;
     const ttlMs = getModelCacheTtlMs();
@@ -159,9 +160,3 @@ export function clearModelListCache() {
         // Cache cleanup is best-effort; it must not break native logout.
     }
 }
-export const __testUtils = {
-    getCachePath,
-    DEFAULT_TTL_MS,
-    DISABLE_ENV_VAR,
-    TTL_ENV_VAR,
-};

package/docs/cursor-live-smoke-checklist.md

@@ -71,7 +71,7 @@ Pass criteria:
 
 - `node --version` reports Node 24+.
 - `pi --version` reports official Pi 0.87.1 or the selected official-latest/current-`fitchmultz/pi` compatibility target.
-- `npm ls` shows exact `@cursor/sdk@1.0.36`; development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 1.0.4 with matching lockfile-resolved transitives, nested host TypeBox 1.3.27 and root validation TypeBox 1.3.36; and the bundled bridge runtime closure `@modelcontextprotocol/server@2.3.1`, `@modelcontextprotocol/hono@2.0.2`, `hono@4.13.13`, and `@hono/node-server@2.1.3`. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run.
+- `npm ls` shows exact `@cursor/sdk@1.0.37`; development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 1.1.0 with matching lockfile-resolved Pi cohort, nested host TypeBox 1.3.27 and root validation TypeBox 1.3.36; and the bundled bridge runtime closure `@modelcontextprotocol/server@2.3.1`, `@modelcontextprotocol/hono@2.0.2`, `hono@4.13.13`, and `@hono/node-server@2.1.3`. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run.
 - `cursor/grok-4.6` appears in the model list.
 - No Cursor key or auth token is printed.
 - If neither `~/.pi/agent/auth.json` cursor auth nor `CURSOR_API_KEY` is available, stop and report the live smoke as blocked.
@@ -136,7 +136,7 @@ Pass criteria:
 
 ## 4. Focused visual card/color rendering check
 
-This is a visual debug menu for changed card/color behavior requiring new live evidence. Select only the relevant category below, or reuse a batched existing platform suite; do not execute the entire list by default. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Node 24+, official Pi 0.87.1 or another current compatibility target, exact `@cursor/sdk@1.0.36`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
+This is a visual debug menu for changed card/color behavior requiring new live evidence. Select only the relevant category below, or reuse a batched existing platform suite; do not execute the entire list by default. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Node 24+, official Pi 0.87.1 or another current compatibility target, exact `@cursor/sdk@1.0.37`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
 
 ```bash
 VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1016-visual.XXXXXX)"
@@ -354,7 +354,7 @@ Script-enforced pass criteria:
 Additional manual usage checks for provider/accounting changes:
 
 - Each assistant message's disjoint input/cache/output components should sum to `totalTokens` and describe one coherent current context, not cumulative billed spend.
-- In split runs, earlier tool results can remain in later current-context estimates. Fresh, attributable LOCAL SDK usage takes precedence; late raw and billed facts remain in the separate ledger without rewriting emitted messages. See [context, compaction, and Cursor usage](../README.md#context-compaction-and-cursor-usage).
+- In split runs, earlier tool results can remain in later current-context estimates. Fresh, attributable LOCAL SDK usage takes precedence; late raw and billed facts remain in the separate ledger without rewriting emitted messages. See [context, compaction, and Cursor usage](reference.md#context-compaction-and-cursor-usage).
 
 ## 11. Standard local gates
 
@@ -391,7 +391,7 @@ Use this list to choose meaningful changed-behavior coverage, not to trigger a f
 - Native replay cards beyond read, especially shell/edit/write cards, when those renderers change.
 - Bridge question UI when `cursor_ask_question` changes.
 - MCP timeout override behavior (3600s `callTool` default, 10s initialize/listTools default, and SDK-default unknown protocol stacks) when timeout code changes.
-- SDK `semSearch` / `recordScreen` activity replay when those formatters change. There is no reliable local prompt that forces Cursor to call these built-in SDK tools on demand; regression is covered by `test/cursor-tool-transcript.test.ts`. Opportunistically confirm neutral `Cursor semantic search` / `Cursor screen recording` cards if a live run surfaces them.
+- SDK `semSearch` / `recordScreen` activity replay when those formatters change. There is no reliable local prompt that forces Cursor to call these built-in SDK tools on demand; regression is covered by `test/cursor-tool-transcript-mcp-web.test.ts`. Opportunistically confirm neutral `Cursor semantic search` / `Cursor screen recording` cards if a live run surfaces them.
 - Ambient Cursor setting-source behavior when startup filtering or local Cursor settings handling changes.
 - Model discovery aliases/context variants when model-discovery code or Cursor SDK versions change.