sneakoscope 4.6.2 → 4.6.4

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.4`** — 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.4"
 dependencies = [
  "serde_json",
 ]

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "4.6.2"
+version = "4.6.4"
 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.4"),
         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.4';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--agent' && args[1] === 'worker') {

package/dist/cli/install-helpers.js

@@ -92,6 +92,11 @@ export async function postinstall({ bootstrap, args = [] }) {
             console.log('SKS update migration: global Doctor ran; project receipt will be finalized on first normal command.');
         else
             console.log(`SKS update migration: global Doctor did not complete; first normal command will retry. ${(postinstallDoctor.blockers || []).join(', ')}`.trim());
+        const postinstallRetention = await runPostinstallProjectRetentionCleanup(installRoot);
+        if (postinstallRetention.status === 'completed' && postinstallRetention.action_count > 0)
+            console.log(`SKS mission cleanup: removed ${postinstallRetention.action_count} disposable runtime artifact(s) from closed missions.`);
+        else if (postinstallRetention.status === 'failed')
+            console.log(`SKS mission cleanup: skipped (${postinstallRetention.error || 'cleanup failed'}).`);
         // Terminating a third-party app's processes during `npm i` is unsafe by default; opt-in only.
         const appProcessRepair = process.env.SKS_POSTINSTALL_RECONCILE_APP_PROCESSES === '1'
             ? await reconcileCodexAppUpgradeProcesses()
@@ -150,6 +155,36 @@ export async function postinstall({ bootstrap, args = [] }) {
         await reportPostinstallCodexLbAuth().catch(() => { });
     }
 }
+async function runPostinstallProjectRetentionCleanup(root) {
+    const projectRoot = path.resolve(root || process.cwd());
+    if (process.env.SKS_POSTINSTALL_RETENTION_CLEANUP === '0') {
+        return { status: 'skipped', reason: 'disabled_by_env', action_count: 0 };
+    }
+    if (!(await exists(path.join(projectRoot, '.sneakoscope', 'missions')))) {
+        return { status: 'skipped', reason: 'missions_missing', action_count: 0 };
+    }
+    try {
+        const { enforceRetention } = await import('../core/retention.js');
+        const result = await enforceRetention(projectRoot, {
+            mode: 'postinstall_update',
+            pruneReportLogs: true,
+            policy: { max_tmp_age_hours: 0 }
+        });
+        return {
+            status: 'completed',
+            root: projectRoot,
+            action_count: Array.isArray(result.actions) ? result.actions.length : 0
+        };
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            root: projectRoot,
+            action_count: 0,
+            error: err?.message || String(err)
+        };
+    }
+}
 async function reportPostinstallCodexLbAuth() {
     const codexLbAuth = await ensureCodexLbAuthDuringInstall();
     if (codexLbAuth.legacy_auth_migrated)

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.4';
 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/retention.js

@@ -14,6 +14,7 @@ export const DEFAULT_RETENTION_POLICY = Object.freeze({
     run_gc_after_each_cycle: true,
     compact_oversize_missions: false,
     compact_closed_mission_workdirs: true,
+    compact_terminal_session_runtime_homes: true,
     prune_disposable_report_logs: false,
     max_wiki_artifacts: 40,
     max_wiki_artifact_age_days: 30,
@@ -46,7 +47,11 @@ const DISPOSABLE_MISSION_DIRS = Object.freeze([
     'tmp',
     'cycles',
     'arenas',
+    'sessions',
+    'codex-sdk-workers',
     'agents/lanes',
+    'agents/sessions',
+    'agents/codex-sdk-workers',
     'agents/tmp',
     'agents/worktrees',
     'research/cycles',
@@ -56,6 +61,10 @@ const DISPOSABLE_MISSION_FILES = Object.freeze([
     'agents/agent-intelligent-work-graph.json',
     'agents/agent-intelligent-work-graph-v2.json'
 ]);
+const DISPOSABLE_RUNTIME_HOME_DIR_NAMES = Object.freeze([
+    'codex-sdk-home',
+    'codex-sdk-workers'
+]);
 const MISSION_CLOSE_GATES = Object.freeze([
     'team-gate.json',
     'reflection-gate.json',
@@ -175,6 +184,15 @@ function proofClosed(proof) {
         return false;
     return ['verified', 'verified_partial', 'pass', 'passed'].includes(status);
 }
+function sessionsTerminal(cleanup) {
+    if (!cleanup || typeof cleanup !== 'object')
+        return false;
+    if (cleanup.all_sessions_terminal === true || cleanup.all_sessions_closed === true)
+        return true;
+    const terminal = Number(cleanup.terminal_session_count);
+    const total = Number(cleanup.total_sessions);
+    return Number.isFinite(terminal) && Number.isFinite(total) && total > 0 && terminal >= total;
+}
 async function missionClosed(mission, opts = {}) {
     const proof = await readJson(path.join(mission.path, 'completion-proof.json'), null).catch(() => null);
     if (opts.completedMissionId && mission.id === opts.completedMissionId)
@@ -195,6 +213,19 @@ async function missionClosed(mission, opts = {}) {
     }
     return false;
 }
+async function missionSessionsTerminal(mission) {
+    const cleanupFiles = [
+        'agents/agent-session-cleanup.json',
+        'team-session-cleanup.json',
+        'agent-session-cleanup.json'
+    ];
+    for (const rel of cleanupFiles) {
+        const cleanup = await readJson(path.join(mission.path, rel), null).catch(() => null);
+        if (sessionsTerminal(cleanup))
+            return true;
+    }
+    return false;
+}
 async function removePath(action, target, dryRun, actions, extra = {}) {
     const st = await fs.stat(target).catch(() => null);
     if (!st)
@@ -208,20 +239,58 @@ async function removePath(action, target, dryRun, actions, extra = {}) {
 function missionRelative(mission, file) {
     return path.relative(mission.path, file).split(path.sep).join('/');
 }
-function isPreservedSessionPath(rel) {
-    return rel.startsWith('sessions/') || rel.startsWith('agents/sessions/');
-}
 async function pruneMissionDisposableLogs(mission, dryRun, actions) {
     const files = await listFilesRecursive(mission.path, { ignore: [], maxFiles: 10000, maxDepth: 8 }).catch(() => []);
     for (const file of files) {
         const rel = missionRelative(mission, file);
-        if (isPreservedSessionPath(rel))
-            continue;
         if (!DISPOSABLE_LOG_RE.test(rel))
             continue;
         await removePath('remove_closed_mission_raw_log', file, dryRun, actions, { mission: mission.id, reason: 'closed_mission_disposable_log' });
     }
 }
+async function collectRuntimeHomeDirs(dir, depth = 10) {
+    if (depth < 0 || !(await exists(dir)))
+        return [];
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const child = path.join(dir, entry.name);
+        if (DISPOSABLE_RUNTIME_HOME_DIR_NAMES.includes(entry.name)) {
+            out.push(child);
+            continue;
+        }
+        out.push(...await collectRuntimeHomeDirs(child, depth - 1));
+    }
+    return out;
+}
+async function pruneMissionRuntimeHomeDirs(mission, action, dryRun, actions, reason) {
+    const dirs = await collectRuntimeHomeDirs(mission.path);
+    for (const dir of dirs) {
+        await removePath(action, dir, dryRun, actions, { mission: mission.id, rel: missionRelative(mission, dir), reason });
+    }
+}
+async function pruneTerminalSessionRuntimeHomes(root, policy, dryRun, actions, opts = {}) {
+    if (policy.compact_terminal_session_runtime_homes === false && opts.compactTerminalSessionRuntimeHomes !== true)
+        return;
+    const activeId = await activeMissionId(root);
+    const targetOnly = Boolean(opts.afterRoute && opts.completedMissionId && opts.sweepClosedMissions !== true);
+    const missions = targetOnly
+        ? [await missionDirById(root, opts.completedMissionId)]
+        : await listMissionDirs(root);
+    for (const mission of missions.filter(Boolean)) {
+        if (await missionClosed(mission, opts))
+            continue;
+        const active = activeId && mission.id === activeId;
+        const activeRouteTarget = Boolean(opts.afterRoute && opts.completedMissionId === mission.id);
+        if (active && !activeRouteTarget && opts.allowActiveMissionCleanup !== true)
+            continue;
+        if (!(await missionSessionsTerminal(mission)))
+            continue;
+        await pruneMissionRuntimeHomeDirs(mission, 'remove_terminal_session_runtime_home', dryRun, actions, 'terminal_agent_session_runtime_home');
+    }
+}
 async function compactClosedMissionWorkdirs(root, policy, dryRun, actions, opts = {}) {
     if (policy.compact_closed_mission_workdirs === false || opts.compactClosedMissionWorkdirs === false)
         return;
@@ -539,6 +608,8 @@ export async function enforceRetention(root, opts = {}) {
     }
     if (shouldCompactClosedMissions)
         await compactClosedMissionWorkdirs(root, policy, dryRun, actions, opts);
+    if (fullMissionSweep || opts.compactTerminalSessionRuntimeHomes === true || Boolean(opts.afterRoute && opts.completedMissionId))
+        await pruneTerminalSessionRuntimeHomes(root, policy, dryRun, actions, opts);
     if (fullMissionSweep || opts.rotateLargeJsonl === true)
         await rotateLargeJsonl(root, policy, dryRun, actions);
     await pruneDisposableReportLogs(root, policy, dryRun, actions, opts);
@@ -556,6 +627,7 @@ export async function enforceRetention(root, opts = {}) {
         protected_durable_context: DURABLE_RETENTION_CLASSES,
         disposable_mission_dirs: DISPOSABLE_MISSION_DIRS,
         disposable_mission_files: DISPOSABLE_MISSION_FILES,
+        disposable_runtime_home_dir_names: DISPOSABLE_RUNTIME_HOME_DIR_NAMES,
         prune_report_logs: Boolean(opts.pruneReportLogs || policy.prune_disposable_report_logs),
         completed_mission_id: opts.completedMissionId || null,
         actions

package/dist/core/update/update-migration-state.js

@@ -2,6 +2,7 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { ensureDir, exists, globalSksRoot, nowIso, packageRoot, PACKAGE_VERSION, projectRoot, readJson, runProcess, sha256, which, writeJsonAtomic } from '../fsx.js';
 import { MANAGED_ASSET_VERSION } from '../managed-assets/managed-assets-manifest.js';
+import { enforceRetention } from '../retention.js';
 export const UPDATE_MIGRATION_SCHEMA = 'sks.project-migration-receipt.v2';
 export const INSTALLATION_EPOCH_SCHEMA = 'sks.installation-epoch.v1';
 const ALLOWLIST_COMMANDS = new Set([
@@ -98,6 +99,7 @@ export async function clearPendingUpdateMigration() {
 export async function writeProjectUpdateMigrationReceipt(input) {
     const receiptPath = projectUpdateMigrationReceiptPath(input.root);
     const epoch = await ensureInstallationEpoch(input.source);
+    const retentionCleanup = await runUpdateRetentionCleanup(input.root, input.source);
     const requiredBlockers = input.blockers || [];
     const optionalWarnings = input.warnings || [];
     const receipt = {
@@ -113,6 +115,7 @@ export async function writeProjectUpdateMigrationReceipt(input) {
         pending_marker_path: installationEpochPath(),
         installation_epoch_path: installationEpochPath(),
         doctor: input.doctor || null,
+        retention_cleanup: retentionCleanup,
         update_stages: input.updateStages || [],
         required_blockers: requiredBlockers,
         optional_warnings: optionalWarnings,
@@ -122,6 +125,71 @@ export async function writeProjectUpdateMigrationReceipt(input) {
     await writeJsonAtomic(receiptPath, receipt);
     return receipt;
 }
+export async function runUpdateRetentionCleanup(root, source = 'update-migration') {
+    const missionsPath = path.join(root, '.sneakoscope', 'missions');
+    const cleanupPath = path.join(root, '.sneakoscope', 'reports', 'retention-cleanup.json');
+    const storagePath = path.join(root, '.sneakoscope', 'reports', 'storage.json');
+    if (process.env.SKS_UPDATE_RETENTION_CLEANUP === '0') {
+        return {
+            schema: 'sks.update-retention-cleanup.v1',
+            ok: true,
+            status: 'skipped',
+            root,
+            source,
+            generated_at: nowIso(),
+            action_count: 0,
+            cleanup_report_path: null,
+            storage_report_path: null,
+            reason: 'disabled_by_env'
+        };
+    }
+    if (!(await exists(missionsPath))) {
+        return {
+            schema: 'sks.update-retention-cleanup.v1',
+            ok: true,
+            status: 'skipped',
+            root,
+            source,
+            generated_at: nowIso(),
+            action_count: 0,
+            cleanup_report_path: null,
+            storage_report_path: null,
+            reason: 'missions_missing'
+        };
+    }
+    try {
+        const result = await enforceRetention(root, {
+            mode: 'update_migration',
+            pruneReportLogs: true,
+            policy: { max_tmp_age_hours: 0 }
+        });
+        return {
+            schema: 'sks.update-retention-cleanup.v1',
+            ok: true,
+            status: 'completed',
+            root,
+            source,
+            generated_at: nowIso(),
+            action_count: Array.isArray(result.actions) ? result.actions.length : 0,
+            cleanup_report_path: cleanupPath,
+            storage_report_path: storagePath
+        };
+    }
+    catch (err) {
+        return {
+            schema: 'sks.update-retention-cleanup.v1',
+            ok: false,
+            status: 'failed',
+            root,
+            source,
+            generated_at: nowIso(),
+            action_count: 0,
+            cleanup_report_path: null,
+            storage_report_path: null,
+            error: err?.message || String(err)
+        };
+    }
+}
 export async function ensureCurrentMigrationBeforeCommand(input) {
     const env = input.env || process.env;
     const command = input.command;

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.4';
 //# 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/dist/scripts/postinstall-safe-side-effects-check.js

@@ -11,6 +11,7 @@ const helpers = readText('src/cli/install-helpers.ts');
 assertGate(helpers.includes('SKS_POSTINSTALL_AUTO_INSTALL_CLI_TOOLS'), 'postinstall cli tool install must be gated behind SKS_POSTINSTALL_AUTO_INSTALL_CLI_TOOLS');
 // Killing a third-party app's processes is opt-in only.
 assertGate(helpers.includes("SKS_POSTINSTALL_RECONCILE_APP_PROCESSES === '1'"), 'postinstall process reconciliation must be gated behind SKS_POSTINSTALL_RECONCILE_APP_PROCESSES');
+assertGate(helpers.includes('runPostinstallProjectRetentionCleanup') && helpers.includes('SKS_POSTINSTALL_RETENTION_CLEANUP'), 'postinstall mission retention cleanup must be project-scoped and disableable');
 // Config writes are gated (unparseable preserved / unsafe rewrite skipped) and backed up.
 assertGate(helpers.includes('unparseable_config_preserved'), 'postinstall must preserve unparseable config');
 assertGate(helpers.includes('skipped_unsafe_rewrite'), 'postinstall must skip unsafe config rewrites');

package/dist/scripts/retention-cleanup-safety-check.js

@@ -38,11 +38,12 @@ try {
         '.sneakoscope/missions/M-old/completion-proof.json',
         '.sneakoscope/missions/M-old/trust-report.json',
         '.sneakoscope/missions/M-old/reflection.md',
-        '.sneakoscope/missions/M-done/sessions/terminal-transcript.log',
-        '.sneakoscope/missions/M-done/agents/sessions/session-1/terminal-transcript.log',
         '.sneakoscope/missions/M-active/team-inbox/active.md',
+        '.sneakoscope/missions/M-active/agents/sessions/session-1/gen-1/worker/codex-sdk-home/codex/cache.bin',
         '.sneakoscope/missions/M-blocked/team-inbox/blocked.md',
-        '.sneakoscope/missions/M-blocked/scout.stderr.log'
+        '.sneakoscope/missions/M-blocked/scout.stderr.log',
+        '.sneakoscope/missions/M-blocked-terminal/team-inbox/blocked.md',
+        '.sneakoscope/missions/M-blocked-terminal/agents/sessions/session-1/gen-1/worker/worker-result.json'
     ]) {
         assertGate(exists(path.join(applyRoot, rel)), `durable or active artifact was removed: ${rel}`, { rel, actions: applied.actions });
     }
@@ -51,10 +52,15 @@ try {
         '.sneakoscope/missions/M-done/team-inbox/worker.md',
         '.sneakoscope/missions/M-done/bus/event.jsonl',
         '.sneakoscope/missions/M-done/agents/lanes/lane-1.json',
+        '.sneakoscope/missions/M-done/sessions/terminal-transcript.log',
+        '.sneakoscope/missions/M-done/agents/sessions/session-1/terminal-transcript.log',
+        '.sneakoscope/missions/M-done/agents/sessions/session-1/gen-1/worker/codex-sdk-home/codex/cache.bin',
         '.sneakoscope/missions/M-done/scout.stdout.log',
         '.sneakoscope/missions/M-done/scout.stderr.log',
         '.sneakoscope/missions/M-old/team-inbox/worker.md',
+        '.sneakoscope/missions/M-old/agents/sessions/session-1/gen-1/worker/codex-sdk-home/codex/cache.bin',
         '.sneakoscope/missions/M-old/scout.stdout.log',
+        '.sneakoscope/missions/M-blocked-terminal/agents/sessions/session-1/gen-1/worker/codex-sdk-home/codex/cache.bin',
         '.sneakoscope/reports/release-parallel-logs/build.stdout.log'
     ]) {
         assertGate(!exists(path.join(applyRoot, rel)), `disposable artifact survived cleanup: ${rel}`, { rel, actions: applied.actions });
@@ -64,6 +70,7 @@ try {
     for (const kind of ['remove_tmp', 'remove_closed_mission_raw_log', 'remove_disposable_report_log_dir']) {
         assertGate(actionKinds.has(kind), `retention cleanup did not report action kind: ${kind}`, { actions: applied.actions });
     }
+    assertGate(actionKinds.has('remove_terminal_session_runtime_home'), 'retention cleanup did not remove terminal session runtime homes', { actions: applied.actions });
     assertGate(actionKinds.has('remove_closed_mission_workdir') || actionKinds.has('remove_old_mission_workdir'), 'retention cleanup did not report mission workdir cleanup', { actions: applied.actions });
     assertGate(actionKinds.has('retain_mission_durable_context'), 'retention cleanup did not preserve old durable mission context', { actions: applied.actions });
     assertGate(dry.actions.length >= applied.actions.length, 'dry-run should plan cleanup actions without deleting files', { applied: applied.actions.length, dry: dry.actions.length });
@@ -95,6 +102,7 @@ async function writeFixture(projectRoot) {
     await writeMission(projectRoot, 'M-active', false);
     await writeOldDurableMission(projectRoot);
     await writeBlockedMission(projectRoot);
+    await writeTerminalBlockedMission(projectRoot);
     await writeText(path.join(projectRoot, '.sneakoscope', 'reports', 'release-parallel-logs', 'build.stdout.log'), 'summarized release log\n');
 }
 async function writeMission(projectRoot, missionId, closed) {
@@ -110,14 +118,16 @@ async function writeMission(projectRoot, missionId, closed) {
         await write(path.join(dir, 'team-gate.json'), { passed: true });
         await write(path.join(dir, 'team-session-cleanup.json'), { passed: true, all_sessions_closed: true });
         await write(path.join(dir, 'agents', 'agent-proof-evidence.json'), { ok: true, all_sessions_closed: true });
-        await writeText(path.join(dir, 'sessions', 'terminal-transcript.log'), 'transcript stays\n');
-        await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'terminal-transcript.log'), 'agent transcript stays\n');
+        await writeText(path.join(dir, 'sessions', 'terminal-transcript.log'), 'transcript is disposable after close\n');
+        await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'terminal-transcript.log'), 'agent transcript is disposable after close\n');
+        await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'gen-1', 'worker', 'codex-sdk-home', 'codex', 'cache.bin'), 'large sdk cache\n');
         await writeText(path.join(dir, 'scout.stdout.log'), 'raw stdout\n');
         await writeText(path.join(dir, 'scout.stderr.log'), 'raw stderr\n');
         await writeText(path.join(dir, 'team-inbox', 'worker.md'), 'temporary inbox\n');
     }
     else {
         await writeText(path.join(dir, 'team-inbox', 'active.md'), 'active mission scratch stays\n');
+        await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'gen-1', 'worker', 'codex-sdk-home', 'codex', 'cache.bin'), 'active sdk cache stays\n');
     }
     await writeText(path.join(dir, 'bus', 'event.jsonl'), '{"event":"temporary"}\n');
     await writeText(path.join(dir, 'agents', 'lanes', 'lane-1.json'), '{"lane":"temporary"}\n');
@@ -129,6 +139,7 @@ async function writeOldDurableMission(projectRoot) {
     await write(path.join(dir, 'evidence-index.json'), { evidence: [] });
     await writeText(path.join(dir, 'reflection.md'), '# old retained reflection\n');
     await writeText(path.join(dir, 'team-inbox', 'worker.md'), 'old scratch\n');
+    await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'gen-1', 'worker', 'codex-sdk-home', 'codex', 'cache.bin'), 'old sdk cache\n');
     await writeText(path.join(dir, 'scout.stdout.log'), 'old raw log\n');
     await old(dir);
 }
@@ -138,6 +149,14 @@ async function writeBlockedMission(projectRoot) {
     await writeText(path.join(dir, 'team-inbox', 'blocked.md'), 'diagnostic scratch\n');
     await writeText(path.join(dir, 'scout.stderr.log'), 'diagnostic raw log\n');
 }
+async function writeTerminalBlockedMission(projectRoot) {
+    const dir = path.join(projectRoot, '.sneakoscope', 'missions', 'M-blocked-terminal');
+    await write(path.join(dir, 'completion-proof.json'), { schema: 'sks.completion-proof.v1', status: 'blocked', blockers: ['fixture_blocker'] });
+    await write(path.join(dir, 'agents', 'agent-session-cleanup.json'), { all_sessions_terminal: true, terminal_session_count: 1, total_sessions: 1 });
+    await writeText(path.join(dir, 'team-inbox', 'blocked.md'), 'diagnostic scratch\n');
+    await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'gen-1', 'worker', 'worker-result.json'), '{"status":"blocked"}\n');
+    await writeText(path.join(dir, 'agents', 'sessions', 'session-1', 'gen-1', 'worker', 'codex-sdk-home', 'codex', 'cache.bin'), 'terminal sdk cache\n');
+}
 async function write(file, data) {
     await writeText(file, `${JSON.stringify(data, null, 2)}\n`);
 }

package/dist/scripts/update-first-command-migration-check.js

@@ -8,6 +8,7 @@ assertGate(helper.includes('INSTALLATION_EPOCH_SCHEMA') && helper.includes('inst
 assertGate(helper.includes('projectUpdateMigrationReceiptPath'), 'migration helper must keep a project receipt');
 assertGate(helper.includes("'--profile', 'migration'") && helper.includes("'--machine-only'") && helper.includes("'--report-file'"), 'first normal command must repair through package-local migration Doctor machine report before continuing');
 assertGate(helper.includes('isProjectReceiptCurrentForEpoch'), 'project receipts must be compared against the current installation epoch');
+assertGate(helper.includes('runUpdateRetentionCleanup') && helper.includes('retention_cleanup'), 'project update migration receipt must run mission retention cleanup and record its receipt');
 assertGate(helper.includes('clearPendingUpdateMigration') && helper.includes('one project must not consume global migration state'), 'legacy clear helper must preserve the persistent epoch contract');
 assertGate(scriptContains('update:first-command-migration', 'update-first-command-migration-check.js'), 'package script must expose first command migration gate');
 emitGate('update:first-command-migration');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "4.6.2",
+  "version": "4.6.4",
   "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",