sneakoscope 0.3.0

package/src/core/fsx.mjs

@@ -0,0 +1,328 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+export const PACKAGE_VERSION = '0.3.0';
+export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
+export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function sha256(input) {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+export function randomId(len = 6) {
+  return crypto.randomBytes(Math.ceil(len / 2)).toString('hex').slice(0, len);
+}
+
+export async function exists(p) {
+  try { await fsp.access(p); return true; } catch { return false; }
+}
+
+export async function ensureDir(p) {
+  await fsp.mkdir(p, { recursive: true });
+}
+
+export async function readText(p, fallback = undefined) {
+  try { return await fsp.readFile(p, 'utf8'); }
+  catch (err) { if (fallback !== undefined) return fallback; throw err; }
+}
+
+export async function writeTextAtomic(p, text) {
+  await ensureDir(path.dirname(p));
+  const tmp = `${p}.${process.pid}.${randomId(6)}.tmp`;
+  const handle = await fsp.open(tmp, 'w');
+  try {
+    await handle.writeFile(text, 'utf8');
+    await handle.sync().catch(() => {});
+  } finally {
+    await handle.close().catch(() => {});
+  }
+  await fsp.rename(tmp, p);
+}
+
+export async function readJson(p, fallback = undefined) {
+  try { return JSON.parse(await fsp.readFile(p, 'utf8')); }
+  catch (err) { if (fallback !== undefined) return fallback; throw err; }
+}
+
+export async function writeJsonAtomic(p, data) {
+  await writeTextAtomic(p, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export async function appendJsonl(p, obj) {
+  await ensureDir(path.dirname(p));
+  await fsp.appendFile(p, `${JSON.stringify(obj)}\n`, 'utf8');
+}
+
+export async function appendJsonlBounded(p, obj, maxBytes = 5 * 1024 * 1024) {
+  await appendJsonl(p, obj);
+  try {
+    const st = await fsp.stat(p);
+    if (st.size <= maxBytes) return;
+    const keep = Math.max(1024, Math.floor(maxBytes / 2));
+    const handle = await fsp.open(p, 'r');
+    try {
+      const start = Math.max(0, st.size - keep);
+      const buf = Buffer.alloc(st.size - start);
+      await handle.read(buf, 0, buf.length, start);
+      const marker = Buffer.from(JSON.stringify({ ts: nowIso(), type: 'log.rotated', kept_tail_bytes: buf.length }) + '\n');
+      await writeTextAtomic(p, `${marker.toString('utf8')}${buf.toString('utf8').replace(/^.*?\n/, '')}`);
+    } finally {
+      await handle.close().catch(() => {});
+    }
+  } catch {}
+}
+
+export async function copyFileIfMissing(src, dest) {
+  if (await exists(dest)) return false;
+  await ensureDir(path.dirname(dest));
+  await fsp.copyFile(src, dest);
+  return true;
+}
+
+export async function mergeManagedBlock(file, markerName, content) {
+  const begin = `<!-- BEGIN ${markerName} -->`;
+  const end = `<!-- END ${markerName} -->`;
+  const block = `${begin}\n${content.trim()}\n${end}\n`;
+  const current = await readText(file, '');
+  if (!current.trim()) {
+    await writeTextAtomic(file, `${block}\n`);
+    return 'created';
+  }
+  const beginIdx = current.indexOf(begin);
+  const endIdx = current.indexOf(end);
+  if (beginIdx >= 0 && endIdx >= beginIdx) {
+    const afterEnd = endIdx + end.length;
+    const next = `${current.slice(0, beginIdx)}${block}${current.slice(afterEnd).replace(/^\n/, '')}`;
+    await writeTextAtomic(file, next);
+    return 'updated';
+  }
+  await writeTextAtomic(file, `${current.replace(/\s*$/, '\n\n')}${block}\n`);
+  return 'appended';
+}
+
+export function packageRoot() {
+  return path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+}
+
+export function cwd() { return process.cwd(); }
+
+export async function findUp(start, names) {
+  let dir = path.resolve(start);
+  const root = path.parse(dir).root;
+  while (true) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      if (await exists(candidate)) return candidate;
+    }
+    if (dir === root) return null;
+    dir = path.dirname(dir);
+  }
+}
+
+export async function projectRoot(start = process.cwd()) {
+  const resolved = path.resolve(start);
+  const sine = await findUp(resolved, ['.sneakoscope', '.dcodex']);
+  if (sine) {
+    const root = path.dirname(sine);
+    if (root !== path.parse(root).root) return root;
+  }
+  const git = await findUp(resolved, ['.git']);
+  if (git) {
+    const root = path.dirname(git);
+    if (root !== path.parse(root).root) return root;
+  }
+  return resolved;
+}
+
+export async function isGitRepo(root = process.cwd()) {
+  return exists(path.join(root, '.git'));
+}
+
+export function rel(root, p) {
+  return path.relative(root, p).split(path.sep).join('/');
+}
+
+export async function listFilesRecursive(dir, opts = {}) {
+  const {
+    ignore = ['.git', 'node_modules', '.sneakoscope/arenas', '.sneakoscope/tmp'],
+    maxFiles = 50000,
+    maxDepth = 40
+  } = opts;
+  const out = [];
+  async function walk(d, depth) {
+    if (out.length >= maxFiles || depth > maxDepth) return;
+    let entries = [];
+    try { entries = await fsp.readdir(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (out.length >= maxFiles) return;
+      const p = path.join(d, e.name);
+      const rp = rel(dir, p);
+      if (ignore.some((ig) => rp === ig || rp.startsWith(`${ig}/`))) continue;
+      if (e.isSymbolicLink?.()) continue;
+      if (e.isDirectory()) await walk(p, depth + 1);
+      else if (e.isFile()) out.push(p);
+    }
+  }
+  await walk(dir, 0);
+  return out;
+}
+
+export async function which(cmd) {
+  const paths = (process.env.PATH || '').split(path.delimiter);
+  const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
+  for (const p of paths) {
+    for (const ext of exts) {
+      const candidate = path.join(p, `${cmd}${ext}`);
+      if (await exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+class TailBuffer {
+  constructor(limitBytes) {
+    this.limit = Math.max(1024, limitBytes || DEFAULT_PROCESS_TAIL_BYTES);
+    this.parts = [];
+    this.bytes = 0;
+    this.totalBytes = 0;
+    this.truncated = false;
+  }
+  push(chunk) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    this.parts.push(buf);
+    this.bytes += buf.length;
+    this.totalBytes += buf.length;
+    while (this.bytes > this.limit && this.parts.length) {
+      const first = this.parts[0];
+      const excess = this.bytes - this.limit;
+      this.truncated = true;
+      if (first.length <= excess) {
+        this.parts.shift();
+        this.bytes -= first.length;
+      } else {
+        this.parts[0] = first.subarray(excess);
+        this.bytes -= excess;
+      }
+    }
+  }
+  text() { return Buffer.concat(this.parts, this.bytes).toString('utf8'); }
+}
+
+export function runProcess(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const tailBytes = options.maxOutputBytes ?? DEFAULT_PROCESS_TAIL_BYTES;
+    const stdoutTail = new TailBuffer(tailBytes);
+    const stderrTail = new TailBuffer(tailBytes);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PROCESS_TIMEOUT_MS;
+    let killedByTimeout = false;
+    let settled = false;
+    let stdoutStream = null;
+    let stderrStream = null;
+
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env: { ...process.env, ...(options.env || {}) },
+      shell: false,
+      stdio: [options.input !== undefined ? 'pipe' : 'ignore', 'pipe', 'pipe']
+    });
+    if (options.input !== undefined && child.stdin) { child.stdin.end(options.input); }
+
+    const finish = async (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { await stdoutStream?.end?.(); } catch {}
+      try { await stderrStream?.end?.(); } catch {}
+      resolve(result);
+    };
+
+    if (options.stdoutFile) {
+      fs.mkdirSync(path.dirname(options.stdoutFile), { recursive: true });
+      stdoutStream = fs.createWriteStream(options.stdoutFile, { flags: 'a' });
+    }
+    if (options.stderrFile) {
+      fs.mkdirSync(path.dirname(options.stderrFile), { recursive: true });
+      stderrStream = fs.createWriteStream(options.stderrFile, { flags: 'a' });
+    }
+
+    const timer = setTimeout(() => {
+      killedByTimeout = true;
+      try { child.kill('SIGTERM'); } catch {}
+      setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, 1500).unref?.();
+    }, timeoutMs);
+    timer.unref?.();
+
+    child.stdout.on('data', (d) => {
+      stdoutTail.push(d);
+      stdoutStream?.write(d);
+      options.onStdout?.(d.toString());
+    });
+    child.stderr.on('data', (d) => {
+      stderrTail.push(d);
+      stderrStream?.write(d);
+      options.onStderr?.(d.toString());
+    });
+    child.on('error', (err) => finish({
+      code: -1,
+      stdout: stdoutTail.text(),
+      stderr: `${stderrTail.text()}${err.message}`,
+      stdoutBytes: stdoutTail.totalBytes,
+      stderrBytes: stderrTail.totalBytes,
+      truncated: stdoutTail.truncated || stderrTail.truncated,
+      timedOut: killedByTimeout
+    }));
+    child.on('close', (code) => finish({
+      code: killedByTimeout ? 124 : code,
+      stdout: stdoutTail.text(),
+      stderr: stderrTail.text(),
+      stdoutBytes: stdoutTail.totalBytes,
+      stderrBytes: stderrTail.totalBytes,
+      truncated: stdoutTail.truncated || stderrTail.truncated,
+      timedOut: killedByTimeout
+    }));
+  });
+}
+
+export async function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+export function tmpdir(prefix = 'sks-') {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+export async function fileSize(p) {
+  try { return (await fsp.stat(p)).size; } catch { return 0; }
+}
+
+export async function dirSize(dir, opts = {}) {
+  let total = 0;
+  const files = await listFilesRecursive(dir, opts);
+  for (const f of files) total += await fileSize(f);
+  return total;
+}
+
+export function formatBytes(bytes) {
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let n = Number(bytes) || 0;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) { n /= 1024; i++; }
+  return `${n.toFixed(i ? 1 : 0)} ${units[i]}`;
+}
+
+export async function rmrf(p) {
+  await fsp.rm(p, { recursive: true, force: true });
+}

