blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/src/lib/autonomy-store.js

@@ -0,0 +1,202 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { buildCatalog } from "./catalog.js";
+import { isFileLockContention, replaceFileWithRetry } from "./filesystem-retry.js";
+import { projectStateDir } from "./paths.js";
+
+export const AUTONOMY_SCHEMA = "agentspine.autonomy-portfolio/v1";
+export const AUTONOMY_MODES = Object.freeze(["observe", "advise", "execute", "publish"]);
+export const AUTONOMY_ACTIONS = Object.freeze(["observe", "advise", "execute", "publish"]);
+export const EVIDENCE_CLASSES = Object.freeze(["objective", "user-feedback", "model-suggestion"]);
+export const AUTONOMY_CONFIRMATION = "local-owner-confirmed";
+export const PUBLISH_CONFIRMATION = "local-owner-publish-confirmed";
+export const ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+export const DIGEST_RE = /^[a-f0-9]{64}$/;
+export const CAPABILITY_RE = /^tool:[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+const MAX_STATE_BYTES = 5 * 1024 * 1024;
+const SECRET_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|gh[opusu])_[A-Za-z0-9_-]{20,}|\bBearer\s+[A-Za-z0-9._~+/-]{20,}|\b(?:api[-_ ]?key|token|password|secret)\s*[:=]\s*\S{8,}/i;
+
+export function digest(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+export function stableId(value, field, nullable = false) {
+  if ((value === null || value === undefined || value === "") && nullable) return null;
+  if (typeof value !== "string" || !ID_RE.test(value)) throw new Error(`${field} must be a stable whitespace-free ID`);
+  return value;
+}
+
+export function safeText(value, field, maximum, nullable = false) {
+  if ((value === null || value === undefined || value === "") && nullable) return null;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${field} is required`);
+  const result = value.trim();
+  if (result.length > maximum) throw new Error(`${field} exceeds ${maximum} characters`);
+  if (SECRET_RE.test(result)) throw new Error(`${field} appears to contain a secret`);
+  return result;
+}
+
+export function timestamp(value, field = "date", nullable = false) {
+  if ((value === null || value === undefined || value === "") && nullable) return null;
+  const parsed = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(parsed.getTime())) throw new Error(`${field} must be a valid date`);
+  return parsed.toISOString();
+}
+
+export function exactCapabilities(value = []) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !CAPABILITY_RE.test(item) || item.includes("*"))) {
+    throw new Error("capabilities must be exact tool:<name> values without wildcards");
+  }
+  return [...new Set(value)].sort();
+}
+
+export function modeAllows(mode, action) {
+  return AUTONOMY_MODES.indexOf(mode) >= AUTONOMY_ACTIONS.indexOf(action);
+}
+
+export function emptyAutonomy(root) {
+  return { schema: AUTONOMY_SCHEMA, root, revision: 0, projects: [], snapshots: [], observations: [], notices: [], history: [] };
+}
+
+function validSource(source) {
+  return source && ["local-root", "public-repository"].includes(source.kind)
+    && typeof source.value === "string" && source.value.length > 0
+    && (source.kind !== "local-root" || isAbsolute(source.value));
+}
+
+function validProject(item) {
+  return item && ID_RE.test(item.id || "") && ID_RE.test(item.projectId || "")
+    && ID_RE.test(item.tenantId || "") && (item.groupId === null || ID_RE.test(item.groupId || ""))
+    && AUTONOMY_MODES.includes(item.mode) && validSource(item.source)
+    && Array.isArray(item.capabilities) && JSON.stringify(item.capabilities) === JSON.stringify([...new Set(item.capabilities)].sort())
+    && item.capabilities.every((value) => CAPABILITY_RE.test(value) && !value.includes("*"))
+    && typeof item.active === "boolean" && Number.isInteger(item.revision) && item.revision > 0
+    && item.authority === "explicit-local-autonomy-policy" && item.sourceAuthority === "explicit-local-owner-policy"
+    && typeof item.goal === "string" && typeof item.updatedAt === "string"
+    && (item.publishConfirmedAt === null || typeof item.publishConfirmedAt === "string");
+}
+
+function ownDigest(item) {
+  const { recordDigest, ...body } = item;
+  return recordDigest === digest(body);
+}
+
+export function autonomyFindings(state) {
+  const findings = [];
+  if (!state || state.schema !== AUTONOMY_SCHEMA || typeof state.root !== "string" || !Number.isInteger(state.revision)
+    || state.revision < 0 || !["projects", "snapshots", "observations", "notices", "history"].every((key) => Array.isArray(state[key]))) {
+    return ["invalid-autonomy-state"];
+  }
+  if (new Set(state.projects.map((item) => item.id)).size !== state.projects.length) findings.push("duplicate-project-registration");
+  for (const item of state.projects) if (!validProject(item) || !ownDigest(item)) findings.push(`invalid-project:${item?.id || "unknown"}`);
+  for (const [key, limit] of [["snapshots", 256], ["observations", 1024], ["notices", 512], ["history", 2048]]) {
+    if (state[key].length > limit) findings.push(`${key}-limit-exceeded`);
+    if (new Set(state[key].map((item) => item.id)).size !== state[key].length) findings.push(`duplicate-${key}-id`);
+    for (const item of state[key]) if (!item || !ID_RE.test(item.id || "") || !ownDigest(item)) findings.push(`invalid-${key}:${item?.id || "unknown"}`);
+  }
+  return findings;
+}
+
+export function normalizeAutonomy(value, root) {
+  if (value?.root !== root) throw new Error("autonomy state root mismatch");
+  const findings = autonomyFindings(value);
+  if (findings.length) throw new Error(`autonomy state failed closed: ${findings.join(", ")}`);
+  return value;
+}
+
+export async function autonomyPaths(root = process.cwd(), providedCatalog = null) {
+  const catalog = providedCatalog || await buildCatalog(root);
+  const directory = await projectStateDir(catalog.root);
+  return { catalog, autonomyPath: join(directory, "autonomy-portfolio.json") };
+}
+
+export async function loadAutonomy(root = process.cwd(), providedCatalog = null) {
+  const paths = await autonomyPaths(root, providedCatalog);
+  try {
+    const metadata = await stat(paths.autonomyPath);
+    if (metadata.size > MAX_STATE_BYTES) throw new Error("autonomy state exceeds 5 MiB");
+    return { state: normalizeAutonomy(JSON.parse(await readFile(paths.autonomyPath, "utf8")), paths.catalog.root), ...paths };
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return { state: emptyAutonomy(paths.catalog.root), ...paths };
+  }
+}
+
+async function saveAutonomy(state, path) {
+  const findings = autonomyFindings(state);
+  if (findings.length) throw new Error(`autonomy state failed closed: ${findings.join(", ")}`);
+  const content = `${JSON.stringify(state, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_STATE_BYTES) throw new Error("autonomy state exceeds 5 MiB");
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { mode: 0o600 });
+    await replaceFileWithRetry(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error) => { if (error.code !== "ENOENT") throw error; });
+  }
+}
+
+async function acquireLock(path) {
+  const lockPath = `${path}.lock`;
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    try {
+      const handle = await import("node:fs/promises").then(({ open }) => open(lockPath, "wx", 0o600));
+      return { handle, lockPath };
+    } catch (error) {
+      if (!isFileLockContention(error)) throw error;
+      try {
+        const metadata = await stat(lockPath);
+        if (Date.now() - metadata.mtimeMs > 90000) await unlink(lockPath);
+      } catch (lockError) {
+        if (lockError.code !== "ENOENT") throw lockError;
+      }
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+    }
+  }
+  throw new Error("autonomy state is busy; retry later");
+}
+
+export async function mutateAutonomy(root, operation) {
+  const paths = await autonomyPaths(root);
+  const { handle, lockPath } = await acquireLock(paths.autonomyPath);
+  try {
+    const { state } = await loadAutonomy(paths.catalog.root, paths.catalog);
+    const result = await operation(state, paths);
+    await saveAutonomy(state, paths.autonomyPath);
+    return result;
+  } finally {
+    await handle.close();
+    await unlink(lockPath).catch((error) => { if (error.code !== "ENOENT") throw error; });
+  }
+}
+
+export function signedRecord(body) {
+  return { ...body, recordDigest: digest(body) };
+}
+
+export function appendHistory(state, body) {
+  const entry = signedRecord({ id: `history:${randomUUID()}`, ...body, authority: "context-only" });
+  state.history.push(entry);
+  if (state.history.length > 2048) state.history.splice(0, state.history.length - 2048);
+  return entry;
+}
+
+export async function canonicalLocalRoot(value) {
+  const input = resolve(safeText(value, "localRoot", 4096));
+  const metadata = await lstat(input);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new Error("local project root must be a regular directory, not a symlink");
+  const canonical = await realpath(input);
+  const same = process.platform === "win32"
+    ? input.toLowerCase() === canonical.toLowerCase()
+    : input === canonical;
+  if (!same) throw new Error("local project root cannot traverse a symlink");
+  return canonical;
+}
+
+export function publicRepository(value) {
+  const url = new URL(safeText(value, "publicRepository", 2048));
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new Error("public repository must be a credential-free HTTPS URL without query or fragment");
+  }
+  return url.toString().replace(/\/$/, "");
+}

