sneakoscope 5.5.2 → 5.6.0

package/dist/core/naruto/normalize-worker-prompt-text.js

@@ -0,0 +1,12 @@
+export const WORKER_PROMPT_TEXT_MAX_CHARS = 32000;
+export function normalizeWorkerPromptText(value) {
+    const normalized = String(value || '').replace(/[^\S\n]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+    const truncated = normalized.length > WORKER_PROMPT_TEXT_MAX_CHARS;
+    const text = truncated ? normalized.slice(0, WORKER_PROMPT_TEXT_MAX_CHARS) : normalized;
+    return {
+        text,
+        truncated,
+        dropped_chars: truncated ? normalized.length - WORKER_PROMPT_TEXT_MAX_CHARS : 0
+    };
+}
+//# sourceMappingURL=normalize-worker-prompt-text.js.map

package/dist/core/routes.js

@@ -643,7 +643,9 @@ export const COMMAND_CATALOG = [
     { name: 'gx', usage: 'sks gx init|render|validate|drift|snapshot [name]', description: 'Create and verify deterministic SVG/HTML visual context cartridges.' },
     { name: 'profile', usage: 'sks profile show|set <model>', description: 'Inspect or set the current SKS model profile metadata.' },
     { name: 'gc', usage: 'sks gc [--dry-run] [--json]', description: 'Compact oversized logs and prune stale runtime artifacts.' },
-    { name: 'stats', usage: 'sks stats [--json]', description: 'Show package and .sneakoscope storage size.' }
+    { name: 'stats', usage: 'sks stats [--json]', description: 'Show package and .sneakoscope storage size.' },
+    { name: 'mcp-server', usage: 'sks mcp-server [--expose-exec] [--probe]', description: 'Run a stdio MCP server exposing SKS read-only commands as tools for any MCP-capable agent host; --expose-exec also exposes non-read-only commands; --probe round-trips initialize/tools-list and exits.' },
+    { name: 'agent-bridge', usage: 'sks agent-bridge setup [--json]', description: 'Publish the agent-bridge manifest, print host registration snippets (generic MCP host, Codex CLI, non-interactive contract), and run a live non-interactive smoke test.' }
 ];
 export function routeById(id) {
     const key = String(id || '').replace(/^\$/, '').toLowerCase();

package/dist/core/triwiki/code-index-scanner.js

@@ -0,0 +1,313 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { collectInputFiles } from './triwiki-cache-key.js';
+export const CODE_INDEX_SCHEMA = 'sks.code-index.v1';
+const DEFAULT_MAX_LINES_PER_FILE = 120;
+const DEFAULT_MAX_FILES = 4000;
+const CODE_EXT_RE = /\.(js|ts|tsx|jsx|cjs|mjs)$/;
+const ENTRY_FILE_RE = /^(index|mod)\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const EXPORT_LINE_RE = /^\s*export\s+(?:default\s+)?(?:const|let|var|function|class|interface|type|enum|abstract\s+class|async\s+function)\s+[A-Za-z0-9_$]+/;
+const EXPORT_BRACE_RE = /^\s*export\s*\{/;
+const EXPORT_STAR_RE = /^\s*export\s*\*/;
+const IMPORT_SPEC_RE = /(?:from\s+|require\()\s*['"](\.\.?\/[^'"]+)['"]/g;
+// High fan-in or a large file surface both correlate with change blast-radius; simple counts avoid needing a real dependency graph.
+const RISK_HIGH_FAN_IN = 5;
+const RISK_HIGH_FILE_COUNT = 40;
+const RISK_MEDIUM_FAN_IN = 2;
+const RISK_MEDIUM_FILE_COUNT = 15;
+export async function scanCodebaseIndex(root, opts = {}) {
+    const resolvedRoot = path.resolve(root);
+    const maxLinesPerFile = opts.maxLinesPerFile ?? DEFAULT_MAX_LINES_PER_FILE;
+    const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES;
+    const inventory = listSourceFiles(resolvedRoot);
+    const truncatedByCap = inventory.length > maxFiles;
+    const scannedFiles = truncatedByCap ? inventory.slice(0, maxFiles) : inventory;
+    const boundaries = inferModuleBoundaries(resolvedRoot);
+    const fileRecords = readFileRecords(resolvedRoot, scannedFiles, maxLinesPerFile);
+    const modulesByPath = assignFilesToModules(boundaries, fileRecords);
+    const moduleIdForFile = buildFileToModuleIdIndex(modulesByPath);
+    const cards = buildModuleCards(resolvedRoot, modulesByPath, moduleIdForFile);
+    return {
+        schema: CODE_INDEX_SCHEMA,
+        generated_at: new Date().toISOString(),
+        root: resolvedRoot,
+        modules: cards,
+        truncated: truncatedByCap,
+        scanned_file_count: scannedFiles.length,
+        scanned_files_cap: maxFiles
+    };
+}
+function listSourceFiles(root) {
+    const gitFiles = tryGitLsFiles(root);
+    const all = gitFiles !== null ? gitFiles : walkFallback(root);
+    return all.filter((rel) => CODE_EXT_RE.test(rel)).sort();
+}
+function tryGitLsFiles(root) {
+    try {
+        const result = spawnSync('git', ['ls-files'], { cwd: root, encoding: 'utf8' });
+        if (result.status !== 0 || result.error)
+            return null;
+        return String(result.stdout || '').split('\n').map((line) => line.trim()).filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+}
+function walkFallback(root) {
+    const collected = collectInputFiles(root, ['.']);
+    return collected.records.map((record) => record.path);
+}
+function inferModuleBoundaries(root) {
+    const boundaries = [];
+    const seen = new Set();
+    const addBoundary = (dir) => {
+        const normalized = dir.replace(/\\/g, '/').replace(/\/+$/, '');
+        if (!normalized || seen.has(normalized))
+            return;
+        seen.add(normalized);
+        boundaries.push({ module_id: moduleIdFromDir(normalized), dir: normalized });
+    };
+    for (const sourceRoot of listDirs(root, '.').filter((name) => name === 'src' || name === 'source' || name === 'lib')) {
+        for (const topLevel of listDirs(root, sourceRoot)) {
+            addBoundary(topLevel);
+            for (const nested of listDirs(root, topLevel))
+                addBoundary(nested);
+        }
+    }
+    const workspaces = readWorkspaceGlobs(root);
+    for (const glob of workspaces) {
+        for (const dir of resolveWorkspaceGlob(root, glob))
+            addBoundary(dir);
+    }
+    return boundaries.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+function listDirs(root, rel) {
+    const absolute = rel === '.' ? root : path.join(root, rel);
+    let entries;
+    try {
+        entries = fs.readdirSync(absolute, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingOrInaccessible(error))
+            return [];
+        throw error;
+    }
+    return entries
+        .filter((entry) => entry.isDirectory() && !isExcludedDirName(entry.name))
+        .map((entry) => (rel === '.' ? entry.name : `${rel}/${entry.name}`))
+        .sort();
+}
+function isExcludedDirName(name) {
+    return name === '.git' || name === 'node_modules' || name === 'dist' || name === 'build' || name === 'coverage' || name === '__tests__' || name.startsWith('.');
+}
+function isMissingOrInaccessible(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'EACCES' || code === 'ENOTDIR' || code === 'EPERM' || code === 'EISDIR';
+}
+function readWorkspaceGlobs(root) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (!pkg.workspaces)
+            return [];
+        if (Array.isArray(pkg.workspaces))
+            return pkg.workspaces;
+        return pkg.workspaces.packages || [];
+    }
+    catch {
+        return [];
+    }
+}
+function resolveWorkspaceGlob(root, glob) {
+    const normalized = glob.replace(/\\/g, '/');
+    if (!normalized.includes('*')) {
+        return fs.existsSync(path.join(root, normalized)) ? [normalized.replace(/\/+$/, '')] : [];
+    }
+    const starIndex = normalized.indexOf('*');
+    const prefix = normalized.slice(0, starIndex).replace(/\/+$/, '');
+    return listDirs(root, prefix || '.');
+}
+function moduleIdFromDir(dir) {
+    return dir.replace(/^src\//, '').replace(/\//g, '-') || 'root';
+}
+function readFileRecords(root, files, maxLinesPerFile) {
+    const out = [];
+    for (const rel of files) {
+        const absolute = path.join(root, rel);
+        let text = '';
+        try {
+            text = fs.readFileSync(absolute, 'utf8');
+        }
+        catch (error) {
+            if (isMissingOrInaccessible(error))
+                continue;
+            throw error;
+        }
+        const lines = text.split(/\r?\n/);
+        const loc = lines.length && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
+        const scanLines = lines.slice(0, maxLinesPerFile);
+        const exportLines = [];
+        for (const line of scanLines) {
+            if (EXPORT_LINE_RE.test(line) || EXPORT_BRACE_RE.test(line) || EXPORT_STAR_RE.test(line)) {
+                exportLines.push(line.trim());
+            }
+        }
+        const importSpecifiers = [];
+        for (const line of scanLines) {
+            IMPORT_SPEC_RE.lastIndex = 0;
+            let match;
+            while ((match = IMPORT_SPEC_RE.exec(line))) {
+                if (match[1])
+                    importSpecifiers.push(match[1]);
+            }
+        }
+        out.push({ rel, loc, exportLines, importSpecifiers });
+    }
+    return out;
+}
+function assignFilesToModules(boundaries, files) {
+    const sortedBoundaries = [...boundaries].sort((a, b) => b.dir.length - a.dir.length);
+    const map = new Map();
+    for (const boundary of boundaries)
+        map.set(boundary.module_id, { boundary, files: [] });
+    for (const file of files) {
+        const owner = sortedBoundaries.find((boundary) => file.rel === boundary.dir || file.rel.startsWith(`${boundary.dir}/`));
+        if (!owner)
+            continue;
+        map.get(owner.module_id).files.push(file);
+    }
+    for (const [moduleId, entry] of map) {
+        if (!entry.files.length)
+            map.delete(moduleId);
+    }
+    return map;
+}
+function buildFileToModuleIdIndex(modulesByPath) {
+    const index = new Map();
+    for (const [moduleId, entry] of modulesByPath) {
+        for (const file of entry.files)
+            index.set(file.rel, moduleId);
+    }
+    return index;
+}
+function buildModuleCards(root, modulesByPath, moduleIdForFile) {
+    const fanIn = new Map();
+    const dependencyEdgesByModule = new Map();
+    for (const [moduleId, entry] of modulesByPath) {
+        const edges = new Set();
+        for (const file of entry.files) {
+            for (const specifier of file.importSpecifiers) {
+                const resolvedRel = resolveRelativeImport(root, file.rel, specifier);
+                if (!resolvedRel)
+                    continue;
+                const targetModuleId = moduleIdForFile.get(resolvedRel);
+                if (!targetModuleId || targetModuleId === moduleId)
+                    continue;
+                edges.add(targetModuleId);
+            }
+        }
+        dependencyEdgesByModule.set(moduleId, edges);
+        for (const target of edges)
+            fanIn.set(target, (fanIn.get(target) || 0) + 1);
+    }
+    const cards = [];
+    for (const [moduleId, entry] of modulesByPath) {
+        const files = entry.files;
+        const loc = files.reduce((sum, file) => sum + file.loc, 0);
+        const exportsSummary = files.flatMap((file) => file.exportLines);
+        const dependencyEdges = [...(dependencyEdgesByModule.get(moduleId) || [])].sort();
+        const entryPoints = collectEntryPoints(root, entry.boundary.dir, files);
+        const fanInCount = fanIn.get(moduleId) || 0;
+        const risk = computeRisk(fanInCount, files.length);
+        cards.push({
+            module_id: moduleId,
+            paths: [entry.boundary.dir],
+            entry_points: entryPoints,
+            exports_summary: exportsSummary,
+            dependency_edges: dependencyEdges,
+            file_count: files.length,
+            loc,
+            risk
+        });
+    }
+    return cards.sort((a, b) => a.module_id.localeCompare(b.module_id));
+}
+function computeRisk(fanIn, fileCount) {
+    if (fanIn >= RISK_HIGH_FAN_IN || fileCount >= RISK_HIGH_FILE_COUNT)
+        return 'high';
+    if (fanIn >= RISK_MEDIUM_FAN_IN || fileCount >= RISK_MEDIUM_FILE_COUNT)
+        return 'medium';
+    return 'low';
+}
+function collectEntryPoints(root, dir, files) {
+    const entryPoints = new Set();
+    const pkgPath = path.join(root, dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            if (typeof pkg.main === 'string')
+                entryPoints.add(normalizeEntryPath(dir, pkg.main));
+            if (typeof pkg.bin === 'string')
+                entryPoints.add(normalizeEntryPath(dir, pkg.bin));
+            else if (pkg.bin && typeof pkg.bin === 'object') {
+                for (const value of Object.values(pkg.bin))
+                    if (typeof value === 'string')
+                        entryPoints.add(normalizeEntryPath(dir, value));
+            }
+            for (const value of collectExportsPaths(pkg.exports))
+                entryPoints.add(normalizeEntryPath(dir, value));
+        }
+        catch {
+            // malformed package.json at a module boundary is not this scanner's concern; skip entry-point inference for it
+        }
+    }
+    for (const file of files) {
+        const base = path.basename(file.rel);
+        if (ENTRY_FILE_RE.test(base))
+            entryPoints.add(file.rel);
+    }
+    return [...entryPoints].sort();
+}
+function collectExportsPaths(exportsField) {
+    if (typeof exportsField === 'string')
+        return [exportsField];
+    if (!exportsField || typeof exportsField !== 'object')
+        return [];
+    const out = [];
+    for (const value of Object.values(exportsField)) {
+        if (typeof value === 'string')
+            out.push(value);
+        else
+            out.push(...collectExportsPaths(value));
+    }
+    return out;
+}
+function normalizeEntryPath(dir, entry) {
+    const cleaned = entry.replace(/^\.\//, '');
+    return `${dir}/${cleaned}`.replace(/\\/g, '/');
+}
+function resolveRelativeImport(root, fromRel, specifier) {
+    const fromDir = path.posix.dirname(fromRel);
+    const joined = path.posix.normalize(path.posix.join(fromDir, specifier));
+    const candidates = [
+        `${joined}.ts`,
+        `${joined}.tsx`,
+        `${joined}.js`,
+        `${joined}.jsx`,
+        `${joined}/index.ts`,
+        `${joined}/index.tsx`,
+        `${joined}/index.js`,
+        `${joined}/index.jsx`,
+        joined
+    ];
+    for (const candidate of candidates) {
+        const absolute = path.join(root, candidate);
+        if (!fs.existsSync(absolute))
+            continue;
+        // only resolve to a real file — a bare directory match (no extension) can't be looked up in the file->module index
+        if (fs.statSync(absolute).isFile())
+            return candidate;
+    }
+    return null;
+}
+//# sourceMappingURL=code-index-scanner.js.map

package/dist/core/triwiki/code-pack.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ensureDir, exists, nowIso, readJson, sha256, writeJsonAtomic } from '../fsx.js';
+export const CODE_PACK_SCHEMA = 'sks.code-pack.v1';
+export const DEFAULT_CODE_PACK_TOKEN_BUDGET = 8000;
+export function codePackDir(root) {
+    return path.join(root, '.sneakoscope', 'wiki');
+}
+export function codePackPath(root) {
+    return path.join(codePackDir(root), 'code-pack.json');
+}
+export function codePackPrevPath(root) {
+    return path.join(codePackDir(root), 'code-pack.prev.json');
+}
+export function buildCodePack(root, index, tokenBudget = DEFAULT_CODE_PACK_TOKEN_BUDGET) {
+    const entries = [];
+    for (const card of index.modules) {
+        const entry = buildEntryForModule(card);
+        if (!entry)
+            continue;
+        entries.push(entry);
+    }
+    const totalTokenCost = entries.reduce((sum, entry) => sum + entry.token_cost, 0);
+    return {
+        schema: CODE_PACK_SCHEMA,
+        generated_at: nowIso(),
+        git_head_sha: readGitHeadSha(root),
+        source_file_count: index.scanned_file_count,
+        index_digest: computeIndexDigest(index),
+        entries,
+        token_budget: tokenBudget,
+        total_token_cost: totalTokenCost
+    };
+}
+function buildEntryForModule(card) {
+    const citations = collectCitations(card);
+    // openwiki principle: an entry with no real repository citation is worse than no entry at all
+    if (!citations.length)
+        return null;
+    const text = summarizeModule(card);
+    return {
+        id: `code:${card.module_id}`,
+        text,
+        citations,
+        trust_score: computeTrustScore(card),
+        freshness: 'unknown',
+        token_cost: Math.ceil(text.length / 4)
+    };
+}
+function collectCitations(card) {
+    const paths = [...card.paths, ...card.entry_points].filter(Boolean);
+    const seen = new Set();
+    const citations = [];
+    for (const p of paths) {
+        if (seen.has(p))
+            continue;
+        seen.add(p);
+        citations.push({ path: p });
+    }
+    return citations;
+}
+function summarizeModule(card) {
+    const role = inferRole(card);
+    const primaryPath = card.paths[0] || card.module_id;
+    const exportsPart = summarizeExports(card.exports_summary);
+    const depsPart = summarizeDependencies(card.dependency_edges);
+    const sizePart = `${card.file_count} file${card.file_count === 1 ? '' : 's'}, ${card.loc} loc, ${card.risk} risk`;
+    return `${card.module_id} is ${role} at ${primaryPath} (${sizePart}). ${exportsPart} ${depsPart}`.trim().replace(/\s+/g, ' ');
+}
+function inferRole(card) {
+    const idLower = card.module_id.toLowerCase();
+    const pathLower = card.paths.join(' ').toLowerCase();
+    if (idLower.includes('test') || pathLower.includes('__tests__'))
+        return 'a test module';
+    if (idLower.includes('cli') || pathLower.includes('cli'))
+        return 'a CLI module';
+    if (idLower.includes('command'))
+        return 'a command module';
+    if (idLower.includes('core'))
+        return 'a core module';
+    return 'a module';
+}
+function summarizeExports(exportsSummary) {
+    if (!exportsSummary.length)
+        return 'It has no detected top-level exports.';
+    const preview = exportsSummary.slice(0, 5).map((line) => line.replace(/^export\s+/, '').replace(/\s*\{\s*$/, '').trim());
+    const suffix = exportsSummary.length > preview.length ? `, and ${exportsSummary.length - preview.length} more` : '';
+    return `Key exports: ${preview.join('; ')}${suffix}.`;
+}
+function summarizeDependencies(dependencyEdges) {
+    if (!dependencyEdges.length)
+        return 'It has no detected cross-module dependencies.';
+    const preview = dependencyEdges.slice(0, 5);
+    const suffix = dependencyEdges.length > preview.length ? `, and ${dependencyEdges.length - preview.length} more` : '';
+    return `Depends on: ${preview.join(', ')}${suffix}.`;
+}
+function computeTrustScore(card) {
+    // more citable surface (entry points, real exports) correlates with a more reliably summarizable module
+    let score = 0.5;
+    if (card.entry_points.length > 0)
+        score += 0.2;
+    if (card.exports_summary.length > 0)
+        score += 0.2;
+    if (card.risk === 'high')
+        score -= 0.15;
+    else if (card.risk === 'low')
+        score += 0.1;
+    return Math.max(0, Math.min(1, Number(score.toFixed(2))));
+}
+function readGitHeadSha(root) {
+    try {
+        const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' });
+        if (result.status !== 0 || result.error)
+            return null;
+        const sha = String(result.stdout || '').trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+function computeIndexDigest(index) {
+    const stable = index.modules
+        .map((card) => ({ module_id: card.module_id, paths: [...card.paths].sort() }))
+        .sort((a, b) => a.module_id.localeCompare(b.module_id));
+    return sha256(JSON.stringify(stable));
+}
+export async function validateCodePack(pack, root) {
+    const issues = [];
+    const seenIds = new Set();
+    for (const entry of pack.entries) {
+        if (seenIds.has(entry.id)) {
+            issues.push(`duplicate entry id: ${entry.id}`);
+        }
+        else {
+            seenIds.add(entry.id);
+        }
+        if (!entry.citations.length) {
+            issues.push(`entry ${entry.id} has no citations`);
+            continue;
+        }
+        for (const citation of entry.citations) {
+            const absolute = path.join(root, citation.path);
+            if (!fs.existsSync(absolute)) {
+                issues.push(`entry ${entry.id} citation path does not exist: ${citation.path}`);
+            }
+        }
+    }
+    const totalTokenCost = pack.entries.reduce((sum, entry) => sum + entry.token_cost, 0);
+    if (totalTokenCost > pack.token_budget) {
+        issues.push(`total_token_cost ${totalTokenCost} exceeds token_budget ${pack.token_budget}`);
+    }
+    return { ok: issues.length === 0, issues };
+}
+export async function writeCodePackAtomic(root, pack) {
+    const targetPath = codePackPath(root);
+    const prevPath = codePackPrevPath(root);
+    await ensureDir(codePackDir(root));
+    let prevWritten = null;
+    if (await exists(targetPath)) {
+        const previous = await readJson(targetPath);
+        await writeJsonAtomic(prevPath, previous);
+        prevWritten = prevPath;
+    }
+    await writeJsonAtomic(targetPath, pack);
+    return { ok: true, path: targetPath, prev_path: prevWritten };
+}
+//# sourceMappingURL=code-pack.js.map

package/dist/core/triwiki/triwiki-cache-key.js

@@ -125,7 +125,15 @@ function listFiles(root, start) {
     const out = [];
     if (!fs.existsSync(start))
         return out;
-    const stat = fs.lstatSync(start);
+    let stat;
+    try {
+        stat = fs.lstatSync(start);
+    }
+    catch (error) {
+        if (isMissingOrInaccessible(error))
+            return out;
+        throw error;
+    }
     if (stat.isSymbolicLink() || stat.isFile())
         return [relativeUnix(root, start)];
     if (!stat.isDirectory())
@@ -138,7 +146,17 @@ function listFiles(root, start) {
         const relDir = relativeUnix(root, dir);
         if (relDir && isExcluded(relDir))
             continue;
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            // dir can vanish or become unreadable between stack push and pop (TOCTOU) — contribute zero files, not a crash
+            if (isMissingOrInaccessible(error))
+                continue;
+            throw error;
+        }
+        for (const entry of entries) {
             const absolute = path.join(dir, entry.name);
             const rel = relativeUnix(root, absolute);
             if (isExcluded(rel))
@@ -151,6 +169,10 @@ function listFiles(root, start) {
     }
     return out.sort();
 }
+function isMissingOrInaccessible(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'EACCES' || code === 'ENOTDIR' || code === 'EPERM';
+}
 function isExcluded(rel) {
     for (const dir of DEFAULT_EXCLUDED_DIRS) {
         if (rel === dir || rel.startsWith(`${dir}/`))

package/dist/core/triwiki-attention.js

@@ -224,7 +224,33 @@ function uniqueAttentionRows(rows = [], max = 4) {
     }
     return out;
 }
-export function buildTriWikiAttention({ selected = [], wiki = {}, role = 'worker', maxUse = 4, maxHydrate = 4 } = {}) {
+/** Ranks code-pack entries (LLM-consumable, source-cited codebase summaries — see
+ * src/core/triwiki/code-pack.ts) by trust_score into a dedicated attention sub-budget,
+ * independent of the policy-claim RGBA/geometric selection above: code entries carry
+ * no meaningful mission-coordinate proximity, so competing them against policy claims
+ * for the same fixed slot budget would make their appearance arbitrary. Each surviving
+ * entry becomes a use_first row (bare id, no fabricated RGBA) plus a hydrate_first row
+ * pointing at its source citations, so a consumer knows which real files back it. */
+function codePackAttentionRows(codePackEntries = [], tokenBudget = 2000) {
+    const sorted = [...(codePackEntries || [])]
+        .filter((entry) => entry && typeof entry.id === 'string')
+        .sort((a, b) => Number(b.trust_score || 0) - Number(a.trust_score || 0));
+    const useFirst = [];
+    const hydrateFirst = [];
+    let tokens = 0;
+    for (const entry of sorted) {
+        const cost = Number(entry.token_cost) || Math.max(1, Math.ceil(String(entry.text || '').length / 4));
+        if (tokens + cost > tokenBudget)
+            continue;
+        tokens += cost;
+        useFirst.push([entry.id, null, null]);
+        const citationPaths = Array.isArray(entry.citations) ? entry.citations.map((c) => c?.path).filter(Boolean) : [];
+        if (citationPaths.length)
+            hydrateFirst.push([entry.id, `code_citations:${citationPaths.join(',')}`]);
+    }
+    return { useFirst, hydrateFirst };
+}
+export function buildTriWikiAttention({ selected = [], wiki = {}, role = 'worker', maxUse = 4, maxHydrate = 4, codePackEntries = [], codePackTokenBudget = 2000 } = {}) {
     const anchors = attentionAnchorMap(wiki);
     const ranked = [...(selected || [])]
         .map((claim, index) => ({ claim, index }))
@@ -250,10 +276,11 @@ export function buildTriWikiAttention({ selected = [], wiki = {}, role = 'worker
         ...voxelRows,
         ...selectedHydrateRows
     ], maxHydrate);
+    const codeRows = codePackAttentionRows(codePackEntries, codePackTokenBudget);
     return {
         mode: 'aggressive_triwiki_active_recall',
-        use_first: useFirst,
-        hydrate_first: hydrateFirst
+        use_first: uniqueAttentionRows([...useFirst, ...codeRows.useFirst], maxUse + codeRows.useFirst.length),
+        hydrate_first: uniqueAttentionRows([...hydrateFirst, ...codeRows.hydrateFirst], maxHydrate + codeRows.hydrateFirst.length)
     };
 }
 export function selectClaims(mission, claims, budget = {}) {
@@ -282,7 +309,7 @@ export function geometricOffsets(max = 65536) {
         out.push(x);
     return out;
 }
-export function contextCapsule({ mission, role = 'worker', contractHash = null, claims = [], q4 = {}, q3 = [], budget = {} }) {
+export function contextCapsule({ mission, role = 'worker', contractHash = null, claims = [], q4 = {}, q3 = [], budget = {}, codePackEntries = [] }) {
     const trustPolicy = budget.trustPolicy || DEFAULT_TRUST_POLICY;
     const claimsWithTrust = (claims || []).map((claim) => withTrust(claim, trustPolicy));
     const selected = selectClaims(mission, claims, { maxClaims: budget.maxClaims ?? (role.includes('verifier') ? 16 : 9), trustPolicy });
@@ -313,7 +340,9 @@ export function contextCapsule({ mission, role = 'worker', contractHash = null,
             wiki,
             role,
             maxUse: budget.maxAttentionUse ?? (role.includes('verifier') ? 7 : 4),
-            maxHydrate: budget.maxAttentionHydrate ?? (role.includes('verifier') ? 7 : 4)
+            maxHydrate: budget.maxAttentionHydrate ?? (role.includes('verifier') ? 7 : 4),
+            codePackEntries,
+            codePackTokenBudget: budget.codePackTokenBudget ?? 2000
         }),
         claims: selected.map((c) => {
             const anchor = anchorsById.get(c.id);