package/src/core/hooks-runtime.mjs

@@ -0,0 +1,110 @@
+import path from 'node:path';
+import { projectRoot, readJson, appendJsonl, readStdin, nowIso, exists } from './fsx.mjs';
+import { containsUserQuestion, looksInteractiveCommand, noQuestionContinuationReason, interactiveCommandReason } from './no-question-guard.mjs';
+import { stateFile, missionDir } from './mission.mjs';
+import { checkDbOperation, dbBlockReason } from './db-safety.mjs';
+
+async function loadHookPayload() {
+  const raw = await readStdin();
+  try { return raw.trim() ? JSON.parse(raw) : {}; } catch { return { raw }; }
+}
+
+async function loadState(root) {
+  return readJson(stateFile(root), {});
+}
+
+function isRalphRunning(state) {
+  return state.mode === 'RALPH' && state.phase === 'RALPH_RUNNING_NO_QUESTIONS';
+}
+
+function extractLastMessage(payload) {
+  return payload.last_assistant_message || payload.assistant_message || payload.message || payload.response || payload.raw || '';
+}
+
+function extractCommand(payload) {
+  return payload.command || payload.tool_input?.command || payload.input?.command || payload.tool?.input?.command || '';
+}
+
+export async function hookMain(name) {
+  const payload = await loadHookPayload();
+  const root = await projectRoot(payload.cwd || process.cwd());
+  const state = await loadState(root);
+  const ralph = isRalphRunning(state);
+  if (name === 'user-prompt-submit') return hookUserPrompt(root, state, payload, ralph);
+  if (name === 'pre-tool') return hookPreTool(root, state, payload, ralph);
+  if (name === 'post-tool') return hookPostTool(root, state, payload, ralph);
+  if (name === 'permission-request') return hookPermission(root, state, payload, ralph);
+  if (name === 'stop') return hookStop(root, state, payload, ralph);
+  return { continue: true };
+}
+
+async function hookUserPrompt(root, state, payload, ralph) {
+  if (!ralph) return { continue: true };
+  const id = state.mission_id;
+  if (id) await appendJsonl(path.join(missionDir(root, id), 'user_queue.jsonl'), { ts: nowIso(), payload });
+  return {
+    decision: 'block',
+    reason: 'Ralph is running in no-question/no-interruption mode. User prompt has been queued until Ralph completes.'
+  };
+}
+
+async function hookPreTool(root, state, payload, ralph) {
+  const dbDecision = await checkDbOperation(root, state, payload, { duringRalph: ralph });
+  if (dbDecision.action === 'block') {
+    return { decision: 'block', permissionDecision: 'deny', reason: dbBlockReason(dbDecision) };
+  }
+  const command = extractCommand(payload);
+  if (ralph && looksInteractiveCommand(command)) return { decision: 'block', reason: interactiveCommandReason(command) };
+  return { continue: true };
+}
+
+async function hookPostTool(root, state, payload, ralph) {
+  const dbDecision = await checkDbOperation(root, state, payload, { duringRalph: ralph });
+  if (dbDecision.action === 'block') {
+    return { decision: 'block', reason: dbBlockReason(dbDecision) };
+  }
+  if (!ralph) return { continue: true };
+  const failed = payload.exit_code && payload.exit_code !== 0;
+  if (failed) {
+    return {
+      additionalContext: 'Ralph no-question mode is active. Do not ask the user about this tool failure. Apply decision-contract.json fallback ladder, create a fix task, and continue.'
+    };
+  }
+  return { continue: true };
+}
+
+async function hookPermission(root, state, payload, ralph) {
+  const dbDecision = await checkDbOperation(root, state, payload, { duringRalph: ralph });
+  if (dbDecision.action === 'block') {
+    return { decision: 'deny', permissionDecision: 'deny', reason: dbBlockReason(dbDecision) };
+  }
+  if (!ralph) return { continue: true };
+  return {
+    decision: 'deny',
+    permissionDecision: 'deny',
+    reason: 'Ralph no-question mode forbids mid-loop approval prompts. Choose a non-approval safe alternative using decision-contract.json.'
+  };
+}
+
+async function hookStop(root, state, payload, ralph) {
+  if (!ralph) return { continue: true };
+  const id = state.mission_id;
+  const last = extractLastMessage(payload);
+  if (containsUserQuestion(last)) return { decision: 'block', reason: noQuestionContinuationReason() };
+  if (id) {
+    const gatePath = path.join(missionDir(root, id), 'done-gate.json');
+    if (await exists(gatePath)) {
+      const gate = await readJson(gatePath, {});
+      if (gate.passed === true) return { continue: true };
+    }
+  }
+  return {
+    decision: 'block',
+    reason: 'Ralph is not done. Continue autonomously. Run verifier, fix failing checks, sync wiki/visual artifacts if needed, and write done-gate.json. Do not ask the user.'
+  };
+}
+
+export async function emitHook(name) {
+  const result = await hookMain(name);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}