package/agent-spine-plugin/src/lib/autonomy.js

@@ -0,0 +1,8 @@
+export {
+  AUTONOMY_ACTIONS, AUTONOMY_CONFIRMATION, AUTONOMY_MODES, AUTONOMY_SCHEMA,
+  EVIDENCE_CLASSES, PUBLISH_CONFIRMATION, autonomyFindings, loadAutonomy, modeAllows
+} from "./autonomy-store.js";
+export {
+  autonomyStatus, configureAutonomyProject, evaluateAutonomyAction, revokeAutonomyProject
+} from "./autonomy-policy.js";
+export { projectPortfolioContext, recordProjectObservation, scanProjectPortfolio } from "./project-portfolio.js";

package/agent-spine-plugin/src/lib/briefing.js

@@ -8,6 +8,8 @@ import { sharedContext } from "./sharing.js";
 import { loadPersonaRuntime, personaRuntimeFindings } from "./persona-runtime.js";
 import { gatewayRuntimeFindings, loadGatewayRuntime } from "./gateway-runtime.js";
 import { voiceCue } from "./voice-runtime.js";
+import { worldContext } from "./world-model.js";
+import { projectPortfolioContext } from "./project-portfolio.js";
 
 const MIN_BYTES = 4096;
 const MAX_BYTES = 262144;
