sneakoscope 4.6.2 → 4.6.3

package/README.md

@@ -49,7 +49,7 @@ sks seo-geo-optimizer apply latest --mode seo --apply --json
 sks seo-geo-optimizer audit --mode geo --target package --offline --json
 ```
 
-> 📋 **Current release: `v4.6.2`** — full release history lives in [CHANGELOG.md](CHANGELOG.md). This README documents how Sneakoscope works today, not its version-by-version changes. Release readiness is tracked in [docs/release-readiness.md](docs/release-readiness.md).
+> 📋 **Current release: `v4.6.3`** — full release history lives in [CHANGELOG.md](CHANGELOG.md). This README documents how Sneakoscope works today, not its version-by-version changes. Release readiness is tracked in [docs/release-readiness.md](docs/release-readiness.md).
 
 ## 🍥 Parallelism, UX, And Integrations
 
@@ -659,7 +659,7 @@ npm install -g .
 sks doctor --fix
 ```
 
-If PATH or npm has duplicate global installs, `sks doctor --fix` keeps one global npm install and removes duplicate global `sneakoscope` installs. The Sneakoscope source checkout is exempt so local development files are not removed.
+If PATH or npm has duplicate global installs, `sks doctor --fix` keeps one global npm install, removes duplicate global `sneakoscope` installs, and clears the npm cache so old downloaded package versions do not accumulate. The Sneakoscope source checkout is exempt so local development files are not removed.
 
 ### SKS keeps asking to update after a global update
 

package/crates/sks-core/Cargo.lock