package/src/core/hproof.mjs

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import { exists, readJson, writeJsonAtomic, nowIso, fileSize } from './fsx.mjs';
+
+export async function evaluateDoneGate(root, missionId) {
+  const dir = path.join(root, '.sneakoscope', 'missions', missionId);
+  const gatePath = path.join(dir, 'done-gate.json');
+  const contractPath = path.join(dir, 'decision-contract.json');
+  const contractExists = await exists(contractPath);
+  const gate = await readJson(gatePath, {});
+  const reasons = [];
+  if (!contractExists) reasons.push('decision_contract_missing');
+  if (gate.unsupported_critical_claims && gate.unsupported_critical_claims > 0) reasons.push('unsupported_critical_claims_present');
+  if (gate.database_safety_violation === true || gate.db_safety_violation === true) reasons.push('database_safety_violation_present');
+  if (gate.database_destructive_operation_attempted === true) reasons.push('destructive_database_operation_attempted');
+  if (gate.visual_drift === 'high') reasons.push('visual_drift_high');
+  if (gate.wiki_drift === 'high') reasons.push('wiki_drift_high');
+  if (gate.tests_required === true && !gate.test_evidence_present) reasons.push('test_evidence_missing');
+  const dbSafetyLog = path.join(dir, 'db-safety.jsonl');
+  if ((await exists(dbSafetyLog)) && (await fileSize(dbSafetyLog)) > 0 && gate.database_safety_reviewed !== true) reasons.push('database_safety_log_requires_review');
+  const passed = gate.passed === true && reasons.length === 0;
+  const result = { checked_at: nowIso(), passed, reasons, gate };
+  await writeJsonAtomic(path.join(dir, 'done-gate.evaluated.json'), result);
+  return result;
+}
+
+export function defaultDoneGate() {
+  return {
+    passed: false,
+    unsupported_critical_claims: 0,
+    database_safety_violation: false,
+    database_destructive_operation_attempted: false,
+    database_safety_reviewed: true,
+    visual_drift: 'unknown',
+    wiki_drift: 'unknown',
+    tests_required: true,
+    test_evidence_present: false,
+    notes: []
+  };
+}

