nexakit 0.0.0-stage → 0.2.0

package/src/legacy-repair.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { acquireLock } from './install-lock.js';
+import { recordEntries } from './install-registry.js';
+import { relinkIfUnchanged } from './link-states.js';
+import { actualRoot, ensureStableInstall, nexakitDir } from './stable-install.js';
+import { TOOLKIT_ROOT, packageVersion, registrationCommand, resolveNodeExecutable, setupToolkit } from './toolkit-setup.js';
+
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+const exists = file => fs.access(file).then(() => true, () => false);
+
+// Finds the global links that point into a root that no longer exists, `from`, and that nexakit cannot prove
+// are its own (no entry in the install registry). Only skill names this version ships are considered.
+// Nothing is written here: the person has to confirm what this lists.
+export async function planLegacyRepair({
+  from, agent = 'all', homeDirectory = os.homedir(), toolkitRoot = TOOLKIT_ROOT, environment = process.env, codexHome
+} = {}) {
+  const dead = path.resolve(from);
+  const setup = await setupToolkit({ agent, homeDirectory, toolkitRoot, environment, ...(codexHome && { codexHome }) });
+  const links = setup.skills
+    .filter(skill => skill.state === 'roto-ajeno' && skill.root && samePath(skill.root, dead))
+    .map(({ client, name, target, literal }) => ({ client, name, target, literal }))
+    .sort((a, b) => a.client.localeCompare(b.client) || a.name.localeCompare(b.name));
+  const mcp = {};
+  for (const [client, state] of Object.entries(setup.mcp.states)) {
+    if (state.state === 'roto-ajeno' && state.root && samePath(state.root, dead)) mcp[client] = { name: state.name, literal: state.literal };
+  }
+  return { from: dead, agent, activeRoot: setup.activeRoot, ephemeral: setup.ephemeral && !setup.otherCopy, links, mcp };
+}
+
+// Repoints the links of the plan to the copy of nexakit in use and records them as nexakit's own.
+// Each link is read again right before writing: one that changed since the plan is left alone.
+export async function applyLegacyRepair(plan, {
+  homeDirectory = os.homedir(), toolkitRoot = TOOLKIT_ROOT, environment = process.env, runNpm, packageSpec, lockOptions,
+  acquire = acquireLock
+} = {}) {
+  const home = await fs.realpath(homeDirectory);
+  const lock = await acquire(nexakitDir(home), lockOptions);
+  try {
+    if (plan.ephemeral && plan.links.length) {
+      await ensureStableInstall({
+        homeDirectory: home, version: await packageVersion(await fs.realpath(toolkitRoot)), lock,
+        ...(runNpm && { runNpm }), ...(packageSpec && { packageSpec })
+      });
+    }
+    const entries = [], skipped = [];
+    let changed = 0;
+    for (const link of plan.links) {
+      const source = path.join(plan.activeRoot, 'skills', link.name);
+      if (!(await exists(path.join(source, 'SKILL.md')))) { skipped.push(link.name); continue; }
+      await lock.assertHeld();
+      if (await relinkIfUnchanged({ target: link.target, expectedLiteral: link.literal, source }) === 'cambio') { changed++; continue; }
+      entries.push({ destino: link.target, apunta: await fs.readlink(link.target), raiz: plan.activeRoot });
+    }
+    await recordEntries(nexakitDir(home), entries, lock);
+
+    // The MCP entry is not rewritten here: its client owns that file, so only the exact commands are given.
+    const mcpCommands = [];
+    const script = path.join(plan.activeRoot, 'bin/agent-toolkit-mcp.js');
+    if (Object.keys(plan.mcp ?? {}).length && await exists(script)) {
+      const nodePath = await resolveNodeExecutable(environment);
+      for (const [client, current] of Object.entries(plan.mcp)) {
+        mcpCommands.push(registrationCommand(client, { state: 'roto-ajeno', name: current.name }, nodePath, script));
+      }
+    }
+    return { repaired: entries.length, changed, skipped, mcpCommands, stableRoot: actualRoot(home) };
+  } finally {
+    await lock.release();
+  }
+}