@@ -76,7 +76,7 @@ dependencies = [
 
 [[package]]
 name = "sks-core"
-version = "4.6.2"
+version = "4.6.3"
 dependencies = [
  "serde_json",
 ]

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "4.6.2"
+version = "4.6.3"
 edition = "2021"
 
 [dependencies]

package/crates/sks-core/src/main.rs

@@ -4,7 +4,7 @@ use std::io::{self, Read, Seek, SeekFrom};
 fn main() {
     let mut args = std::env::args().skip(1);
     match args.next().as_deref() {
-        Some("--version") => println!("sks-rs 4.6.2"),
+        Some("--version") => println!("sks-rs 4.6.3"),
         Some("compact-info") => {
             let mut input = String::new();
             let _ = io::stdin().read_to_string(&mut input);

package/dist/bin/sks.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const FAST_PACKAGE_VERSION = '4.6.2';
+const FAST_PACKAGE_VERSION = '4.6.3';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--agent' && args[1] === 'worker') {

package/dist/commands/doctor.js

@@ -501,7 +501,7 @@ async function runDoctor(args = [], root, doctorFix) {
         warnings_suppressed: false,
         blockers: [err?.message || String(err)]
     }));
-    const globalSksInstallCleanup = flag(args, '--fix') && !flag(args, '--local-only') && deepDiagnostics
+    const globalSksInstallCleanup = flag(args, '--fix') && !flag(args, '--local-only')
         ? await cleanDuplicateGlobalSksInstalls({ root, fix: true }).catch((err) => ({ schema: 'sks.global-sks-install-cleanup.v1', ok: false, fix: true, error: err?.message || String(err), blockers: ['global_sks_install_cleanup_exception'] }))
         : null;
     const { detectImagegenCapability } = await import('../core/imagegen/imagegen-capability.js');
@@ -879,6 +879,8 @@ async function runDoctor(args = [], root, doctorFix) {
     }
     if (globalSksInstallCleanup) {
         console.log(`Global SKS installs: kept ${globalSksInstallCleanup.kept?.length ?? 0}, removed ${globalSksInstallCleanup.removed?.filter((entry) => entry.ok).length ?? 0}, source repo exempt ${globalSksInstallCleanup.candidates?.filter((entry) => entry.source_repo_exempt).length ?? 0}`);
+        if (globalSksInstallCleanup.npm_cache)
+            console.log(`NPM cache cleanup: ${globalSksInstallCleanup.npm_cache.status}`);
     }
     if (!ready.ready && ready.next_actions?.length) {
         console.log('What still needs you:');

package/dist/core/doctor/global-sks-install-cleanup.js

@@ -12,18 +12,22 @@ export async function cleanDuplicateGlobalSksInstalls(opts = {}) {
     const planned = planGlobalSksInstallCleanup(candidates, { sourceRoot });
     const removed = [];
     const blockers = [...planned.blockers];
+    const cleanupContract = opts.fix === true && npmBin
+        ? createRequestedScopeContract({
+            route: 'doctor',
+            userRequest: 'sks doctor --fix global SKS install and npm cache cleanup',
+            projectRoot: sourceRoot,
+            overrides: { package_install: true }
+        })
+        : null;
+    const guardContext = cleanupContract && npmBin
+        ? guardContextForRoute(sourceRoot, cleanupContract, 'sks doctor --fix global SKS install and npm cache cleanup')
+        : null;
     if (opts.fix === true && planned.removable.length > 0) {
-        if (!npmBin) {
+        if (!npmBin || !guardContext) {
             blockers.push('npm_not_found_for_duplicate_global_sks_cleanup');
         }
         else {
-            const cleanupContract = createRequestedScopeContract({
-                route: 'doctor',
-                userRequest: 'sks doctor --fix duplicate global SKS cleanup',
-                projectRoot: sourceRoot,
-                overrides: { package_install: true }
-            });
-            const guardContext = guardContextForRoute(sourceRoot, cleanupContract, 'sks doctor --fix duplicate global SKS cleanup');
             for (const candidate of planned.removable) {
                 if (!candidate.prefix) {
                     blockers.push(`duplicate_global_sks_missing_prefix:${candidate.package_root || candidate.bin || 'unknown'}`);
@@ -44,9 +48,12 @@ export async function cleanDuplicateGlobalSksInstalls(opts = {}) {
             }
         }
     }
+    const npmCache = await cleanNpmCache({ fix: opts.fix === true, npmBin, env, guardContext });
+    if (opts.fix === true && !npmCache.ok)
+        blockers.push(...npmCache.blockers);
     return {
         schema: 'sks.global-sks-install-cleanup.v1',
-        ok: blockers.length === 0,
+        ok: blockers.length === 0 && npmCache.ok,
         fix: opts.fix === true,
         source_root: sourceRoot,
         package: 'sneakoscope',
@@ -54,6 +61,7 @@ export async function cleanDuplicateGlobalSksInstalls(opts = {}) {
         kept: planned.kept,
         removable: planned.removable,
         removed,
+        npm_cache: npmCache,
         blockers
     };
 }
@@ -217,6 +225,62 @@ function dedupeCandidates(candidates) {
 function scoreCandidate(candidate) {
     return (candidate.bin ? 2 : 0) + (candidate.prefix ? 1 : 0);
 }
+async function cleanNpmCache(opts) {
+    const args = ['cache', 'clean', '--force', '--silent'];
+    const command = opts.npmBin ? [opts.npmBin, ...args].join(' ') : null;
+    if (!opts.fix) {
+        return {
+            schema: 'sks.npm-cache-cleanup.v1',
+            ok: true,
+            fix: false,
+            status: 'skipped',
+            command,
+            code: null,
+            scope: 'npm_cache_all_packages',
+            stdout_tail: '',
+            stderr_tail: '',
+            blockers: []
+        };
+    }
+    if (!opts.npmBin || !opts.guardContext) {
+        return {
+            schema: 'sks.npm-cache-cleanup.v1',
+            ok: false,
+            fix: true,
+            status: 'npm_missing',
+            command: null,
+            code: null,
+            scope: 'npm_cache_all_packages',
+            stdout_tail: '',
+            stderr_tail: '',
+            blockers: ['npm_not_found_for_npm_cache_cleanup']
+        };
+    }
+    const result = await guardedPackageInstall(opts.guardContext, 'npm cache clean --force', {
+        confirmed: true,
+        command: opts.npmBin,
+        args,
+        env: opts.env,
+        timeoutMs: 60_000,
+        maxOutputBytes: 16 * 1024
+    }).catch((err) => ({ code: 1, stdout: '', stderr: err?.message || String(err) }));
+    const ok = result.code === 0;
+    return {
+        schema: 'sks.npm-cache-cleanup.v1',
+        ok,
+        fix: true,
+        status: ok ? 'cleaned' : 'failed',
+        command,
+        code: result.code,
+        scope: 'npm_cache_all_packages',
+        stdout_tail: tail(result.stdout),
+        stderr_tail: tail(result.stderr),
+        blockers: ok ? [] : ['npm_cache_clean_failed']
+    };
+}
+function tail(text) {
+    return String(text || '').slice(-2000);
+}
 async function realpathOrSelf(value) {
     try {
         return await fsp.realpath(value);

package/dist/core/fsx.js

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-export const PACKAGE_VERSION = '4.6.2';
+export const PACKAGE_VERSION = '4.6.3';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 export function nowIso() {

package/dist/core/mad-db/mad-db-coordinator.js

@@ -17,10 +17,10 @@ export async function prepareMadDbMission(input) {
     const blockers = [...target.blockers];
     let profile;
     if (!target.project_ref) {
-        profile = await createMadDbRuntimeProfile({ root: input.root, missionId: id, cycleId, projectRef: 'missing-project-ref', runtimeSessionId });
+        profile = await createMadDbRuntimeProfile({ root: input.root, missionId: id, cycleId, projectRef: 'missing-project-ref', runtimeSessionId, mcpUrl: target.mcp_url });
     }
     else {
-        profile = await createMadDbRuntimeProfile({ root: input.root, missionId: id, cycleId, projectRef: target.project_ref, runtimeSessionId });
+        profile = await createMadDbRuntimeProfile({ root: input.root, missionId: id, cycleId, projectRef: target.project_ref, runtimeSessionId, mcpUrl: target.mcp_url });
     }
     const capability = await createMadDbCapability(input.root, {
         missionId: id,
@@ -54,7 +54,7 @@ export async function prepareMadDbMission(input) {
         command: '$MAD-DB',
         mode: 'MADDB',
         task: input.task,
-        target: { ...target, project_ref: target.project_ref ? `<hash:${target.project_ref_hash}>` : null },
+        target: redactTarget(target),
         capability_file: 'mad-db-capability.json',
         runtime_profile_manifest: 'mad-db/runtime/runtime-profile-manifest.json',
         tool_inventory: toolInventory ? 'mad-db/runtime/tool-inventory.json' : null
@@ -118,6 +118,8 @@ export async function runMadDbCycle(input) {
         await writeJsonAtomic(path.join(missionDir(input.root, prepared.mission_id), 'mad-db', 'runtime', 'tool-inventory.json'), inventory);
         if (!inventory.ok) {
             blockers.push('mad_db_execute_sql_or_apply_migration_unavailable');
+            if (inventory.error_kind)
+                blockers.push(inventory.error_kind);
             throw new Error('mad_db_tool_inventory_failed');
         }
         await activateMadDbCapability(input.root, prepared.mission_id);
@@ -154,6 +156,8 @@ export async function runMadDbCycle(input) {
         });
         if (!execution.ok)
             blockers.push('mad_db_tool_execution_failed');
+        if (!execution.ok && execution.error_kind)
+            blockers.push(execution.error_kind);
         if (execution.ok && input.verifySql) {
             const verifyStart = Date.now();
             readBack = await runReadBackChecks({
@@ -227,10 +231,7 @@ async function clearMadDbCurrentState(root, missionId, ok, restoration) {
 function redactCycleResult(result) {
     return {
         ...result,
-        target: {
-            ...result.target,
-            project_ref: result.target.project_ref ? '<redacted>' : null
-        }
+        target: redactTarget(result.target)
     };
 }
 async function resolveSqlInput(input) {
@@ -252,13 +253,21 @@ async function recreateProfileFromPrepared(root, prepared) {
         profile_path: prepared.runtime_profile.profile_path,
         profile_sha256: prepared.runtime_profile.profile_sha256,
         server_url_redacted: prepared.runtime_profile.server_url_redacted,
-        server_url: `https://mcp.supabase.com/mcp?project_ref=${encodeURIComponent(projectRef)}&features=database`,
+        server_url: prepared.target.mcp_url || `https://mcp.supabase.com/mcp?project_ref=${encodeURIComponent(projectRef)}&features=database`,
+        server_url_source: prepared.target.mcp_url ? 'explicit_mcp_url' : 'generated_project_ref',
         features: ['database'],
         write_capable: true,
         normal_config_hash_before: prepared.runtime_profile.normal_config_hash_before,
         created_at: prepared.runtime_profile.created_at
     };
 }
+function redactTarget(target) {
+    return {
+        ...target,
+        project_ref: target.project_ref ? `<hash:${target.project_ref_hash}>` : null,
+        mcp_url: target.mcp_url ? '<redacted>' : null
+    };
+}
 export async function madDbRouteIdentityProof(root, missionId) {
     const capability = await readMadDbCapability(root, missionId);
     const state = await readJson(path.join(root, '.sneakoscope', 'state', 'current.json'), {});

package/dist/core/mad-db/mad-db-executor.js

@@ -33,10 +33,15 @@ export class MadDbMcpExecutor {
                 execute_sql_available: hasTool(names, 'execute_sql'),
                 apply_migration_available: hasTool(names, 'apply_migration'),
                 duration_ms: Math.round(performance.now() - started),
-                error_digest: null
+                error_digest: null,
+                error_summary: null,
+                error_kind: null,
+                retry_guidance: null
             };
         }
         catch (err) {
+            const summary = summarizeMadDbError(err);
+            const kind = classifyMadDbError(summary);
             return {
                 schema: 'sks.mad-db-tool-inventory.v1',
                 checked_at: nowIso(),
@@ -45,7 +50,10 @@ export class MadDbMcpExecutor {
                 execute_sql_available: false,
                 apply_migration_available: false,
                 duration_ms: Math.round(performance.now() - started),
-                error_digest: sha256(redactError(err)).slice(0, 32)
+                error_digest: sha256(summary).slice(0, 32),
+                error_summary: summary,
+                error_kind: kind,
+                retry_guidance: madDbRetryGuidance(kind)
             };
         }
     }
@@ -77,21 +85,29 @@ export class MadDbMcpExecutor {
                     result_digest: sha256(JSON.stringify(redactToolResult(result))).slice(0, 32),
                     row_count: extractRowCount(result),
                     is_error: result.isError === true,
-                    duration_ms: Math.round(performance.now() - started)
+                    duration_ms: Math.round(performance.now() - started),
+                    error_summary: result.isError === true ? summarizeMadDbToolError(result) : null,
+                    error_kind: result.isError === true ? classifyMadDbError(summarizeMadDbToolError(result)) : null,
+                    retry_guidance: result.isError === true ? madDbRetryGuidance(classifyMadDbError(summarizeMadDbToolError(result))) : null
                 };
             }
             catch (err) {
                 lastError = err;
             }
         }
+        const summary = summarizeMadDbError(lastError);
+        const kind = classifyMadDbError(summary);
         return {
             schema: 'sks.mad-db-tool-result.v1',
             ok: false,
             tool_name: tool,
-            result_digest: sha256(redactError(lastError)).slice(0, 32),
+            result_digest: sha256(summary).slice(0, 32),
             row_count: null,
             is_error: true,
-            duration_ms: 0
+            duration_ms: 0,
+            error_summary: summary,
+            error_kind: kind,
+            retry_guidance: madDbRetryGuidance(kind)
         };
     }
 }
@@ -112,9 +128,45 @@ function authHeaders() {
         return undefined;
     return { Authorization: `Bearer ${token}` };
 }
-function redactError(err) {
+export function summarizeMadDbError(err) {
     const text = err instanceof Error ? `${err.name}:${err.message}` : String(err);
-    return text.replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1<redacted>').replace(/(token|password|secret|apikey)=([^&\s]+)/gi, '$1=<redacted>');
+    return redactErrorText(text).slice(0, 1200);
+}
+function summarizeMadDbToolError(result) {
+    return redactErrorText(JSON.stringify(redactToolResult(result))).slice(0, 1200);
+}
+function redactErrorText(text) {
+    return String(text || '')
+        .replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1<redacted>')
+        .replace(/(token|password|secret|apikey)=([^&\s]+)/gi, '$1=<redacted>')
+        .replace(/(postgres(?:ql)?:\/\/[^:\s/]+:)([^@\s]+)(@)/gi, '$1<redacted>$3');
+}
+export function classifyMadDbError(summary) {
+    const text = String(summary || '').toLowerCase();
+    if (/read[_ -]?only|read only|permission denied.+read/i.test(text))
+        return 'supabase_mcp_read_only_transport';
+    if (/timeout|timed out|etimedout|i\/o timeout|aborterror|deadline/i.test(text))
+        return 'supabase_sql_plane_timeout';
+    if (/connection terminated|econnreset|unexpected eof|socket hang up|server closed/i.test(text))
+        return 'supabase_sql_plane_connection_interrupted';
+    if (/sasl|password authentication failed|invalid login|authentication failed|sqlstate 28p01/i.test(text))
+        return 'supabase_sql_plane_auth_failed';
+    if (/fetch failed|enotfound|econnrefused|network|dns/i.test(text))
+        return 'supabase_mcp_transport_unreachable';
+    return 'supabase_mcp_tool_error';
+}
+export function madDbRetryGuidance(kind) {
+    if (kind === 'supabase_mcp_read_only_transport')
+        return 'The active MadDB cycle must use the mission-local write-capable MCP URL. Pass --mcp-url or SKS_MAD_DB_MCP_URL if a project-local read-only Supabase MCP config is shadowing the intended transport.';
+    if (kind === 'supabase_sql_plane_timeout')
+        return 'Retry with an explicit Supabase pooler/session/direct MCP transport if available; Supabase CLI docs also support --db-url for CLI migration paths when pooler/direct connectivity differs.';
+    if (kind === 'supabase_sql_plane_connection_interrupted')
+        return 'Treat this as a SQL-plane connectivity interruption, not a DB safety denial. Retry after checking Supabase project health, pooler/direct connection mode, and network reachability.';
+    if (kind === 'supabase_sql_plane_auth_failed')
+        return 'Check SUPABASE_ACCESS_TOKEN and the project/database credentials used by the Supabase MCP server; do not retry destructive SQL until auth is corrected.';
+    if (kind === 'supabase_mcp_transport_unreachable')
+        return 'Check access to https://mcp.supabase.com/mcp or pass a trusted local MCP URL with --mcp-url for the active MadDB cycle.';
+    return 'Inspect error_summary in mad-db-result.json; the failure occurred after MadDB capability gating, so do not report it as a safety-gate denial.';
 }
 function redactToolResult(value) {
     if (value == null)

package/dist/core/mad-db/mad-db-runtime-profile.js

@@ -5,7 +5,7 @@ import { missionDir } from '../mission.js';
 export async function createMadDbRuntimeProfile(input) {
     const dir = path.join(missionDir(input.root, input.missionId), 'mad-db', 'runtime');
     await fs.mkdir(dir, { recursive: true });
-    const url = madDbMcpUrl(input.projectRef);
+    const url = madDbMcpUrl(input.projectRef, input.mcpUrl);
     const text = [
         '[mcp_servers.supabase_mad_db]',
         `url = "${url}"`,
@@ -26,6 +26,7 @@ export async function createMadDbRuntimeProfile(input) {
         profile_sha256: profileHash,
         server_url_redacted: redactSupabaseUrl(url),
         server_url: url,
+        server_url_source: input.mcpUrl ? 'explicit_mcp_url' : 'generated_project_ref',
         features: ['database'],
         write_capable: true,
         normal_config_hash_before: normalHash,
@@ -74,7 +75,15 @@ export function redactedRuntimeProfile(profile) {
     const { server_url: _serverUrl, ...rest } = profile;
     return rest;
 }
-export function madDbMcpUrl(projectRef) {
+export function madDbMcpUrl(projectRef, explicitUrl) {
+    if (explicitUrl) {
+        const parsed = new URL(explicitUrl);
+        if (projectRef && !parsed.searchParams.get('project_ref'))
+            parsed.searchParams.set('project_ref', projectRef);
+        parsed.searchParams.set('features', 'database');
+        parsed.searchParams.delete('read_only');
+        return parsed.toString();
+    }
     const params = new URLSearchParams();
     params.set('project_ref', projectRef);
     params.set('features', 'database');

package/dist/core/mad-db/mad-db-target.js

@@ -1,10 +1,13 @@
 import path from 'node:path';
 import { exists, readText, sha256 } from '../fsx.js';
+import { redactSupabaseUrl } from './mad-db-runtime-profile.js';
 export async function resolveMadDbTarget(root, input = {}) {
     const args = input.args || [];
     const explicit = input.projectRef || readOption(args, '--project-ref', '') || process.env.SKS_MAD_DB_PROJECT_REF || process.env.SKS_MAD_DB_E2E_PROJECT_REF || '';
     const candidates = explicit ? [explicit] : await projectRefCandidates(root);
     const projectRef = explicit || (candidates.length === 1 ? candidates[0] || '' : '');
+    const explicitMcpUrl = readOption(args, '--mcp-url', '') || process.env.SKS_MAD_DB_MCP_URL || process.env.SKS_MAD_DB_SUPABASE_MCP_URL || '';
+    const normalizedMcp = normalizeExplicitMcpUrl(explicitMcpUrl, projectRef || null);
     const target = normalizeTarget(input.target || readOption(args, '--target', '') || process.env.SKS_MAD_DB_TARGET || process.env.SKS_MAD_DB_E2E_TARGET || 'production');
     const allowedSchemas = input.allowedSchemas?.length
         ? input.allowedSchemas
@@ -12,10 +15,16 @@ export async function resolveMadDbTarget(root, input = {}) {
     const blockers = [];
     if (!projectRef)
         blockers.push(candidates.length > 1 ? 'mad_db_project_ref_ambiguous' : 'mad_db_project_ref_missing');
+    if (normalizedMcp.blocker)
+        blockers.push(normalizedMcp.blocker);
     return {
         schema: 'sks.mad-db-target.v1',
         project_ref: projectRef || null,
         project_ref_hash: projectRef ? sha256(projectRef).slice(0, 16) : null,
+        mcp_url: normalizedMcp.url,
+        mcp_url_hash: normalizedMcp.url ? sha256(normalizedMcp.url).slice(0, 16) : null,
+        mcp_url_redacted: normalizedMcp.url ? redactSupabaseUrl(normalizedMcp.url) : null,
+        mcp_url_source: normalizedMcp.url ? 'explicit_or_environment' : 'default_generated',
         target_environment: target,
         allowed_schemas: allowedSchemas.length ? allowedSchemas : ['public'],
         source: explicit ? 'explicit_or_environment' : candidates.length === 1 ? 'managed_config_single_candidate' : 'unresolved',
@@ -23,6 +32,28 @@ export async function resolveMadDbTarget(root, input = {}) {
         candidates: candidates.map((candidate) => `${sha256(candidate).slice(0, 8)}:${candidate.slice(0, 2)}...`)
     };
 }
+function normalizeExplicitMcpUrl(value, projectRef) {
+    if (!value)
+        return { url: null, blocker: null };
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return { url: null, blocker: 'mad_db_mcp_url_invalid' };
+    }
+    const isSupabaseRemote = parsed.protocol === 'https:' && parsed.hostname === 'mcp.supabase.com' && parsed.pathname === '/mcp';
+    const isLocalMcp = parsed.protocol === 'http:' && /^localhost$|^127\.0\.0\.1$/.test(parsed.hostname) && parsed.pathname.endsWith('/mcp');
+    if (!isSupabaseRemote && !isLocalMcp)
+        return { url: null, blocker: 'mad_db_mcp_url_untrusted_host' };
+    if (parsed.searchParams.get('read_only') === 'true')
+        return { url: null, blocker: 'mad_db_mcp_url_read_only_conflict' };
+    if (projectRef && !parsed.searchParams.get('project_ref'))
+        parsed.searchParams.set('project_ref', projectRef);
+    parsed.searchParams.set('features', 'database');
+    parsed.searchParams.delete('read_only');
+    return { url: parsed.toString(), blocker: null };
+}
 export async function projectRootHash(root) {
     return sha256(path.resolve(root)).slice(0, 24);
 }

package/dist/core/update-check.js

@@ -389,7 +389,7 @@ export async function detectEffectiveSksVersion(options = {}) {
     const pathCandidate = candidates.find((candidate) => candidate.source.startsWith('PATH:'))?.version || null;
     const npmGlobalCandidate = candidates.find((candidate) => candidate.source.startsWith('npm-global:'))?.version || null;
     const packageRootCandidate = candidates.find((candidate) => candidate.source === 'packageRoot:package.json')?.version || null;
-    const current = highestPackageVersion(candidates.map((candidate) => candidate.version));
+    const current = effectiveInstalledVersion(candidates);
     return {
         current,
         runtime_current: PACKAGE_VERSION,
@@ -533,6 +533,16 @@ function updateNowError(install, newBinary, newVersionDoctor, migrationCurrent)
         return 'project update migration receipt was not current';
     return 'update failed';
 }
+function effectiveInstalledVersion(candidates) {
+    const firstBySource = (source) => candidates.find((candidate) => candidate.source === source)?.version || null;
+    const firstByPrefix = (prefix) => candidates.find((candidate) => candidate.source.startsWith(prefix))?.version || null;
+    return firstBySource('env:SKS_INSTALLED_SKS_VERSION')
+        || firstByPrefix('npm-global:')
+        || firstByPrefix('PATH:')
+        || firstBySource('runtime')
+        || firstBySource('packageRoot:package.json')
+        || highestPackageVersion(candidates.map((candidate) => candidate.version));
+}
 function highestPackageVersion(versions) {
     return versions
         .filter((version) => typeof version === 'string' && version.length > 0)

package/dist/core/version.js

@@ -1,2 +1,2 @@
-export const PACKAGE_VERSION = '4.6.2';
+export const PACKAGE_VERSION = '4.6.3';
 //# sourceMappingURL=version.js.map

package/dist/scripts/mad-db-supabase-transport-diagnostics-check.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createMission } from '../core/mission.js';
+import { classifyMadDbError, madDbRetryGuidance, summarizeMadDbError } from '../core/mad-db/mad-db-executor.js';
+import { createMadDbRuntimeProfile, madDbMcpUrl } from '../core/mad-db/mad-db-runtime-profile.js';
+import { resolveMadDbTarget } from '../core/mad-db/mad-db-target.js';
+import { assertGate, emitGate } from './sks-1-18-gate-lib.js';
+const timeoutSummary = summarizeMadDbError(new Error('failed to connect to postgres: dial tcp 1.2.3.4:6543: i/o timeout token=secret-token'));
+assertGate(classifyMadDbError(timeoutSummary) === 'supabase_sql_plane_timeout', 'timeout errors must be classified as SQL-plane timeout', { timeoutSummary });
+assertGate(!timeoutSummary.includes('secret-token'), 'error summary must redact token query values', { timeoutSummary });
+assertGate(madDbRetryGuidance('supabase_sql_plane_timeout').includes('--db-url'), 'timeout guidance should mention explicit db-url fallback evidence from Supabase CLI docs');
+const readOnlyKind = classifyMadDbError('MCP server denied apply_migration because this connection is read only');
+assertGate(readOnlyKind === 'supabase_mcp_read_only_transport', 'read-only transport errors must be separated from SQL-plane connectivity', { readOnlyKind });
+const root = await fs.mkdtemp(path.join(os.tmpdir(), 'sks-mad-db-transport-'));
+await fs.mkdir(path.join(root, '.codex'), { recursive: true });
+await fs.writeFile(path.join(root, '.codex', 'config.toml'), '[mcp_servers.supabase]\nurl = "https://mcp.supabase.com/mcp?project_ref=localref&read_only=true&features=database,docs"\n', 'utf8');
+const target = await resolveMadDbTarget(root, {
+    args: ['--project-ref', 'explicitref', '--mcp-url', 'https://mcp.supabase.com/mcp?features=docs']
+});
+assertGate(target.blockers.length === 0, 'explicit trusted MCP URL without read_only should be accepted', target);
+assertGate(target.mcp_url?.includes('project_ref=explicitref'), 'explicit MCP URL should inherit project_ref when omitted', target);
+assertGate(target.mcp_url?.includes('features=database'), 'explicit MCP URL should force database feature for MadDB SQL-plane execution', target);
+assertGate(!target.mcp_url?.includes('read_only=true'), 'active MadDB explicit MCP URL must not remain read-only', target);
+const conflict = await resolveMadDbTarget(root, {
+    args: ['--project-ref', 'explicitref', '--mcp-url', 'https://mcp.supabase.com/mcp?read_only=true']
+});
+assertGate(conflict.blockers.includes('mad_db_mcp_url_read_only_conflict'), 'read-only explicit MCP URL must be rejected in active MadDB', conflict);
+const mission = await createMission(root, { mode: 'mad-db', prompt: 'transport diagnostics fixture' });
+const profile = await createMadDbRuntimeProfile({
+    root,
+    missionId: mission.id,
+    cycleId: 'cycle-fixture',
+    projectRef: 'explicitref',
+    runtimeSessionId: 'session-fixture',
+    mcpUrl: target.mcp_url
+});
+assertGate(profile.server_url_source === 'explicit_mcp_url', 'runtime profile must record explicit MCP URL source', profile);
+assertGate(profile.server_url === target.mcp_url, 'runtime profile must use normalized explicit MCP URL', { profile, target });
+assertGate(madDbMcpUrl('abc123') === 'https://mcp.supabase.com/mcp?project_ref=abc123&features=database', 'generated MCP URL should stay project scoped and database-feature scoped');
+emitGate('mad-db:supabase-transport-diagnostics', {
+    timeout_kind: classifyMadDbError(timeoutSummary),
+    read_only_kind: readOnlyKind,
+    mcp_url_source: profile.server_url_source
+});
+//# sourceMappingURL=mad-db-supabase-transport-diagnostics-check.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "4.6.2",
+  "version": "4.6.3",
   "description": "Sneakoscope Codex: fast proof-first Codex trust layer with image-based Voxel TriWiki.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -745,6 +745,7 @@
     "mad-db:runtime-profile": "node ./dist/scripts/mad-db-runtime-profile-lifecycle-check.js",
     "mad-db:skill-policy": "node ./dist/scripts/mad-db-skill-policy-snapshot-check.js",
     "mad-db:policy-v2": "node ./dist/scripts/mad-db-policy-v2-check.js",
+    "mad-db:supabase-transport-diagnostics": "node ./dist/scripts/mad-db-supabase-transport-diagnostics-check.js",
     "release:speed-summary": "node ./dist/scripts/release-speed-summary-check.js",
     "release:speed-summary:check": "node ./dist/scripts/release-speed-summary-check.js",
     "naruto:ssot-routing": "node ./dist/scripts/naruto-ssot-routing-check.js",
@@ -778,7 +779,7 @@
     "mad-db:lifecycle-hook-decision": "node ./dist/scripts/mad-db-lifecycle-hook-decision-check.js",
     "mad-db:mcp-result-lifecycle": "node ./dist/scripts/mad-db-mcp-result-lifecycle-check.js",
     "mad-db:operation-lifecycle-blackbox": "node ./dist/scripts/mad-db-operation-lifecycle-blackbox.js",
-    "mad-db:unit": "npm run mad-db:capability && npm run mad-db:command && npm run mad-db:mad-command && npm run mad-db:priority-resolver && npm run mad-db:ledger && npm run mad-db:one-cycle-consumption && npm run mad-db:safety-conflict-matrix && npm run mad-db:one-cycle-bounded && npm run mad-db:operation-lifecycle-ledger && npm run mad-db:route-identity && npm run mad-db:hook-idempotency && npm run mad-db:direct-apply-migration-hook && npm run mad-db:parallel-lifecycle && npm run mad-db:runtime-profile && npm run mad-db:skill-policy && npm run mad-db:policy-v2 && npm run mad-db:lifecycle-hook-decision && npm run mad-db:mcp-result-lifecycle && npm run mad-db:operation-lifecycle-blackbox",
+    "mad-db:unit": "npm run mad-db:capability && npm run mad-db:command && npm run mad-db:mad-command && npm run mad-db:priority-resolver && npm run mad-db:ledger && npm run mad-db:one-cycle-consumption && npm run mad-db:safety-conflict-matrix && npm run mad-db:one-cycle-bounded && npm run mad-db:operation-lifecycle-ledger && npm run mad-db:route-identity && npm run mad-db:hook-idempotency && npm run mad-db:direct-apply-migration-hook && npm run mad-db:parallel-lifecycle && npm run mad-db:runtime-profile && npm run mad-db:skill-policy && npm run mad-db:policy-v2 && npm run mad-db:supabase-transport-diagnostics && npm run mad-db:lifecycle-hook-decision && npm run mad-db:mcp-result-lifecycle && npm run mad-db:operation-lifecycle-blackbox",
     "mad-db:real-e2e": "node ./dist/scripts/mad-db-real-supabase-e2e.js --require-real",
     "mad-db:all": "npm run build && npm run mad-db:unit",
     "mad-db:release": "npm run mad-db:all && npm run mad-db:real-e2e",