package/src/core/init.mjs

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { ensureDir, writeJsonAtomic, writeTextAtomic, mergeManagedBlock, nowIso, PACKAGE_VERSION, exists } from './fsx.mjs';
+import { DEFAULT_RETENTION_POLICY } from './retention.mjs';
+import { DEFAULT_DB_SAFETY_POLICY } from './db-safety.mjs';
+
+const AGENTS_BLOCK = `
+# Sneakoscope Codex Managed Rules
+
+This repository uses Sneakoscope Codex.
+
+## Ralph No-Question Rule
+
+Ralph may ask questions only during prepare. After decision-contract.json is sealed and Ralph run starts, the assistant must not ask the user questions, request confirmation, or present choices. Resolve using the decision ladder.
+
+## Performance and Retention
+
+Sneakoscope Codex keeps runtime state bounded. Do not write large raw logs into prompts. Store raw outputs in files, keep only tails/summaries in JSON, and allow sks gc to remove old arenas, temp files, and stale mission logs.
+
+## Source Priority
+
+1. Current code, tests, config
+2. decision-contract.json
+3. vgraph.json
+4. beta.json
+5. LLM Wiki
+6. visual parse
+7. model knowledge only if explicitly allowed
+
+## Database Safety
+
+Sneakoscope Codex treats database access as high risk. Destructive database operations are never allowed: DROP, TRUNCATE, mass DELETE/UPDATE, reset, push, repair, project deletion, branch reset/merge/delete, RLS disabling, broad grants/revokes, and any operation that could erase or overwrite data. Supabase/Postgres MCP should be read-only and project-scoped by default. Live database writes must not be performed through direct execute_sql; schema changes must be migration-file based and allowed only for local or preview/branch environments by the sealed contract.
+
+## Done Means
+
+A task is not done until relevant tests are run or justified, unsupported critical claims are zero, database safety violations are zero, visual/wiki drift is low or explicitly accepted, and final output includes evidence.
+`;
+
+export async function initProject(root, opts = {}) {
+  const created = [];
+  const sine = path.join(root, '.sneakoscope');
+  const dirs = [
+    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.agents/skills'
+  ];
+  for (const d of dirs) await ensureDir(path.join(root, d));
+
+  await writeJsonAtomic(path.join(sine, 'manifest.json'), {
+    package: 'sneakoscope',
+    version: PACKAGE_VERSION,
+    initialized_at: nowIso(),
+    no_external_tools: true,
+    codex_required: true,
+    native_runtime_dependencies: 0,
+    database_safety: 'destructive_db_operations_denied_always'
+  });
+  created.push('.sneakoscope/manifest.json');
+
+  const dbSafetyPath = path.join(sine, 'db-safety.json');
+  if (!(await exists(dbSafetyPath)) || opts.force) {
+    await writeJsonAtomic(dbSafetyPath, DEFAULT_DB_SAFETY_POLICY);
+    created.push('.sneakoscope/db-safety.json');
+  }
+
+  const policyPath = path.join(sine, 'policy.json');
+  if (!(await exists(policyPath)) || opts.force) {
+    await writeJsonAtomic(policyPath, {
+      schema_version: 1,
+      retention: DEFAULT_RETENTION_POLICY,
+      database_safety: DEFAULT_DB_SAFETY_POLICY,
+      performance: {
+        max_parallel_sessions: 2,
+        process_tail_bytes: 262144,
+        codex_timeout_ms: 1800000,
+        prefer_streaming_logs: true
+      },
+      package: {
+        zero_runtime_dependencies: true,
+        rust_default_runtime: false,
+        rust_reason: 'Native Rust binaries would increase package size and break npm install portability. Optional Rust source is provided for future acceleration, but default runtime is dependency-free Node.js.'
+      },
+      database: {
+        guardian_enabled: true,
+        live_database_mode: 'read_only',
+        destructive_operations_allowed: false,
+        mcp_write_tools_allowed: false
+      }
+    });
+    created.push('.sneakoscope/policy.json');
+  }
+
+  const currentState = path.join(sine, 'state', 'current.json');
+  if (!(await exists(currentState)) || opts.force) {
+    await writeJsonAtomic(currentState, { mode: 'IDLE', phase: 'IDLE', updated_at: nowIso() });
+    created.push('.sneakoscope/state/current.json');
+  }
+
+  await mergeManagedBlock(path.join(root, 'AGENTS.md'), 'Sneakoscope Codex GX MANAGED BLOCK', AGENTS_BLOCK);
+  created.push('AGENTS.md managed block');
+
+  await writeTextAtomic(path.join(root, '.codex', 'config.toml'), `[features]\ncodex_hooks = true\n\n[profiles.sks-ralph]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "high"\n\n[profiles.sks-default]\nmodel = "gpt-5.5"\napproval_policy = "on-request"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "medium"\n`);
+  created.push('.codex/config.toml');
+
+  await writeJsonAtomic(path.join(root, '.codex', 'hooks.json'), {
+    hooks: {
+      UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'sks hook user-prompt-submit' }] }],
+      PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: 'sks hook pre-tool' }] }],
+      PostToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: 'sks hook post-tool' }] }],
+      PermissionRequest: [{ matcher: '*', hooks: [{ type: 'command', command: 'sks hook permission-request' }] }],
+      Stop: [{ hooks: [{ type: 'command', command: 'sks hook stop' }] }]
+    }
+  });
+  created.push('.codex/hooks.json');
+
+  await installSkills(root);
+  created.push('.agents/skills/*');
+  return { created };
+}
+
+async function installSkills(root) {
+  const skills = {
+    'ralph-supervisor': `---\nname: ralph-supervisor\ndescription: Run the Ralph no-question loop after a decision contract is sealed.\n---\n\nYou are the Ralph Supervisor.\n\nRules:\n- Never ask the user during Ralph run.\n- Use decision-contract.json and the decision ladder.\n- Continue until done-gate.json passes or safe scope is completed with explicit limitation.\n- Keep outputs bounded. Write raw logs to files and summarize only tails.\n- Database destructive operations are never allowed.\n- Write progress to .sneakoscope mission files.\n`,
+    'ralph-resolver': `---\nname: ralph-resolver\ndescription: Resolve newly discovered ambiguity during Ralph using the sealed decision ladder, without asking the user.\n---\n\nResolve ambiguity in this order: seed contract, explicit answers, approved defaults, AGENTS.md, current code/tests, smallest reversible change, defer optional scope. Never ask the user. If database risk is involved, prefer read-only, no-op, local-only migration file, or safe limitation; never run destructive SQL.\n`,
+    'hproof-claim-ledger': `---\nname: hproof-claim-ledger\ndescription: Extract atomic claims and classify support status.\n---\n\nEvery factual statement must become an atomic claim. Unsupported critical claims cannot be used for implementation or final answer. Database claims require DB safety evidence.\n`,
+    'hproof-evidence-bind': `---\nname: hproof-evidence-bind\ndescription: Bind claims to code, tests, decision contract, vgraph, beta, wiki, or visual parse evidence.\n---\n\nEvidence priority: current code/tests, decision-contract.json, vgraph.json, beta.json, wiki, visual parse, user prompt. Database claims must respect .sneakoscope/db-safety.json.\n`,
+    'db-safety-guard': `---\nname: db-safety-guard\ndescription: Enforce Sneakoscope Codex database safety before using SQL, Supabase MCP, Postgres, Prisma, Drizzle, Knex, or migration commands.\n---\n\nRules:\n- Never run DROP, TRUNCATE, mass DELETE/UPDATE, db reset, db push, project deletion, branch reset/merge/delete, or RLS-disabling operations.\n- Supabase MCP must be read-only and project-scoped by default.\n- Live writes through execute_sql are blocked; use migration files and only local/preview branches if explicitly allowed.\n- Production writes are forbidden.\n- If unsure, read-only only.\n`,
+    'gx-visual-generate': `---\nname: gx-visual-generate\ndescription: Generate a visual sheet using GPT Image 2 from vgraph.json and beta.json.\n---\n\nUse built-in GPT Image 2 / $imagegen only. Do not use external diagram tools. vgraph.json is source of truth.\n`,
+    'gx-visual-read': `---\nname: gx-visual-read\ndescription: Read a Sneakoscope Codex visual sheet and produce parse.json.\n---\n\nExtract nodes, edges, invariants, tests, risks, and uncertainties. Do not infer hidden nodes.\n`,
+    'gx-visual-validate': `---\nname: gx-visual-validate\ndescription: Validate visual parse against vgraph.json and beta.json.\n---\n\nIf critical nodes, edges, or invariants are missing, mark validation failed.\n`,
+    'turbo-context-pack': `---\nname: turbo-context-pack\ndescription: Build ultra-low-token context packet with Q4 bits, Q3 tags, top-K claims, and minimal evidence.\n---\n\nDefault to Q4/Q3 only. Add Q2 or Q1 only when needed for support or verification.\n`
+  };
+  for (const [name, content] of Object.entries(skills)) {
+    const dir = path.join(root, '.agents', 'skills', name);
+    await ensureDir(dir);
+    await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
+  }
+}