package/src/level-agents.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { agentModels } from "./agent-models.js";
+
+// Codex has no plugins, so its level agents are files. Claude's come from the `niveles` plugin.
+// The top level is "alto"; xhigh is asked per spawn, only after high failed.
+const LEVELS = [["Ligero", "ligero"], ["Normal", "normal"], ["Exigente", "exigente"], ["Alto", "alto"]];
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/u;
+
+export class LevelAgentsError extends Error {
+  constructor(message) { super(message); this.code = "level-agents"; }
+}
+
+function content(slug, level, { model, effort }) {
+  const task = `nivel ${level} (${model}, ${effort})`;
+  return [`# Generado por \`agent-toolkit-inbox agentes\`. Ese comando nunca sobrescribe ni borra: lo anterior queda como .anterior-*.`,
+    `name = ${JSON.stringify(`nivel_${slug}`)}`,
+    `description = ${JSON.stringify(`Ejecuta una tarea delegada de ${task}. Úsalo solo cuando la skill revision-cruzada indique este nivel.`)}`,
+    `model = ${JSON.stringify(model)}`, `model_reasoning_effort = ${JSON.stringify(effort)}`,
+    `developer_instructions = """`,
+    `Ejecutas una tarea que te delega la sesión principal de la revisión cruzada, con el ${task}.`,
+    "Haz solo lo que pide la delegación y respeta las reglas del proyecto (AGENTS.md y sus skills).",
+    "Si la tarea es de código: cambio mínimo, pruebas que lo cubran, y ejecútalas junto con el lint o la compilación que correspondan.",
+    "No hagas commit, push ni PR, y no envíes, apruebes ni reclames encargos de revisión.",
+    "Termina con los cambios por archivo, las comprobaciones ejecutadas con su resultado real y lo que no comprobaste.",
+    `"""`, ""].join("\n");
+}
+
+async function current(file) {
+  try {
+    const stat = await fs.lstat(file);
+    // A link or a directory is never read through or replaced silently: it counts as different.
+    return stat.isFile() ? await fs.readFile(file, "utf8") : false;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+// Plans the Codex level agents from the live catalog; writes nothing.
+export async function levelAgentPlan({ codexHome = process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex") } = {}) {
+  const { codex, levels } = await agentModels({ codexHome });
+  const files = [];
+  for (const [level, slug] of LEVELS) {
+    const target = path.join(codexHome, "agents", `nivel_${slug}.toml`);
+    const pick = levels.find(entry => entry.level === level)?.codex;
+    const base = { level: slug, name: `nivel_${slug}`, path: target, model: pick?.model ?? null, effort: pick?.effort ?? null };
+    if (!codex.available) { files.push({ ...base, state: "sin-catalogo" }); continue; }
+    if (!pick || !MODEL.test(pick.model)) { files.push({ ...base, state: "sin-modelo" }); continue; }
+    const wanted = content(slug, level, pick);
+    const existing = await current(target);
+    files.push({ ...base, content: wanted, state: existing === null ? "nuevo" : existing === wanted ? "igual" : "distinto" });
+  }
+  return { catalog: codex.available, files };
+}
+
+async function directory(dir) {
+  await fs.mkdir(dir, { recursive: true });
+  const stat = await fs.lstat(dir);
+  if (!stat.isDirectory()) throw new LevelAgentsError(`${dir} debe ser un directorio y no un enlace; no se escribió nada en él.`);
+}
+
+// Publishing with link() fails instead of replacing whatever appeared at the target.
+async function publish(file) {
+  const temporary = path.join(path.dirname(file.path), `.nivel-${randomUUID()}.tmp`);
+  try {
+    await fs.writeFile(temporary, file.content, { flag: "wx", mode: 0o644 });
+    await fs.link(temporary, file.path);
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") return false;
+    throw error;
+  } finally { await fs.unlink(temporary).catch(() => {}); }
+}
+
+// Never overwrites or deletes: a different file is kept under a unique `.anterior-*` name, and only with `force`.
+export async function writeLevelAgents(plan, { force = false } = {}) {
+  for (const file of plan.files) {
+    if (file.state !== "nuevo" && !(force && file.state === "distinto")) continue;
+    await directory(path.dirname(file.path));
+    if (file.state === "distinto") {
+      file.anterior = `${file.path}.anterior-${new Date().toISOString().replace(/\D/gu, "").slice(0, 14)}-${randomUUID().slice(0, 8)}`;
+      try { await fs.rename(file.path, file.anterior); }
+      catch (error) { if (error.code !== "ENOENT") throw error; file.anterior = null; }
+    }
+    if (await publish(file)) file.state = file.state === "nuevo" ? "escrito" : "actualizado";
+    else file.state = "distinto";
+  }
+  return plan;
+}
+
+const LABEL = { nuevo: "se crea", escrito: "creado", igual: "sin cambios", distinto: "ya existe y es distinto: no se toca",
+  actualizado: "actualizado", "sin-modelo": "sin modelo de esa categoría", "sin-catalogo": "catálogo no disponible" };
+
+export function levelAgentsTable({ catalog, files }) {
+  const lines = ["**Agentes por nivel de Codex**", "", "| Nivel | Nombre | Modelo | Esfuerzo | Estado |", "| --- | --- | --- | --- | --- |"];
+  for (const file of files) {
+    lines.push(`| ${file.level} | \`${file.name}\` | ${file.model ? `\`${file.model}\`` : "—"} | ${file.effort ? `\`${file.effort}\`` : "—"} | ${LABEL[file.state]} |`);
+  }
+  lines.push("");
+  if (!catalog) lines.push("No se pudo leer el catálogo de Codex (`models_cache.json`); no se escribe nada hasta que se lea bien.");
+  const pending = files.filter(file => file.state === "nuevo").length, different = files.filter(file => file.state === "distinto").length;
+  if (pending) lines.push(`Vista previa: no se escribió nada. Ejecuta \`agent-toolkit-inbox agentes --escribir\` para crear ${pending}.`);
+  if (different) lines.push(`Hay ${different} ${different === 1 ? "archivo" : "archivos"} con otro contenido que no se ${different === 1 ? "toca" : "tocan"}. Con \`--escribir --forzar\` se actualizan y el anterior queda como \`.anterior-*\` junto al archivo.`);
+  for (const file of files.filter(item => item.anterior)) lines.push(`Anterior conservado: \`${file.anterior}\`.`);
+  if (!pending && !different && catalog) lines.push("Los agentes están al día.");
+  lines.push("");
+  return lines.join("\n");
+}

package/src/link-states.js

@@ -0,0 +1,172 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { IS_WINDOWS } from './platform.js';
+
+// Evaluated in this order; the first one that holds wins.
+export const LINK_STATES = Object.freeze(['falta', 'conflicto', 'efimero', 'instalado', 'otra-copia', 'roto-propio', 'roto-ajeno', 'quitada']);
+// What an apply acts on, and what counts as ready.
+export const ACTIONABLE_LINK_STATES = Object.freeze(['falta', 'efimero', 'roto-propio']);
+export const READY_LINK_STATES = Object.freeze(['instalado', 'otra-copia']);
+// `quitada`: nexakit instaló el enlace y el usuario lo quitó. No es pendiente: se respeta hasta que pida `--reponer`.
+export const REMOVED_BY_USER_STATE = 'quitada';
+export const SETTLED_LINK_STATES = Object.freeze([...READY_LINK_STATES, REMOVED_BY_USER_STATE]);
+
+const PACKAGE_NAMES = new Set(['nexakit', 'agent-toolkit']);
+const MAX_PACKAGE_BYTES = 1_048_576;
+const BROKEN_CODES = new Set(['ENOENT', 'ENOTDIR', 'ELOOP']);
+
+const normalized = value => (IS_WINDOWS ? value.toLowerCase() : value);
+const samePath = (a, b) => normalized(a) === normalized(b);
+const lstatOrNull = file => fs.lstat(file).catch(error => {
+  if (error.code === 'ENOENT') return null;
+  throw error;
+});
+
+export const isEphemeralPath = value => path.resolve(value).split(path.sep).includes('_npx');
+
+// A copy of nexakit inside an npx cache: `…/_npx/<hash>/node_modules/nexakit` (or the old name, agent-toolkit).
+// Anything else under `_npx` belongs to another package and is never treated as nexakit's.
+export function isEphemeralNexakitRoot(root) {
+  const parts = path.resolve(root).split(path.sep);
+  const n = parts.length;
+  return n >= 4 && parts[n - 4] === '_npx' && parts[n - 2] === 'node_modules' && PACKAGE_NAMES.has(parts[n - 1]);
+}
+
+export async function readLink(target) {
+  const info = await lstatOrNull(target);
+  if (!info) return { exists: false, isLink: false };
+  if (!info.isSymbolicLink()) return { exists: true, isLink: false };
+  const literal = await fs.readlink(target);
+  return { exists: true, isLink: true, literal, absolute: path.resolve(path.dirname(target), literal) };
+}
+
+// Strips `suffix` from the end of `value`; null when it does not end with it.
+function rootFrom(value, suffix) {
+  const tail = path.normalize(suffix);
+  const resolved = path.resolve(value);
+  if (!normalized(resolved).endsWith(normalized(path.sep + tail))) return null;
+  return resolved.slice(0, resolved.length - tail.length - 1) || null;
+}
+
+export async function recognizedRoot(resolvedPath, suffix) {
+  const root = rootFrom(resolvedPath, suffix);
+  if (!root) return null;
+  const file = path.join(root, 'package.json');
+  const info = await lstatOrNull(file);
+  if (!info?.isFile() || info.isSymbolicLink() || info.size > MAX_PACKAGE_BYTES) return null;
+  try {
+    const pkg = JSON.parse(await fs.readFile(file, 'utf8'));
+    return PACKAGE_NAMES.has(pkg?.name) ? root : null;
+  } catch { return null; }
+}
+
+async function realpathOrNull(file) {
+  try { return await fs.realpath(file); } catch (error) {
+    if (BROKEN_CODES.has(error.code)) return null;
+    throw error;
+  }
+}
+
+export async function classifyLink({ target, suffix, activeRoots = [], isOwned = () => false }) {
+  const link = await readLink(target);
+  if (!link.exists) return { target, suffix, state: 'falta' };
+  if (!link.isLink) return { target, suffix, state: 'conflicto' };
+  return classifyReference({ target, literal: link.literal, absolute: link.absolute, suffix, activeRoots, isOwned });
+}
+
+// Classifies a path that points into a copy of nexakit without being a link itself, such as the script
+// an MCP entry runs. `target` identifies the reference for `isOwned`; `absolute` defaults to the literal.
+export async function classifyReference({ target, literal, absolute = path.resolve(literal), suffix, activeRoots = [], isOwned = () => false }) {
+  const base = { target, suffix };
+  const resolved = await realpathOrNull(absolute);
+
+  // Before `instalado`, so a link into the cache this run came from is never taken as good. It must point at
+  // exactly `<copy of nexakit in an npx cache>/<suffix>`; another package there is not nexakit's to move.
+  const ephemeralRoot = [absolute, resolved].filter(Boolean)
+    .map(candidate => rootFrom(candidate, suffix)).find(root => root && isEphemeralNexakitRoot(root));
+  if (ephemeralRoot) return { ...base, state: 'efimero', literal, root: ephemeralRoot };
+
+  if (resolved) {
+    const tail = path.normalize(suffix);
+    for (const candidate of activeRoots) {
+      if (isEphemeralPath(candidate)) continue;
+      const real = await realpathOrNull(candidate);
+      if (real && samePath(resolved, path.join(real, tail))) return { ...base, state: 'instalado', literal, root: real };
+    }
+    const other = await recognizedRoot(resolved, suffix);
+    if (other) return { ...base, state: 'otra-copia', literal, root: other };
+    return { ...base, state: 'conflicto', literal };
+  }
+
+  const owned = await isOwned(target, literal);
+  return { ...base, state: owned ? 'roto-propio' : 'roto-ajeno', literal, root: rootFrom(absolute, suffix) ?? undefined };
+}
+
+export function chooseActiveRoot(items, fallbackRoot) {
+  const counts = new Map();
+  for (const item of items) {
+    if (item.state !== 'otra-copia' || !item.root || isEphemeralPath(item.root)) continue;
+    counts.set(item.root, (counts.get(item.root) ?? 0) + 1);
+  }
+  let best = null;
+  for (const [root, count] of counts) {
+    if (count * 2 > items.length && (!best || count > best.count)) best = { root, count };
+  }
+  return best?.root ?? fallbackRoot;
+}
+
+export function legacyGroups(items, { skillNames, mcpDeadRoot } = {}) {
+  const groups = new Map();
+  for (const item of items) {
+    if (item.state !== 'roto-ajeno' || !item.root || !skillNames?.has(path.basename(item.target))) continue;
+    groups.set(item.root, [...(groups.get(item.root) ?? []), item.target]);
+  }
+  return [...groups]
+    .filter(([root, targets]) => targets.length >= 3 || (mcpDeadRoot !== undefined && root === mcpDeadRoot))
+    .map(([root, targets]) => ({ root, targets }));
+}
+
+// `expectedLiteral` is the readlink value the plan saw; null means the path must not exist yet.
+// Re-reads right before writing and touches nothing when the link is no longer what the plan saw.
+// `relative` writes the link relative to its own folder (Windows junctions are always absolute).
+export async function relinkIfUnchanged({ target, expectedLiteral, source, relative = false }) {
+  const type = IS_WINDOWS ? 'junction' : 'dir';
+  const absoluteSource = path.resolve(source);
+  const linkValue = relative && !IS_WINDOWS ? path.relative(path.dirname(target), absoluteSource) : absoluteSource;
+  const info = await lstatOrNull(target);
+
+  if (expectedLiteral === null) {
+    if (info) return 'cambio';
+    try { await fs.symlink(linkValue, target, type); } catch (error) {
+      if (error.code === 'EEXIST') return 'cambio';
+      throw error;
+    }
+    return 'hecho';
+  }
+
+  if (!info?.isSymbolicLink() || await fs.readlink(target) !== expectedLiteral) return 'cambio';
+
+  if (IS_WINDOWS) {
+    // A junction cannot be renamed over; this window is not atomic there.
+    await fs.unlink(target);
+    await fs.symlink(linkValue, target, type);
+    return 'hecho';
+  }
+
+  // Build the new link beside the old one and rename over it, so the name is never missing.
+  const temporary = `${target}.nx-${crypto.randomUUID()}`;
+  await fs.symlink(linkValue, temporary, type);
+  try {
+    if (await fs.readlink(target) !== expectedLiteral) {
+      await fs.unlink(temporary);
+      return 'cambio';
+    }
+    await fs.rename(temporary, target);
+  } catch (error) {
+    await fs.unlink(temporary).catch(() => {});
+    if (error.code === 'ENOENT' || error.code === 'EINVAL') return 'cambio';
+    throw error;
+  }
+  return 'hecho';
+}

package/src/memory-connection-artifacts.js

@@ -0,0 +1,192 @@
+import { resolvePackageLock } from './package-lock-path.js';
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+import {
+  createMemoryConnectionDescriptor, copyMemoryConnectionData, freezeMemoryConnectionData,
+  memoryConnectionHash, MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION
+} from "./memory-connection-descriptor.js";
+
+const MIB = 1048576;
+export const MEMORY_CONNECTION_ARTIFACT_LIMITS = Object.freeze({
+  nodeBytes: 256 * MIB, smallBytes: MIB / 2, lockBytes: 2 * MIB,
+  totalBytes: 260 * MIB, chunkBytes: 65536,
+  pathChars: 4096, components: 64, reportBytes: 131072
+});
+export const MEMORY_CONNECTION_ARTIFACT_OPEN_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+const HASH_KEYS = ["nodeSha256", "binSha256", "manifestSha256", "packageJsonSha256", "packageLockSha256"];
+class Rejected extends Error {
+  constructor(code, state = "blocked") { super(code); this.code = code; this.state = state; }
+}
+const reject = (code, state) => { throw new Rejected(code, state); };
+const errno = (e) => e instanceof Error && typeof e.code === "string" ? e.code : "";
+const within = (root, full) => full === root || full.startsWith(root + "/");
+const fileSignature = (s) => JSON.stringify([s.dev, s.ino, s.uid, s.gid, s.mode, s.nlink, s.size, s.mtimeMs, s.ctimeMs]);
+const dirSignature = (s) => JSON.stringify([s.dev, s.ino, s.uid, s.gid, s.mode]);
+const inode = (s) => JSON.stringify([s.dev, s.ino]);
+
+function inputData(input) {
+  try {
+    const data = copyMemoryConnectionData(input);
+    if (!data || Array.isArray(data) || Object.keys(data).length !== 2 ||
+        !Object.hasOwn(data, "descriptor") || !Object.hasOwn(data, "expectedHashes")) reject("MC_ARTIFACT_INPUT", "invalid");
+    const descriptor = createMemoryConnectionDescriptor(data.descriptor?.identity);
+    if (memoryConnectionHash(data.descriptor) !== memoryConnectionHash(descriptor)) reject("MC_ARTIFACT_INPUT", "invalid");
+    const hashes = data.expectedHashes;
+    if (!hashes || Array.isArray(hashes) || Object.keys(hashes).length !== HASH_KEYS.length ||
+        !HASH_KEYS.every(key => Object.hasOwn(hashes, key) && typeof hashes[key] === "string" && /^[a-f0-9]{64}$/.test(hashes[key]))) {
+      reject("MC_ARTIFACT_INPUT", "invalid");
+    }
+    const { toolkitRoot, vaultPath, manifestPath, nodePath } = descriptor.identity;
+    if (within(toolkitRoot, vaultPath) || within(vaultPath, toolkitRoot) ||
+        !manifestPath.startsWith(vaultPath + "/")) reject("MC_ARTIFACT_INPUT", "invalid");
+    const entries = [
+      { key: "nodeSha256", full: nodePath, kind: "node", limit: MEMORY_CONNECTION_ARTIFACT_LIMITS.nodeBytes },
+      { key: "binSha256", full: descriptor.server.args[0], kind: "code", limit: MEMORY_CONNECTION_ARTIFACT_LIMITS.smallBytes },
+      { key: "manifestSha256", full: manifestPath, kind: "manifest", limit: MEMORY_CONNECTION_ARTIFACT_LIMITS.smallBytes },
+      { key: "packageJsonSha256", full: toolkitRoot + "/package.json", kind: "code", limit: MEMORY_CONNECTION_ARTIFACT_LIMITS.smallBytes },
+      { key: "packageLockSha256", full: toolkitRoot + "/package-lock.json", kind: "code", limit: MEMORY_CONNECTION_ARTIFACT_LIMITS.lockBytes }
+    ];
+    for (const entry of entries) {
+      if (entry.full.length > MEMORY_CONNECTION_ARTIFACT_LIMITS.pathChars ||
+          entry.full.split("/").length - 1 > MEMORY_CONNECTION_ARTIFACT_LIMITS.components ||
+          entries.some(other => other !== entry && within(entry.full, other.full))) reject("MC_ARTIFACT_INPUT", "invalid");
+    }
+    return { descriptor, hashes, entries, roots: [toolkitRoot, vaultPath] };
+  } catch { reject("MC_ARTIFACT_INPUT", "invalid"); }
+}
+function safeDir(s, uid, owned) {
+  if (!s.isDirectory() || s.isSymbolicLink() || !(s.mode & 0o100)) reject("MC_ARTIFACT_PARENT_UNSAFE");
+  if (owned) {
+    if (s.uid !== uid || s.mode & 0o7022) reject("MC_ARTIFACT_PARENT_UNSAFE");
+  } else {
+    const sharedSticky = s.uid === 0 && (s.mode & 0o7777) === 0o1777;
+    if (![0, uid].includes(s.uid) || !sharedSticky && s.mode & 0o7022) reject("MC_ARTIFACT_PARENT_UNSAFE");
+  }
+}
+function safeFile(s, entry, uid) {
+  if (!s.isFile() || s.isSymbolicLink() || s.nlink !== 1) reject("MC_ARTIFACT_FILE_UNSAFE");
+  const mode = s.mode & 0o7777;
+  if (entry.kind === "node") {
+    if (![0, uid].includes(s.uid) || (mode & 0o500) !== 0o500 || mode & 0o7022) reject("MC_ARTIFACT_FILE_UNSAFE");
+  } else if (s.uid !== uid || (entry.kind === "manifest" ? mode !== 0o600 : ![0o600, 0o644].includes(mode))) {
+    reject("MC_ARTIFACT_FILE_UNSAFE");
+  }
+  if (!Number.isSafeInteger(s.size) || s.size < 0 || s.size > entry.limit) reject("MC_ARTIFACT_FILE_LIMIT");
+}
+async function snapshot(io, entry, roots, uid) {
+  const parents = []; let current = "/";
+  const root = await io.lstat(current); safeDir(root, uid, false);
+  parents.push({ path: current, signature: dirSignature(root), inode: inode(root) });
+  const parts = entry.full.slice(1).split("/");
+  for (const part of parts.slice(0, -1)) {
+    current = path.posix.join(current, part); const s = await io.lstat(current);
+    safeDir(s, uid, roots.some(owned => within(owned, current)));
+    parents.push({ path: current, signature: dirSignature(s), inode: inode(s) });
+  }
+  const stat = await io.lstat(entry.full); safeFile(stat, entry, uid);
+  return { entry, parents, stat };
+}
+async function recheck(io, item, roots, uid) {
+  for (const parent of item.parents) {
+    let s; try { s = await io.lstat(parent.path); } catch { reject("MC_ARTIFACT_CHANGED"); }
+    safeDir(s, uid, roots.some(owned => within(owned, parent.path)));
+    if (dirSignature(s) !== parent.signature) reject("MC_ARTIFACT_CHANGED");
+  }
+  let named;
+  try { named = await io.lstat(item.entry.full); } catch { reject("MC_ARTIFACT_CHANGED"); }
+  safeFile(named, item.entry, uid);
+  if (fileSignature(named) !== fileSignature(item.stat)) reject("MC_ARTIFACT_CHANGED");
+}
+async function recheckAll(io, items, roots, uid) {
+  for (const item of items) await recheck(io, item, roots, uid);
+}
+function rejectAliases(items, roots) {
+  const files = items.map(item => inode(item.stat));
+  if (new Set(files).size !== files.length) reject("MC_ARTIFACT_ALIAS");
+  const directories = roots.map(root => items.flatMap(item => item.parents).find(p => p.path === root)?.inode);
+  if (directories.some(value => value === undefined) || new Set(directories).size !== directories.length) reject("MC_ARTIFACT_ALIAS");
+}
+
+/**
+ * Verify five explicit byte pins, NOT executable semantics, active runtime,
+ * manifest/schema validity or installed dependency/import closure. No discovery,
+ * candidate execution/import, node_modules enumeration, install or write.
+ * Trusted IO doubles are simulations, never native local-read attestations.
+ * Rechecks are cooperative observations, not atomic openat or ABA isolation.
+ */
+export async function inspectMemoryConnectionArtifacts(input, dependencies = {}) {
+  let data = null, nativeIO = false;
+  const budget = { read: 0 };
+  const report = (state, details = {}) => {
+    const matched = state === "matched";
+    const result = {
+      schemaVersion: MEMORY_CONNECTION_VERSION, state, hashes: null,
+      metadataSha256: null, bytesRead: budget.read, reasons: [], ...details,
+      facts: {
+        ...MEMORY_CONNECTION_FACTS, verificationScope: "base-artifacts-only",
+        evidence: matched ? nativeIO ? "local-artifact-files" : "simulated-local-artifacts" : "none",
+        artifactPathsVerified: matched && nativeIO, localReadVerified: matched && nativeIO,
+        bytePinsMatched: matched, installedDependenciesVerified: false,
+        manifestSemanticsVerified: false, runtimeVersionVerified: false,
+        runtimeCompatibilityVerified: false, inspectedCandidatesExecuted: false
+      }
+    };
+    if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_CONNECTION_ARTIFACT_LIMITS.reportBytes) reject("MC_ARTIFACT_REPORT_LIMIT");
+    return freezeMemoryConnectionData(result);
+  };
+  try {
+    data = inputData(input);
+    nativeIO = dependencies.io === undefined;
+    const io = dependencies.io ?? fs, uid = process.getuid?.();
+    if (!["darwin", "linux"].includes(process.platform) || !Number.isSafeInteger(uid) || constants.O_NOFOLLOW === undefined) reject("MC_ARTIFACT_PLATFORM");
+    data.entries.find(entry => entry.key === 'packageLockSha256').full = await resolvePackageLock(data.descriptor.identity.toolkitRoot, io);
+    const items = [];
+    for (const entry of data.entries) items.push(await snapshot(io, entry, data.roots, uid));
+    rejectAliases(items, data.roots);
+    if (items.reduce((sum, item) => sum + item.stat.size, 0) > MEMORY_CONNECTION_ARTIFACT_LIMITS.totalBytes) reject("MC_ARTIFACT_TOTAL_LIMIT");
+    await recheckAll(io, items, data.roots, uid);
+    // One reusable small buffer, not an allocation of a Node binary's size.
+    const chunk = Buffer.alloc(MEMORY_CONNECTION_ARTIFACT_LIMITS.chunkBytes), hashes = {};
+    for (const item of items) {
+      await recheckAll(io, items, data.roots, uid);
+      let handle;
+      try { handle = await io.open(item.entry.full, MEMORY_CONNECTION_ARTIFACT_OPEN_FLAGS); }
+      catch (e) { reject(errno(e) === "ELOOP" ? "MC_ARTIFACT_FILE_UNSAFE" : "MC_ARTIFACT_UNREADABLE"); }
+      const hash = createHash("sha256");
+      try {
+        const opened = await handle.stat(); safeFile(opened, item.entry, uid);
+        if (fileSignature(opened) !== fileSignature(item.stat)) reject("MC_ARTIFACT_CHANGED");
+        await recheck(io, item, data.roots, uid);
+        let offset = 0;
+        while (offset < item.stat.size) {
+          const request = Math.min(chunk.length, item.stat.size - offset, MEMORY_CONNECTION_ARTIFACT_LIMITS.totalBytes - budget.read);
+          if (request <= 0) reject("MC_ARTIFACT_TOTAL_LIMIT");
+          const { bytesRead } = await handle.read(chunk, 0, request, offset);
+          if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > request) reject("MC_ARTIFACT_READ");
+          budget.read += bytesRead; // Retained even if metadata/pin/hash later fails.
+          if (!bytesRead) reject("MC_ARTIFACT_CHANGED");
+          offset += bytesRead; hash.update(chunk.subarray(0, bytesRead));
+        }
+        const after = await handle.stat(); safeFile(after, item.entry, uid);
+        if (fileSignature(after) !== fileSignature(item.stat)) reject("MC_ARTIFACT_CHANGED");
+        await recheck(io, item, data.roots, uid);
+      } finally {
+        try { await handle.close(); } catch { reject("MC_ARTIFACT_CLOSE"); }
+      }
+      await recheck(io, item, data.roots, uid);
+      const value = hash.digest("hex");
+      if (value !== data.hashes[item.entry.key]) reject("MC_ARTIFACT_PIN_MISMATCH");
+      hashes[item.entry.key] = value;
+    }
+    await recheckAll(io, items, data.roots, uid);
+    const metadataSha256 = createHash("sha256").update(JSON.stringify(items.map(item => ({
+      role: item.entry.key, path: item.entry.full, parents: item.parents, signature: fileSignature(item.stat)
+    })))).digest("hex");
+    return report("matched", { hashes, metadataSha256, reasons: ["MC_ARTIFACT_MATCH"] });
+  } catch (e) {
+    return report(e instanceof Rejected ? e.state : "blocked", { reasons: [e instanceof Rejected ? e.code : "MC_ARTIFACT_IO"] });
+  }
+}