sneakoscope 0.9.10 → 0.9.12

package/README.md

@@ -1,6 +1,24 @@
 # Sneakoscope Codex
 
-Sneakoscope Codex (`sks`) is a Codex CLI/App harness for repeatable workflows. It adds terminal commands, Codex App `$` commands, tmux workspaces, Team/QA/Research routes, pipeline plans, Computer Use, imagegen UI/UX review, Goal, Context7, DB safety, TriWiki, design-system routing, skill dreaming, Honest Mode.
+Fast proof-first Codex trust layer with image-based Voxel TriWiki.
+
+Sneakoscope Codex (`sks`) is a Codex CLI/App harness for repeatable workflows. It adds terminal commands, Codex App `$` commands, tmux workspaces, Team/QA/Research routes, pipeline plans, Computer Use, imagegen UI/UX review, Goal, Context7, DB safety, Voxel TriWiki, design-system routing, skill dreaming, completion proof, and Honest Mode.
+
+## 60-second start
+
+```sh
+npm i -g sneakoscope
+sks root
+sks doctor
+sks codex-app check
+sks selftest --mock
+```
+
+## Three core promises
+
+1. Image-based Voxel TriWiki memory
+2. Codex App / codex-lb operational readiness
+3. Completion proof for every serious route
 
 ## Quick Start
 