@@ -133,7 +135,7 @@ export async function sessionBriefing({
       ? { root: userStateRoot, entityId, includePrivate, groupId, catalog: userCatalog }
       : { root: catalog.root, entityId, includePrivate, groupId, catalog })
     : null;
-  const [learned, attention, tasks, shared, userLearned, personas, gateway] = await settleReads([
+  const [learned, attention, tasks, shared, userLearned, personas, gateway, world, portfolio] = await settleReads([
     learningContext({ root: catalog.root, includePrivate, groupId, scope: learningScope, maxItems: 50, catalog, now }),
     attentionContext({
       root: catalog.root, includePrivate, entityId, groupId, projectId, currentTaskId,
@@ -146,7 +148,11 @@ export async function sessionBriefing({
         catalog: userCatalog })
       : Promise.resolve({ items: [] }),
     loadPersonaRuntime(catalog.root, catalog),
-    loadGatewayRuntime(catalog.root, catalog)
+    loadGatewayRuntime(catalog.root, catalog),
+    worldContext({ root: catalog.root, projectId, groupId, includePrivate,
+      continuationTaskId: currentTaskId, maxItems: 50, now }),
+    tenantId ? projectPortfolioContext({ root: catalog.root, tenantId, groupId, markPresented: false, now })
+      : Promise.resolve({ projects: [], observations: [], notice: null, rateLimited: false })
   ]);
   const personaFindings = personaRuntimeFindings(personas.policy, personas.runtime);
   if (personaFindings.length) throw new Error(`persona runtime failed closed: ${personaFindings.join(", ")}`);
@@ -199,13 +205,26 @@ export async function sessionBriefing({
     },
     learning: [],
     shared: [],
+    world: {
+      schema: world.schema,
+      facts: [], conflicts: [], proposals: [], stale: [],
+      ...(world.knowledge.current.length ? { knowledge: {
+        schema: world.knowledge.schema, current: [], counts: world.knowledge.counts,
+        continuation: { ...world.knowledge.continuation, tasks: [], terminal: [] },
+        taskContext: { ...world.knowledge.taskContext, items: [] },
+        omitted: { ...world.knowledge.omitted }, authority: "context-only"
+      } } : {}),
+      uncertainty: world.uncertainty,
+      authority: "context-only"
+    },
     attention: { suppressed: attention.suppressed, items: [] },
+    portfolio: { projects: [], observations: [], notice: portfolio.notice, rateLimited: portfolio.rateLimited, authority: "context-only" },
     budget: {
       maxBytes: limit,
       usedBytes: 0,
       remainingBytes: 0,
       measurement: "compact-json-utf8",
-      omitted: { sources: 0, tasks: 0, relationships: 0, voice: 0, learning: 0, shared: 0, attention: 0 }
+      omitted: { sources: 0, tasks: 0, relationships: 0, voice: 0, learning: 0, shared: 0, world: 0, attention: 0, portfolio: 0 }
     },
     authority: "context-only",
     note: "This packet is descriptive context only. It grants no delegation, host, tool, file, network, production, spending, or policy rights. Native host rules and explicit local policy remain authoritative."
@@ -213,8 +232,42 @@ export async function sessionBriefing({
   recalculateBudget(result);
   if (result.budget.usedBytes > limit) throw new Error(`maxBytes is too small for the briefing envelope; use at least ${MIN_BYTES}`);
 
+  const continuationIds = new Set();
+  for (const item of world.knowledge.continuation.tasks) {
+    if (tryAdd(result, result.world.knowledge.continuation.tasks, item)) continuationIds.add(item.assertionId);
+    else countOmitted(result, "world");
+  }
+  for (const item of world.knowledge.continuation.terminal) {
+    if (tryAdd(result, result.world.knowledge.continuation.terminal, item)) continuationIds.add(item.assertionId);
+    else countOmitted(result, "world");
+  }
+  const contextualIds = new Set(continuationIds);
+  for (const item of world.knowledge.taskContext.items) {
+    if (tryAdd(result, result.world.knowledge.taskContext.items, item)) contextualIds.add(item.id);
+    else {
+      result.world.knowledge.taskContext.omitted += 1;
+      countOmitted(result, "world");
+    }
+  }
+  for (const section of ["facts", "conflicts", "proposals", "stale"]) {
+    const items = section === "facts"
+      ? world[section].filter((item) => !item.assertionIds?.some((id) => contextualIds.has(id)))
+      : world[section];
+    for (const item of items) {
+      if (!tryAdd(result, result.world[section], item)) countOmitted(result, "world");
+    }
+  }
+  for (const item of world.knowledge.current.filter((entry) => !contextualIds.has(entry.id))) {
+    if (!tryAdd(result, result.world.knowledge.current, item)) {
+      result.world.knowledge.omitted.current += 1;
+      countOmitted(result, "world");
+    }
+  }
+
   const scopedTasks = tasks.items.filter((task) => taskMatchesScope(task, entityId));
-  if (currentTaskId && !scopedTasks.some((task) => task.id === currentTaskId)) {
+  const continuedTask = [...world.knowledge.continuation.tasks, ...world.knowledge.continuation.terminal]
+    .find((task) => task.taskId === currentTaskId) || null;
+  if (currentTaskId && !scopedTasks.some((task) => task.id === currentTaskId) && !continuedTask) {
     throw new Error(`current task is not visible in this briefing scope: ${currentTaskId}`);
   }
   const orderedTasks = [...scopedTasks].sort((left, right) => {
@@ -229,6 +282,10 @@ export async function sessionBriefing({
   if (focusedTask && !trySet(result, result.voiceBrief, "currentTask", {
     id: focusedTask.id, title: focusedTask.title, status: focusedTask.status
   })) countOmitted(result, "voice");
+  if (!focusedTask && continuedTask && !trySet(result, result.voiceBrief, "currentTask", {
+    id: continuedTask.taskId, title: continuedTask.objective, status: continuedTask.status,
+    nextStep: continuedTask.nextStep
+  })) countOmitted(result, "voice");
   const focusedGoal = entityId ? gateway.policy.goals.find((goal) => goal.agentId === entityId && goal.status === "active"
     && (projectId === null || goal.projectId === projectId) && goal.groupId === groupId) : null;
   if (focusedGoal && !trySet(result, result.voiceBrief, "currentGoal", {
@@ -310,6 +367,12 @@ export async function sessionBriefing({
   for (const item of attentionItems) {
     if (!tryAdd(result, result.attention.items, item)) countOmitted(result, "attention");
   }
+  for (const item of portfolio.projects) {
+    if (!tryAdd(result, result.portfolio.projects, item)) countOmitted(result, "portfolio");
+  }
+  for (const item of portfolio.observations) {
+    if (!tryAdd(result, result.portfolio.observations, item)) countOmitted(result, "portfolio");
+  }
 
   recalculateBudget(result);
   if (result.budget.usedBytes > limit) throw new Error("briefing budget invariant failed");

package/agent-spine-plugin/src/lib/catalog-document-read.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { canonicalPath, isInside } from "./paths.js";
+
+function sameFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino && a.size === b.size
+    && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+
+export async function readCatalogDocument({ root, catalog, path, offset = 0, length = 65536 }) {
+  if (catalog.root !== await canonicalPath(root)) throw new Error("catalog belongs to a different project root");
+  const absolute = resolve(catalog.root, path);
+  const document = catalog.documents.find(item => item.relativePath === path
+    || (isInside(catalog.root, absolute) && item.path === absolute));
+  if (!document) throw new Error("path is not an indexed Markdown document in the bounded host sources");
+  const before = await lstat(document.path);
+  if (!before.isFile() || before.isSymbolicLink() || before.size !== document.bytes
+    || before.size > 4 * 1024 * 1024 || await realpath(document.path) !== document.path) {
+    throw new Error("indexed contract source changed before reading");
+  }
+  const handle = await open(document.path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  let buffer;
+  try {
+    if (!sameFile(before, await handle.stat())) throw new Error("indexed contract source was replaced");
+    // A concurrent append must not turn this bounded read into an unbounded one.
+    buffer = Buffer.alloc(before.size + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const result = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+      if (!result.bytesRead) break;
+      bytesRead += result.bytesRead;
+    }
+    buffer = buffer.subarray(0, bytesRead);
+    if (!sameFile(before, await handle.stat()) || !sameFile(before, await lstat(document.path))
+      || await realpath(document.path) !== document.path
+      || createHash("sha256").update(buffer).digest("hex") !== document.sha256) {
+      throw new Error("indexed contract source changed during reading");
+    }
+  } finally {
+    await handle.close();
+  }
+  const start = Math.min(buffer.length, Math.max(0, Number(offset) || 0));
+  const end = Math.min(buffer.length, start + Math.max(0, Number(length) || 0));
+  return { path: isInside(catalog.root, document.path)
+    ? relative(catalog.root, document.path).replaceAll("\\", "/") : document.relativePath,
+    sha256: document.sha256, offset: start, bytes: end - start, totalBytes: buffer.length,
+    eof: end >= buffer.length, encoding: "utf8", content: buffer.subarray(start, end).toString("utf8"),
+    contentBase64: buffer.subarray(start, end).toString("base64") };
+}

package/agent-spine-plugin/src/lib/catalog.js

@@ -67,7 +67,7 @@ function catalogConflicts(documents) {
 
 export async function buildCatalog(inputRoot = process.cwd(), { env = process.env } = {}) {
   const root = await canonicalPath(inputRoot);
-  const documents = await discoverDocuments(root, { excludeRoots: [stateRoot(env)] });
+  const documents = await discoverDocuments(root, { excludeRoots: [stateRoot(env)], env });
   const conflicts = catalogConflicts(documents);
   const byLayer = Object.fromEntries(
     [...new Set(documents.map((document) => document.layer))]

package/agent-spine-plugin/src/lib/codex-installation.js

@@ -0,0 +1,231 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+import { defaultCodexSkillsRoot, installCodexSkill } from "./codex-skill-installation.js";
+
+const REGISTRATION_SCHEMA = "agentspine.codex-reader-registration/v1";
+const AUTHORITY = "host-registration-only";
+const START = "# BEGIN AGENTSPINE MANAGED MCP";
+const END = "# END AGENTSPINE MANAGED MCP";
+const MAX_CONFIG_BYTES = 1024 * 1024;
+const EXPECTED_TOOLS = [
+  "session_briefing", "delivery_knowledge_query",
+  "record_delivery_premortem", "read_document"
+];
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function seal(value) {
+  return { ...value, digest: sha256(canonical(value)) };
+}
+
+async function regularFile(path, label) {
+  const metadata = await lstat(path);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error(`${label} must be a regular non-symlink file`);
+  return path;
+}
+
+async function exactDirectory(path, label, { create = false } = {}) {
+  const target = resolve(path);
+  if (!isAbsolute(path)) throw new Error(`${label} must be absolute`);
+  if (create) await mkdir(target, { recursive: true, mode: 0o700 });
+  const metadata = await lstat(target);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new Error(`${label} must be a regular non-symlink directory`);
+  return realpath(target);
+}
+
+async function optionalText(path) {
+  try {
+    await regularFile(path, "Codex config.toml");
+    const value = await readFile(path, "utf8");
+    if (Buffer.byteLength(value) > MAX_CONFIG_BYTES) throw new Error("Codex config.toml exceeds 1 MiB");
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+async function regularOrMissing(path, label) {
+  try {
+    await regularFile(path, label);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+function managedRange(text) {
+  const starts = [...text.matchAll(new RegExp(`^${START}$`, "gm"))];
+  const ends = [...text.matchAll(new RegExp(`^${END}$`, "gm"))];
+  if (!starts.length && !ends.length) return null;
+  if (starts.length !== 1 || ends.length !== 1 || ends[0].index < starts[0].index) {
+    throw new Error("Codex config contains a malformed AgentSpine managed block");
+  }
+  let end = ends[0].index + END.length;
+  if (text.slice(end, end + 2) === "\r\n") end += 2;
+  else if (text[end] === "\n") end += 1;
+  const start = starts[0].index > 0 ? starts[0].index - 1 : starts[0].index;
+  return { start, end };
+}
+
+function hasRegistration(text) {
+  return /^\s*\[\s*mcp_servers\s*\.\s*(?:agent-spine|["']agent-spine["'])\s*\]\s*(?:#.*)?$/m.test(text);
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+function managedBlock(nodePath, launcherPath) {
+  return [
+    START,
+    "[mcp_servers.agent-spine]",
+    `command = ${tomlString(nodePath)}`,
+    `args = [${tomlString(launcherPath)}]`,
+    "enabled = true",
+    END,
+    ""
+  ].join("\n");
+}
+
+function updateConfig(text, block) {
+  const range = managedRange(text);
+  if (range) {
+    const prefix = text.slice(0, range.start);
+    const suffix = text.slice(range.end);
+    const outside = prefix + suffix;
+    if (hasRegistration(outside)) throw new Error("Codex config has an unmanaged AgentSpine MCP registration");
+    return { text: prefix + (prefix.length ? "\n" : "") + block + suffix,
+      outsideBefore: outside, outsideAfter: outside, status: "updated" };
+  }
+  if (hasRegistration(text)) throw new Error("Codex config has an unmanaged AgentSpine MCP registration");
+  const separator = text.length ? "\n" : "";
+  return { text: text + separator + block,
+    outsideBefore: text, outsideAfter: text, status: "installed" };
+}
+
+async function atomicWrite(path, content, assertOwned) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(content);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await replaceFileWithRetry(temporary, path, { beforeAttempt: assertOwned });
+  } finally {
+    await handle?.close();
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+async function packageRegistration(packageRoot, nodePath) {
+  const root = await exactDirectory(packageRoot, "AgentSpine package root");
+  const entrypoint = await regularFile(join(root, "src", "mcp.js"), "AgentSpine MCP entrypoint");
+  const versionSource = await regularFile(join(root, "src", "version.js"), "AgentSpine version source");
+  const packageFile = await regularFile(join(root, "package.json"), "AgentSpine package manifest");
+  const packageJson = await readFile(packageFile, "utf8");
+  const pkg = JSON.parse(packageJson);
+  const source = await readFile(versionSource, "utf8");
+  const sourceVersion = source.match(/^export const VERSION = "([^"]+)";\s*$/)?.[1];
+  if (!pkg.version || sourceVersion !== pkg.version) throw new Error("AgentSpine package and runtime versions differ");
+  const canonicalNode = await realpath(await regularFile(nodePath, "Node.js runtime"));
+  return seal({
+    schema: REGISTRATION_SCHEMA,
+    expectedName: "agent-spine",
+    expectedVersion: pkg.version,
+    expectedTools: EXPECTED_TOOLS,
+    packageRoot: root,
+    nodePath: canonicalNode,
+    entrypoint,
+    entrypointDigest: sha256(await readFile(entrypoint)),
+    packageDigest: sha256(packageJson),
+    versionSourceDigest: sha256(source),
+    authority: AUTHORITY
+  });
+}
+
+export function defaultCodexHome(env = process.env) {
+  return resolve(env.CODEX_HOME || join(homedir(), ".codex"));
+}
+
+export async function installCodexMcp({
+  codexHome = defaultCodexHome(),
+  skillsRoot = defaultCodexSkillsRoot(),
+  packageRoot = fileURLToPath(new URL("../..", import.meta.url)),
+  nodePath = process.execPath,
+  faultAfter = null
+} = {}) {
+  const home = await exactDirectory(codexHome, "Codex home", { create: true });
+  const managed = join(home, "agentspine");
+  await exactDirectory(managed, "Codex AgentSpine directory", { create: true });
+  const configPath = join(home, "config.toml");
+  const launcherPath = join(managed, "reader-launcher.mjs");
+  const registrationPath = join(managed, "registration.json");
+  const lockPath = join(managed, "install.lock");
+  try {
+    const lock = await lstat(lockPath);
+    if (lock.isSymbolicLink()) throw new Error("Codex AgentSpine install lock must not be a symlink");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return withOwnedFileLock(lockPath, async ({ assertOwned }) => {
+    await Promise.all([
+      regularOrMissing(launcherPath, "Codex AgentSpine launcher"),
+      regularOrMissing(registrationPath, "Codex AgentSpine registration")
+    ]);
+    const [before, registration, launcher] = await Promise.all([
+      optionalText(configPath), packageRegistration(packageRoot, nodePath),
+      readFile(fileURLToPath(new URL("../codex-reader-launcher.js", import.meta.url)))
+    ]);
+    const update = updateConfig(before, managedBlock(registration.nodePath, launcherPath));
+    if (update.outsideBefore !== update.outsideAfter) throw new Error("unmanaged Codex configuration bytes changed");
+    const skill = await installCodexSkill({
+      skillsRoot, packageRoot,
+      faultAfter: faultAfter === "skill-marker" ? "marker" : faultAfter === "skill" ? "skill" : null
+    });
+    if (skill.version !== registration.expectedVersion || skill.packageRoot !== registration.packageRoot) {
+      throw new Error("Codex skill and MCP reader package identity differ");
+    }
+    await atomicWrite(launcherPath, launcher, assertOwned);
+    if (faultAfter === "launcher") throw new Error("synthetic crash after launcher publication");
+    await atomicWrite(registrationPath, `${JSON.stringify(registration, null, 2)}\n`, assertOwned);
+    if (faultAfter === "registration") throw new Error("synthetic crash after registration publication");
+    await atomicWrite(configPath, update.text, assertOwned);
+    return {
+      schema: "agentspine.codex-installation/v1",
+      status: update.status,
+      version: registration.expectedVersion,
+      configPath,
+      launcherPath,
+      registrationPath,
+      registrationDigest: registration.digest,
+      unmanagedBeforeDigest: sha256(update.outsideBefore),
+      unmanagedAfterDigest: sha256(update.outsideAfter),
+      configDigest: sha256(update.text),
+      skill,
+      restartRequired: true,
+      authority: AUTHORITY
+    };
+  });
+}
+
+export function stripManagedCodexBlock(text) {
+  const range = managedRange(text);
+  return range ? text.slice(0, range.start) + text.slice(range.end) : text;
+}