package/src/core/mission.mjs

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { ensureDir, nowIso, randomId, writeJsonAtomic, appendJsonl, readJson, exists } from './fsx.mjs';
+
+export function missionId() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  return `M-${stamp}-${randomId(4)}`;
+}
+
+export function sineDir(root) { return path.join(root, '.sneakoscope'); }
+export function missionsDir(root) { return path.join(sineDir(root), 'missions'); }
+export function missionDir(root, id) { return path.join(missionsDir(root), id); }
+export function stateFile(root) { return path.join(sineDir(root), 'state', 'current.json'); }
+
+export async function createMission(root, { mode, prompt }) {
+  const id = missionId();
+  const dir = missionDir(root, id);
+  await ensureDir(dir);
+  await ensureDir(path.join(dir, 'bus'));
+  await ensureDir(path.join(dir, 'ralph'));
+  await ensureDir(path.join(dir, 'sessions'));
+  const mission = {
+    id,
+    mode,
+    prompt,
+    created_at: nowIso(),
+    phase: mode === 'ralph' ? 'RALPH_PREPARE' : 'PREPARE',
+    questions_allowed: true,
+    implementation_allowed: false
+  };
+  await writeJsonAtomic(path.join(dir, 'mission.json'), mission);
+  await appendJsonl(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'mission.created', mission: id, mode, prompt });
+  await writeJsonAtomic(stateFile(root), { mission_id: id, mode: mode.toUpperCase(), phase: mission.phase, updated_at: nowIso() });
+  return { id, dir, mission };
+}
+
+export async function loadMission(root, id) {
+  const dir = missionDir(root, id);
+  const mission = await readJson(path.join(dir, 'mission.json'));
+  return { id, dir, mission };
+}
+
+export async function findLatestMission(root) {
+  const dir = missionsDir(root);
+  if (!(await exists(dir))) return null;
+  const fs = await import('node:fs/promises');
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const ids = entries.filter((e) => e.isDirectory() && e.name.startsWith('M-')).map((e) => e.name).sort();
+  return ids.at(-1) || null;
+}
+
+export async function setCurrent(root, patch) {
+  const current = await readJson(stateFile(root), {});
+  await writeJsonAtomic(stateFile(root), { ...current, ...patch, updated_at: nowIso() });
+}