@@ -12,6 +30,8 @@ sks root
 sks
 ```
 
+`0.9.12` adds the lazy CLI architecture foundation, `sks proof`, image voxel ledger commands, cold-start perf checks, hook trust reports, codex-lb circuit metrics, and feature fixture contracts. Rust accelerator source is included in the npm package; until prebuilt binaries ship, SKS uses JS fallbacks unless `SKS_RS_BIN` or a source-checkout `sks-rs` binary is available.
+
 `npm i -g sneakoscope` automatically refreshes the `sks` command shim, global Codex App `$` skills, and SKS bootstrap surface. When the install is run from a project, postinstall bootstraps that project. When it is run outside a repo/project marker, postinstall bootstraps the per-user global runtime root instead of writing `.sneakoscope` into a random current directory. `sks root` tells you which root SKS will use.
 
 If you only want a one-shot run without keeping `sks` installed globally:

package/crates/sks-core/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "sks-core"
+version = "0.9.12"

package/crates/sks-core/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "sks-core"
+version = "0.9.12"
+edition = "2021"
+
+[dependencies]
+
+[[bin]]
+name = "sks-rs"
+path = "src/main.rs"

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

@@ -0,0 +1,62 @@
+use std::fs::File;
+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 0.9.12"),
+        Some("compact-info") => {
+            let mut input = String::new();
+            let _ = io::stdin().read_to_string(&mut input);
+            println!("{{\"ok\":true,\"engine\":\"rust\",\"input_bytes\":{}}}", input.as_bytes().len());
+        }
+        Some("jsonl-tail") => {
+            let path = args.next().unwrap_or_default();
+            let mut bytes: u64 = 262144;
+            while let Some(arg) = args.next() {
+                if arg == "--bytes" {
+                    if let Some(raw) = args.next() {
+                        bytes = raw.parse().unwrap_or(bytes);
+                    }
+                }
+            }
+            match tail_file(&path, bytes) {
+                Ok(text) => print!("{}", text),
+                Err(err) => {
+                    eprintln!("{}", err);
+                    std::process::exit(1);
+                }
+            }
+        }
+        Some("secret-scan") => {
+            let path = args.next().unwrap_or_default();
+            match std::fs::read_to_string(&path) {
+                Ok(text) => {
+                    let found = ["CODEX_ACCESS_TOKEN", "OPENAI_API_KEY", "CODEX_LB_API_KEY", "sk-proj-", "sk-clb-", "github_pat_"]
+                        .iter()
+                        .any(|needle| text.contains(needle));
+                    println!("{{\"ok\":{},\"engine\":\"rust\",\"findings\":{}}}", if found { "false" } else { "true" }, if found { 1 } else { 0 });
+                    if found { std::process::exit(1); }
+                }
+                Err(err) => {
+                    eprintln!("{}", err);
+                    std::process::exit(1);
+                }
+            }
+        }
+        _ => {
+            eprintln!("sks-rs optional accelerator. Commands: --version, compact-info, jsonl-tail, secret-scan");
+            std::process::exit(2);
+        }
+    }
+}
+
+fn tail_file(path: &str, bytes: u64) -> io::Result<String> {
+    let mut file = File::open(path)?;
+    let len = file.metadata()?.len();
+    let start = len.saturating_sub(bytes);
+    file.seek(SeekFrom::Start(start))?;
+    let mut out = String::new();
+    file.read_to_string(&mut out)?;
+    Ok(out)
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.9.10",
-  "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Goal, AutoResearch, TriWiki, and Honest Mode.",
+  "version": "0.9.12",
+  "description": "Sneakoscope Codex: fast proof-first Codex trust layer with image-based Voxel TriWiki.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
   "repository": {
@@ -23,6 +23,9 @@
   "files": [
     "bin",
     "src",
+    "crates/sks-core/Cargo.lock",
+    "crates/sks-core/Cargo.toml",
+    "crates/sks-core/src",
     "README.md",
     "LICENSE"
   ],
@@ -36,11 +39,18 @@
     "doctor": "node ./bin/sks.mjs doctor",
     "packcheck": "find bin src scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check",
     "changelog:check": "node ./scripts/changelog-check.mjs",
+    "cli-entrypoint:check": "node ./scripts/check-cli-entrypoint.mjs",
     "sizecheck": "node ./scripts/sizecheck.mjs",
     "registry:check": "node ./scripts/release-registry-check.mjs",
     "feature:check": "node ./bin/sks.mjs features check --json",
     "all-features:selftest": "node ./bin/sks.mjs all-features selftest --mock --json",
-    "release:check": "npm run repo-audit && npm run changelog:check && npm run packcheck && npm run feature:check && npm run all-features:selftest && npm run selftest && npm run sizecheck && npm run registry:check",
+    "perf:cold-start": "node ./bin/sks.mjs perf cold-start --json",
+    "perf:gate": "node ./scripts/perf-gate.mjs",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "test:unit": "node --test \"test/unit/**/*.test.mjs\"",
+    "test:integration:mock": "node --test \"test/integration/**/*.test.mjs\"",
+    "coverage": "node --experimental-test-coverage --test \"test/**/*.test.mjs\"",
+    "release:check": "npm run repo-audit && npm run changelog:check && npm run cli-entrypoint:check && npm run packcheck && npm run feature:check && npm run all-features:selftest && npm run selftest && npm run test:unit && npm run test:integration:mock && npm run perf:gate && npm run sizecheck && npm run registry:check",
     "publish:dry": "npm run release:check && npm --cache /tmp/sks-npm-cache publish --dry-run --registry https://registry.npmjs.org/ --access public",
     "publish:npm": "npm --cache /tmp/sks-npm-cache publish --registry https://registry.npmjs.org/ --access public",
     "prepublishOnly": "npm run release:check && node ./scripts/release-registry-check.mjs --require-unpublished"

package/src/cli/args.mjs

@@ -0,0 +1,49 @@
+export function flag(args = [], name) {
+  return args.includes(name);
+}
+
+export function readOption(args = [], name, fallback = null) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+export function positionalArgs(args = []) {
+  const out = [];
+  const valueFlags = new Set([
+    '--source',
+    '--format',
+    '--iterations',
+    '--out',
+    '--baseline',
+    '--candidate',
+    '--install-scope',
+    '--max-cycles',
+    '--cycle-timeout-minutes',
+    '--depth',
+    '--scope',
+    '--transport',
+    '--query',
+    '--topic',
+    '--tokens',
+    '--timeout-ms',
+    '--sql',
+    '--command',
+    '--project-ref',
+    '--agent',
+    '--phase',
+    '--message',
+    '--role',
+    '--max-anchors',
+    '--lines',
+    '--dir'
+  ]);
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i]);
+    if (valueFlags.has(arg)) {
+      i += 1;
+      continue;
+    }
+    if (!arg.startsWith('--')) out.push(arg);
+  }
+  return out;
+}

package/src/cli/command-registry.mjs

@@ -0,0 +1,128 @@
+const legacy = () => import('./legacy-main.mjs');
+
+export const COMMANDS = {
+  help: {
+    maturity: 'stable',
+    summary: 'Show SKS help',
+    lazy: () => import('../commands/help.mjs')
+  },
+  version: {
+    maturity: 'stable',
+    summary: 'Show SKS version',
+    lazy: () => import('../commands/version.mjs')
+  },
+  commands: {
+    maturity: 'stable',
+    summary: 'List SKS commands',
+    lazy: () => import('../commands/help.mjs')
+  },
+  root: {
+    maturity: 'stable',
+    summary: 'Show active SKS root',
+    lazy: () => import('../commands/root.mjs')
+  },
+  features: {
+    maturity: 'beta',
+    summary: 'Validate feature registry',
+    lazy: () => import('../commands/features.mjs')
+  },
+  'all-features': {
+    maturity: 'beta',
+    summary: 'Run all-features selftest',
+    lazy: () => import('../commands/all-features.mjs')
+  },
+  hooks: {
+    maturity: 'beta',
+    summary: 'Explain and inspect Codex hooks',
+    lazy: () => import('../commands/hooks.mjs')
+  },
+  proof: {
+    maturity: 'beta',
+    summary: 'Show and validate completion proof',
+    lazy: () => import('../commands/proof.mjs')
+  },
+  wiki: {
+    maturity: 'beta',
+    summary: 'Manage TriWiki and image voxel ledgers',
+    lazy: () => import('../commands/wiki.mjs')
+  },
+  perf: {
+    maturity: 'beta',
+    summary: 'Run performance checks',
+    lazy: () => import('../commands/perf.mjs')
+  },
+  'codex-lb': {
+    maturity: 'beta',
+    summary: 'Inspect codex-lb status and circuit health',
+    lazy: () => import('../commands/codex-lb.mjs')
+  },
+  auth: {
+    maturity: 'beta',
+    summary: 'Alias for codex-lb auth commands',
+    lazy: () => import('../commands/codex-lb.mjs')
+  },
+  postinstall: { maturity: 'stable', summary: 'Run postinstall bootstrap', lazy: legacy },
+  wizard: { maturity: 'stable', summary: 'Open setup wizard', lazy: legacy },
+  ui: { maturity: 'stable', summary: 'Open setup UI', lazy: legacy },
+  'update-check': { maturity: 'stable', summary: 'Check npm package freshness', lazy: legacy },
+  usage: { maturity: 'stable', summary: 'Show focused usage topic', lazy: legacy },
+  quickstart: { maturity: 'stable', summary: 'Show quickstart flow', lazy: legacy },
+  'codex-app': { maturity: 'beta', summary: 'Check Codex App readiness', lazy: legacy },
+  openclaw: { maturity: 'labs', summary: 'Create OpenClaw skill package', lazy: legacy },
+  bootstrap: { maturity: 'stable', summary: 'Initialize SKS project files', lazy: legacy },
+  deps: { maturity: 'stable', summary: 'Check or install local dependencies', lazy: legacy },
+  'qa-loop': { maturity: 'beta', summary: 'Run QA loop missions', lazy: legacy },
+  ppt: { maturity: 'labs', summary: 'Inspect/build PPT artifacts', lazy: legacy },
+  'image-ux-review': { maturity: 'labs', summary: 'Inspect image UX artifacts', lazy: legacy },
+  'ux-review': { maturity: 'labs', summary: 'Alias for image UX review', lazy: legacy },
+  'visual-review': { maturity: 'labs', summary: 'Alias for image UX review', lazy: legacy },
+  'ui-ux-review': { maturity: 'labs', summary: 'Alias for image UX review', lazy: legacy },
+  context7: { maturity: 'beta', summary: 'Context7 checks and docs', lazy: legacy },
+  recallpulse: { maturity: 'labs', summary: 'RecallPulse evidence route', lazy: legacy },
+  pipeline: { maturity: 'beta', summary: 'Inspect pipeline missions', lazy: legacy },
+  guard: { maturity: 'beta', summary: 'Check harness guard', lazy: legacy },
+  conflicts: { maturity: 'beta', summary: 'Check harness conflicts', lazy: legacy },
+  versioning: { maturity: 'stable', summary: 'Manage release version metadata', lazy: legacy },
+  reasoning: { maturity: 'labs', summary: 'Show reasoning route', lazy: legacy },
+  aliases: { maturity: 'stable', summary: 'Show command aliases', lazy: legacy },
+  setup: { maturity: 'stable', summary: 'Initialize SKS state', lazy: legacy },
+  'fix-path': { maturity: 'stable', summary: 'Repair hook command paths', lazy: legacy },
+  doctor: { maturity: 'stable', summary: 'Check and repair SKS install', lazy: legacy },
+  init: { maturity: 'stable', summary: 'Initialize local control surface', lazy: legacy },
+  selftest: { maturity: 'stable', summary: 'Run local mock selftest', lazy: legacy },
+  goal: { maturity: 'beta', summary: 'Manage Goal bridge workflow', lazy: legacy },
+  research: { maturity: 'labs', summary: 'Run research missions', lazy: legacy },
+  hook: { maturity: 'beta', summary: 'Codex hook entrypoint', lazy: legacy },
+  profile: { maturity: 'labs', summary: 'Inspect/set profile', lazy: legacy },
+  hproof: { maturity: 'beta', summary: 'Evaluate H-Proof gate', lazy: legacy },
+  'validate-artifacts': { maturity: 'beta', summary: 'Validate mission artifacts', lazy: legacy },
+  'proof-field': { maturity: 'beta', summary: 'Scan proof field', lazy: legacy },
+  'skill-dream': { maturity: 'labs', summary: 'Track skill dream counters', lazy: legacy },
+  'code-structure': { maturity: 'labs', summary: 'Scan source structure', lazy: legacy },
+  memory: { maturity: 'labs', summary: 'Run retention checks', lazy: legacy },
+  gx: { maturity: 'labs', summary: 'Render/validate GX cartridges', lazy: legacy },
+  team: { maturity: 'beta', summary: 'Create and observe Team missions', lazy: legacy },
+  db: { maturity: 'beta', summary: 'Inspect DB safety policy', lazy: legacy },
+  eval: { maturity: 'labs', summary: 'Run eval reports', lazy: legacy },
+  harness: { maturity: 'labs', summary: 'Run harness fixtures', lazy: legacy },
+  gc: { maturity: 'labs', summary: 'Compact/prune runtime state', lazy: legacy },
+  stats: { maturity: 'labs', summary: 'Show storage stats', lazy: legacy },
+  tmux: { maturity: 'beta', summary: 'Open/check SKS tmux UI', lazy: legacy },
+  'auto-review': { maturity: 'beta', summary: 'Manage auto-review profile', lazy: legacy },
+  autoreview: { maturity: 'beta', summary: 'Alias for auto-review', lazy: legacy },
+  'dollar-commands': { maturity: 'stable', summary: 'List Codex App dollar commands', lazy: legacy },
+  dollars: { maturity: 'stable', summary: 'Alias for dollar-commands', lazy: legacy },
+  '$': { maturity: 'stable', summary: 'Alias for dollar-commands', lazy: legacy },
+  dfix: { maturity: 'stable', summary: 'Explain DFix route', lazy: legacy }
+};
+
+export const COMMAND_ALIASES = {
+  '--help': 'help',
+  '-h': 'help',
+  '--version': 'version',
+  '-v': 'version'
+};
+
+export function commandNames() {
+  return Object.keys(COMMANDS).sort();
+}

package/src/cli/feature-commands.mjs

@@ -1,6 +1,8 @@
 import path from 'node:path';
-import { projectRoot } from '../core/fsx.mjs';
+import os from 'node:os';
+import { exists, projectRoot, readJson } from '../core/fsx.mjs';
 import { CODEX_ACCESS_TOKENS_DOCS_URL } from '../core/codex-app.mjs';
+import { redactSecrets } from '../core/secret-redaction.mjs';
 import { buildAllFeaturesSelftest, buildFeatureRegistry, validateFeatureRegistry, writeFeatureInventoryDocs } from '../core/feature-registry.mjs';
 
 const flag = (args, name) => args.includes(name);
@@ -59,10 +61,33 @@ export async function allFeaturesCommand(sub = 'selftest', args = []) {
   if (!result.ok) process.exitCode = 1;
 }
 
-export function hooksCommand(sub = 'explain', args = []) {
+export async function hooksCommand(sub = 'explain', args = []) {
   const action = sub || 'explain';
-  if (action !== 'explain' && action !== 'status') {
-    console.error('Usage: sks hooks explain [--json]');
+  const root = await projectRoot();
+  if (action === 'status') {
+    const report = await hooksStatusReport(root);
+    if (flag(args, '--json')) return console.log(JSON.stringify(report, null, 2));
+    console.log(`Hooks: ${report.ok ? 'ok' : 'missing'}`);
+    for (const file of report.hooks_files) console.log(`- ${file.path}: ${file.exists ? 'present' : 'missing'}`);
+    return;
+  }
+  if (action === 'trust-report') {
+    const report = await hooksTrustReport(root);
+    if (flag(args, '--json')) return console.log(JSON.stringify(report, null, 2));
+    console.log(`Hooks trust report: ${report.ok ? 'ok' : 'blocked'}`);
+    for (const event of report.events) console.log(`- ${event.event}: ${event.command}`);
+    return;
+  }
+  if (action === 'replay') {
+    const fixture = args.find((arg) => !String(arg).startsWith('--'));
+    const report = await hooksReplayReport(fixture);
+    if (flag(args, '--json')) return console.log(JSON.stringify(report, null, 2));
+    console.log(`Hook replay: ${report.ok ? 'ok' : 'blocked'} ${report.event || 'unknown'}`);
+    if (report.decision) console.log(`Decision: ${report.decision}`);
+    return;
+  }
+  if (action !== 'explain') {
+    console.error('Usage: sks hooks explain|status|trust-report|replay <fixture.json> [--json]');
     process.exitCode = 1;
     return;
   }
@@ -80,6 +105,56 @@ export function hooksCommand(sub = 'explain', args = []) {
   for (const source of report.sources) console.log(`- ${source.title}: ${source.url}`);
 }
 
+async function hooksStatusReport(root) {
+  const files = [
+    path.join(os.homedir(), '.codex', 'hooks.json'),
+    path.join(root, '.codex', 'hooks.json')
+  ];
+  const hooksFiles = [];
+  for (const file of files) {
+    hooksFiles.push({ path: file, exists: await exists(file) });
+  }
+  return {
+    schema: 'sks.hooks-status.v1',
+    hooks_files: hooksFiles,
+    ok: hooksFiles.some((file) => file.exists)
+  };
+}
+
+async function hooksTrustReport(root) {
+  const status = await hooksStatusReport(root);
+  return redactSecrets({
+    schema: 'sks.hooks-trust-report.v1',
+    hooks_files: status.hooks_files.map((file) => file.path),
+    events: [
+      { event: 'PreToolUse', command: 'sks hook pre-tool', writes: ['.sneakoscope/bus/tool-events.jsonl'], network: false, secret_policy: 'redacted', risk: 'medium' },
+      { event: 'PermissionRequest', command: 'sks hook permission-request', writes: ['.sneakoscope/state'], network: false, secret_policy: 'redacted', risk: 'medium' },
+      { event: 'UserPromptSubmit', command: 'sks hook user-prompt-submit', writes: ['.sneakoscope/missions'], network: false, secret_policy: 'redacted', risk: 'medium' },
+      { event: 'Stop', command: 'sks hook stop', writes: ['.sneakoscope/missions', '.sneakoscope/proof'], network: false, secret_policy: 'redacted', risk: 'high' }
+    ],
+    ok: true,
+    warnings: status.ok ? [] : ['no hooks.json file found in project or user config']
+  });
+}
+
+async function hooksReplayReport(fixturePath) {
+  if (!fixturePath) return { schema: 'sks.hooks-replay.v1', ok: false, reason: 'fixture_required' };
+  const fixture = await readJson(path.resolve(fixturePath), {});
+  const command = fixture.command || fixture.tool_input?.command || fixture.toolInput?.command || fixture.input?.command || '';
+  const event = fixture.event || fixture.hook_event_name || fixture.name || 'unknown';
+  const dangerousDb = /\b(?:drop\s+table|delete\s+from|truncate|supabase\s+db\s+reset)\b/i.test(command);
+  const missingProof = /route-without-proof|without-proof/i.test(fixturePath) || fixture.requires_proof === true;
+  return redactSecrets({
+    schema: 'sks.hooks-replay.v1',
+    ok: !dangerousDb && !missingProof,
+    event,
+    command,
+    decision: dangerousDb || missingProof ? 'block' : 'continue',
+    reason: dangerousDb ? 'dangerous_database_command' : (missingProof ? 'route_completion_without_proof' : 'fixture_safe'),
+    secret_policy: 'redacted'
+  });
+}
+
 export function hooksExplainReport() {
   return {
     schema: 'sks.hooks-explain.v1',

package/src/cli/install-helpers.mjs

@@ -3,7 +3,7 @@ import os from 'node:os';
 import fsp from 'node:fs/promises';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
-import { ensureDir, exists, globalSksRoot, packageRoot, readText, runProcess, tmpdir, which, writeTextAtomic } from '../core/fsx.mjs';
+import { ensureDir, exists, globalSksRoot, packageRoot, PACKAGE_VERSION, readText, runProcess, tmpdir, which, writeTextAtomic } from '../core/fsx.mjs';
 import { getCodexInfo } from '../core/codex-adapter.mjs';
 import { formatHarnessConflictReport, llmHarnessCleanupPrompt, scanHarnessConflicts } from '../core/harness-conflicts.mjs';
 import { initProject, installSkills } from '../core/init.mjs';
@@ -32,6 +32,7 @@ export async function postinstall({ bootstrap }) {
   console.log('\nSKS installed.');
   const shim = await ensureSksCommandDuringInstall();
   if (shim.status === 'present') console.log(`SKS command: available (${shim.command}).`);
+  else if (shim.status === 'repaired') console.log(`SKS command: stale PATH shim repaired (${shim.command}).`);
   else if (shim.status === 'created') console.log(`SKS command: shim created at ${shim.command}.`);
   else if (shim.status === 'created_not_on_path') console.log(`SKS command: shim created at ${shim.command}. Add ${path.dirname(shim.command)} to PATH, or run npx -y -p sneakoscope sks.`);
   else if (shim.status === 'skipped') console.log(`SKS command: skipped (${shim.reason}).`);
@@ -1367,10 +1368,13 @@ function escapeRegExp(value) {
 export async function ensureSksCommandDuringInstall(opts = {}) {
   if (process.env.SKS_SKIP_POSTINSTALL_SHIM === '1' && !opts.force) return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_SHIM=1' };
   const pathEnv = opts.pathEnv ?? process.env.PATH ?? '';
-  const existing = await findCommandOnPath('sks', pathEnv);
-  if (isStableSksBin(existing)) return { status: 'present', command: existing };
   const nodeBin = opts.nodeBin || process.execPath;
   const target = opts.target || path.join(packageRoot(), 'bin', 'sks.mjs');
+  const repair = await reconcileSksPathShimsDuringInstall({ ...opts, pathEnv, nodeBin, target });
+  if (repair.status === 'repaired') return { ...repair, command: repair.command || repair.repaired?.[0]?.path || target };
+  if (repair.status === 'failed') return repair;
+  const existing = await findCommandOnPath('sks', pathEnv);
+  if (isStableSksBin(existing)) return { status: 'present', command: existing };
   const dirs = candidateShimDirs(pathEnv, opts.home || process.env.HOME);
   const script = process.platform === 'win32'
     ? `@echo off\r\n"${nodeBin}" "${target}" %*\r\n`
@@ -1394,6 +1398,80 @@ export async function ensureSksCommandDuringInstall(opts = {}) {
   return { status: 'failed', error: lastError };
 }
 
+export async function selftestSksShimRepair() {
+  const staleShimTmp = tmpdir();
+  const staleBin = path.join(staleShimTmp, 'old-prefix', 'bin');
+  const stalePkg = path.join(staleShimTmp, 'old-prefix', 'lib', 'node_modules', 'sneakoscope');
+  await ensureDir(path.join(stalePkg, 'bin'));
+  await ensureDir(staleBin);
+  await writeTextAtomic(path.join(stalePkg, 'package.json'), JSON.stringify({ name: 'sneakoscope', version: '0.0.1' }, null, 2));
+  await writeTextAtomic(path.join(stalePkg, 'bin', 'sks.mjs'), '#!/usr/bin/env node\nconsole.log("sneakoscope 0.0.1");\n');
+  await fsp.chmod(path.join(stalePkg, 'bin', 'sks.mjs'), 0o755).catch(() => {});
+  await fsp.symlink(path.join(stalePkg, 'bin', 'sks.mjs'), path.join(staleBin, 'sks'));
+  const repair = await ensureSksCommandDuringInstall({ force: true, pathEnv: staleBin, home: path.join(staleShimTmp, 'home') });
+  if (repair.status !== 'repaired') throw new Error(`selftest: stale global sks shim was not repaired (${repair.status})`);
+  const run = await runProcess(path.join(staleBin, 'sks'), ['--version'], { timeoutMs: 10000, maxOutputBytes: 16 * 1024 });
+  if (run.code !== 0 || !String(run.stdout || '').includes(PACKAGE_VERSION)) throw new Error('selftest: repaired stale sks shim does not run current package version');
+  return { ok: true, repaired: repair.repaired || [] };
+}
+
+async function reconcileSksPathShimsDuringInstall(opts = {}) {
+  if (process.env.SKS_SKIP_POSTINSTALL_SHIM_REPAIR === '1' && !opts.force) return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_SHIM_REPAIR=1' };
+  const target = opts.target || path.join(packageRoot(), 'bin', 'sks.mjs');
+  const nodeBin = opts.nodeBin || process.execPath;
+  const currentVersion = await installedPackageVersion(packageRoot());
+  const commands = await findCommandsOnPath(['sks', 'sneakoscope'], opts.pathEnv ?? process.env.PATH ?? '');
+  const repaired = [];
+  const failed = [];
+  for (const command of commands) {
+    const info = await inspectSksPathShim(command.path, { target, currentVersion });
+    if (!info.repairable) continue;
+    const script = process.platform === 'win32'
+      ? `@echo off\r\n"${nodeBin}" "${target}" %*\r\n`
+      : `#!/bin/sh\nexec "${nodeBin}" "${target}" "$@"\n`;
+    try {
+      await writeTextAtomic(command.path, script);
+      if (process.platform !== 'win32') await fsp.chmod(command.path, 0o755).catch(() => {});
+      repaired.push({ path: command.path, name: command.name, previous_version: info.version || null, target });
+    } catch (err) {
+      failed.push({ path: command.path, name: command.name, previous_version: info.version || null, error: err.message });
+    }
+  }
+  if (repaired.length) return { status: 'repaired', command: repaired[0].path, repaired, failed };
+  if (failed.length) return { status: 'failed', error: failed.map((entry) => `${entry.path}: ${entry.error}`).join('; '), failed };
+  return { status: 'present' };
+}
+
+async function inspectSksPathShim(candidate, opts = {}) {
+  if (!candidate || isTransientNpmBinPath(candidate)) return { repairable: false, reason: 'transient_or_missing' };
+  const target = path.resolve(opts.target || path.join(packageRoot(), 'bin', 'sks.mjs'));
+  const resolved = await fsp.realpath(candidate).catch(() => candidate);
+  if (path.resolve(resolved) === target) return { repairable: false, reason: 'current_target' };
+  const packageDir = sksPackageRootForBin(resolved) || sksPackageRootForBin(candidate);
+  if (!packageDir) return { repairable: false, reason: 'not_sneakoscope_bin' };
+  const version = await installedPackageVersion(packageDir);
+  const currentVersion = opts.currentVersion || await installedPackageVersion(packageRoot());
+  if (!version || !currentVersion || compareVersions(version, currentVersion) >= 0) return { repairable: false, reason: 'not_older', version, current_version: currentVersion };
+  return { repairable: true, version, current_version: currentVersion, package_dir: packageDir, resolved };
+}
+
+function sksPackageRootForBin(file) {
+  const normalized = String(file || '').split(path.sep).join('/');
+  const marker = '/node_modules/sneakoscope/bin/';
+  const idx = normalized.lastIndexOf(marker);
+  if (idx < 0) return null;
+  return normalized.slice(0, idx + '/node_modules/sneakoscope'.length).split('/').join(path.sep);
+}
+
+async function installedPackageVersion(root) {
+  const pkg = await readJsonMaybe(path.join(root, 'package.json'));
+  return pkg?.version || (root === packageRoot() ? PACKAGE_VERSION : null);
+}
+
+async function readJsonMaybe(file) {
+  try { return JSON.parse(await fsp.readFile(file, 'utf8')); } catch { return null; }
+}
+
 function candidateShimDirs(pathEnv, home) {
   const seen = new Set();
   const out = [];
@@ -1413,14 +1491,26 @@ function candidateShimDirs(pathEnv, home) {
 }
 
 async function findCommandOnPath(name, pathEnv) {
+  const found = await findCommandsOnPath([name], pathEnv);
+  return found[0]?.path || null;
+}
+
+async function findCommandsOnPath(names, pathEnv) {
   const suffixes = process.platform === 'win32' ? ['.cmd', '.exe', ''] : [''];
+  const out = [];
+  const seen = new Set();
   for (const dir of String(pathEnv || '').split(path.delimiter).filter(Boolean)) {
-    for (const suffix of suffixes) {
-      const candidate = path.join(dir, `${name}${suffix}`);
-      if (await exists(candidate)) return candidate;
+    for (const name of names) {
+      for (const suffix of suffixes) {
+        const candidate = path.join(dir, `${name}${suffix}`);
+        const key = path.resolve(candidate);
+        if (seen.has(key) || !await exists(candidate)) continue;
+        seen.add(key);
+        out.push({ name, path: candidate });
+      }
     }
   }
-  return null;
+  return out;
 }
 
 async function ensureGlobalContext7DuringInstall() {