@twin3-ai/agent-id 0.1.0 → 0.3.0

package/installer.js

@@ -1,14 +1,46 @@
 "use strict";
 
 const fs = require("node:fs/promises");
+const fsSync = require("node:fs");
 const path = require("node:path");
+const os = require("node:os");
 const crypto = require("node:crypto");
 const { DEFAULT_ENDPOINT } = require("./runtime-config.js");
 
 const INSTALL_SCHEMA = "agentx-install-plan-v1";
 const STATE_SCHEMA = "agentx-site-agent-install-state-v1";
 const MANAGED_DIR = ".agent-id";
+const TRANSACTION_SCHEMA = "agentx-install-transaction-journal-v1";
+const COMMIT_SCHEMA = "agentx-install-commit-marker-v1";
+const TRANSACTION_DIR = `${MANAGED_DIR}/.transactions`;
+const TRANSACTION_JOURNAL = `${TRANSACTION_DIR}/active.json`;
+const TRANSACTION_LOCK = `${TRANSACTION_DIR}/active.lock`;
+const COMMIT_MARKER = `${MANAGED_DIR}/install-commit.json`;
 const SECRET_IGNORE = "*\n!.gitignore\n";
+const INSTALL_MODULES = Object.freeze({
+  identity: Object.freeze({ permission: "identity_publish", label: "Domain-bound Agent identity" }),
+  audit: Object.freeze({ permission: "public_read", label: "SEO / AEO / GEO / AGO public audit" }),
+  measurement: Object.freeze({ permission: "telemetry_submit", label: "AI reads, citations, and conversion evidence" }),
+  optimization: Object.freeze({ permission: "insights_read", label: "Evidence-bound optimization insights" }),
+  automation: Object.freeze({ permission: "ai_files_write", label: "Locally approved AI-file updates and rollback" }),
+});
+const DEFAULT_INSTALL_MODULES = Object.freeze(["identity", "audit", "optimization"]);
+
+function normalizeInstallSelection(modules, grantedPermissions) {
+  const selected = [...new Set((Array.isArray(modules) && modules.length ? modules : DEFAULT_INSTALL_MODULES).map(String))];
+  const unknown = selected.filter((name) => !INSTALL_MODULES[name]);
+  if (unknown.length) throw installError("INVALID_INSTALL_MODULE", `Unknown install modules: ${unknown.join(", ")}`);
+  if (!selected.includes("identity")) throw installError("INSTALL_IDENTITY_REQUIRED", "The identity module is required for every Agent ID installation.");
+  const granted = [...new Set((Array.isArray(grantedPermissions) ? grantedPermissions : selected.map((name) => INSTALL_MODULES[name].permission)).map(String))];
+  const missing = selected.filter((name) => !granted.includes(INSTALL_MODULES[name].permission));
+  if (missing.length) throw installError("INSTALL_PERMISSION_REQUIRED", `Missing permissions for modules: ${missing.join(", ")}`);
+  const knownPermissions = new Set(Object.values(INSTALL_MODULES).map((item) => item.permission));
+  const unsupported = granted.filter((permission) => !knownPermissions.has(permission));
+  if (unsupported.length) throw installError("INVALID_INSTALL_PERMISSION", `Unknown install permissions: ${unsupported.join(", ")}`);
+  const unused = granted.filter((permission) => !selected.some((name) => INSTALL_MODULES[name].permission === permission));
+  if (unused.length) throw installError("UNUSED_INSTALL_PERMISSION", `Permissions without a selected module are not allowed: ${unused.join(", ")}`);
+  return { modules: selected, granted_permissions: granted };
+}
 
 function installError(code, message) {
   const error = new Error(message);
@@ -19,6 +51,20 @@ function installError(code, message) {
 function normalizeProjectRoot(projectRoot = process.cwd()) {
   const root = path.resolve(String(projectRoot));
   if (!path.isAbsolute(root)) throw installError("INVALID_PROJECT_ROOT", "Project root must be an absolute path.");
+  if (root === path.parse(root).root) {
+    throw installError("UNSAFE_PROJECT_ROOT_FILESYSTEM", "UNSAFE_PROJECT_ROOT_FILESYSTEM: Refusing to install at the filesystem root.");
+  }
+  if (root === path.resolve(os.homedir())) {
+    throw installError("UNSAFE_PROJECT_ROOT_HOME", "UNSAFE_PROJECT_ROOT_HOME: Refusing to install in the user home directory. Select the website project or published static-site directory.");
+  }
+  try {
+    if (fsSync.realpathSync.native(root) === fsSync.realpathSync.native(os.homedir())) {
+      throw installError("UNSAFE_PROJECT_ROOT_HOME", "UNSAFE_PROJECT_ROOT_HOME: Refusing to install through a path that resolves to the user home directory.");
+    }
+  } catch (error) {
+    if (error && error.code === "UNSAFE_PROJECT_ROOT_HOME") throw error;
+    if (!error || error.code !== "ENOENT") throw error;
+  }
   return root;
 }
 
@@ -38,8 +84,12 @@ function normalizeSiteUrl(value) {
 }
 
 async function readJson(filePath) {
+  return readJsonWith(fs, filePath);
+}
+
+async function readJsonWith(fsImpl, filePath) {
   try {
-    return JSON.parse(await fs.readFile(filePath, "utf8"));
+    return JSON.parse(await fsImpl.readFile(filePath, "utf8"));
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
@@ -62,6 +112,24 @@ async function detectProject({ projectRoot = process.cwd(), fsImpl = fs } = {})
   };
   const dependencyNames = Object.keys(dependencies);
   const hasStaticEntry = await exists("index.html") || await exists("public/index.html");
+  const frameworkMarkers = [
+    "next.config.js", "next.config.mjs", "next.config.ts",
+    "nuxt.config.js", "nuxt.config.ts", "astro.config.js", "astro.config.mjs",
+    "vite.config.js", "vite.config.mjs", "vite.config.ts", "gatsby-config.js",
+    "svelte.config.js"
+  ];
+  const detectedMarkers = [];
+  if (hasStaticEntry) detectedMarkers.push("html_entry");
+  if (await exists(".git")) detectedMarkers.push("git_repository");
+  if ((await Promise.all(frameworkMarkers.map(exists))).some(Boolean)) detectedMarkers.push("framework_config");
+  const packageHasProjectIdentity = Boolean(packageJson && (
+    (packageJson.scripts && Object.keys(packageJson.scripts).length)
+    || dependencyNames.some((name) => name !== "@twin3-ai/agent-id")
+  ));
+  if (packageHasProjectIdentity) detectedMarkers.push("project_package_manifest");
+  if (!detectedMarkers.length) {
+    throw installError("PROJECT_ROOT_NOT_SITE", "PROJECT_ROOT_NOT_SITE: The selected directory is not a recognizable website project. Provide a directory with an HTML entry, repository metadata, framework config, or real project package manifest.");
+  }
   const cliOnlyStaticSite = Boolean(
     packageJson
     && hasStaticEntry
@@ -89,6 +157,7 @@ async function detectProject({ projectRoot = process.cwd(), fsImpl = fs } = {})
     framework,
     package_manager: packageManager,
     package_name: packageJson && typeof packageJson.name === "string" ? packageJson.name : "",
+    project_markers: detectedMarkers,
     detected_files: detectedFiles
   };
 }
@@ -124,7 +193,7 @@ module.exports = { createAgentIdRuntime };
 `;
 }
 
-function staticRunnerTemplate(siteUrl) {
+function staticRunnerTemplate(siteUrl, modules = DEFAULT_INSTALL_MODULES) {
   return `"use strict";
 
 const fs = require("node:fs/promises");
@@ -134,6 +203,7 @@ const SITE_URL = process.env.SITE_URL || ${JSON.stringify(siteUrl)};
 const AGENT_ID_ENDPOINT = String(process.env.AGENT_ID_ENDPOINT || "").replace(/\\/+$/, "");
 const SITE_AGENT_KEY = process.env.SITE_AGENT_KEY || "";
 const SYNC_MODE = process.env.AGENT_ID_SYNC_MODE || "full";
+const ENABLED_MODULES = new Set(${JSON.stringify(modules)});
 
 function redact(value) {
   if (Array.isArray(value)) return value.map(redact);
@@ -167,11 +237,15 @@ async function main() {
   if (!SITE_AGENT_KEY) throw new Error("SITE_AGENT_KEY is required in the customer-owned runner environment.");
   if (!["heartbeat", "monthly", "full"].includes(SYNC_MODE)) throw new Error("AGENT_ID_SYNC_MODE must be heartbeat, monthly, or full.");
   const observedAt = new Date().toISOString();
-  const heartbeat = SYNC_MODE === "monthly" ? { skipped: true, reason: "monthly_insights_run" } : await call("site_agent_events", {
+  const heartbeat = !ENABLED_MODULES.has("measurement")
+    ? { skipped: true, reason: "measurement_module_not_granted" }
+    : SYNC_MODE === "monthly" ? { skipped: true, reason: "monthly_insights_run" } : await call("site_agent_events", {
     source: "customer_owned_github_actions_runner",
-    events: [{ event: "heartbeat", url: SITE_URL, ts: Math.floor(Date.now() / 1000), data: { runtime: "github_actions", sdk_version: "0.1.0" } }]
+    events: [{ event: "heartbeat", url: SITE_URL, ts: Math.floor(Date.now() / 1000), data: { runtime: "github_actions", sdk_version: "0.3.0" } }]
   });
-  const insights = SYNC_MODE === "heartbeat" ? { skipped: true, reason: "daily_heartbeat_only" } : await call("insights_feed", {
+  const insights = !ENABLED_MODULES.has("optimization")
+    ? { skipped: true, reason: "optimization_module_not_granted" }
+    : SYNC_MODE === "heartbeat" ? { skipped: true, reason: "daily_heartbeat_only" } : await call("insights_feed", {
     source: "customer_owned_github_actions_runner",
     audit_url: true,
     cadence: "monthly"
@@ -182,6 +256,7 @@ async function main() {
     parent_endpoint: AGENT_ID_ENDPOINT,
     observed_at: observedAt,
     sync_mode: SYNC_MODE,
+    enabled_modules: [...ENABLED_MODULES],
     heartbeat,
     insights,
     authority: "advisory_only",
@@ -280,7 +355,7 @@ This directory contains only the local install state and a server-side helper te
 }
 
 function stateTemplate(plan) {
-  return {
+  const state = {
     schema: STATE_SCHEMA,
     install_id: plan.install_id,
     site_url: plan.site_url,
@@ -288,6 +363,8 @@ function stateTemplate(plan) {
     parent_endpoint: plan.parent_endpoint,
     framework: plan.framework,
     package_manager: plan.package_manager,
+    modules: [...(plan.modules || [])],
+    granted_permissions: [...(plan.granted_permissions || [])],
     status: "installed",
     verification_status: "pending_domain_verification",
     requires_site_agent_key: true,
@@ -295,24 +372,122 @@ function stateTemplate(plan) {
       ? "github_actions_secret:SITE_AGENT_KEY"
       : "server_secret_store:SITE_AGENT_KEY",
     managed_paths: plan.files.map((file) => file.path),
+    managed_files: plan.files
+      .filter((file) => file.path !== `${MANAGED_DIR}/install-state.json`)
+      .map((file) => ({ path: file.path, sha256: file.sha256 })),
     no_direct_customer_site_mutation: true,
     no_secret_in_state: true
   };
+  state.state_hash = hashText(stableJson(state));
+  return state;
 }
 
-function buildInstallPlan({ url, projectRoot = process.cwd(), endpoint = DEFAULT_ENDPOINT, framework, packageManager, detected } = {}) {
+function verifyInstallState(state) {
+  if (!state || state.schema !== STATE_SCHEMA || typeof state.state_hash !== "string") return false;
+  const unsigned = { ...state };
+  delete unsigned.state_hash;
+  return state.state_hash === hashText(stableJson(unsigned));
+}
+
+const OPPORTUNITY_CHECKS = Object.freeze([
+  { id: "package_manifest", paths: ["package.json"] },
+  { id: "llms_txt", paths: ["llms.txt", "public/llms.txt"] },
+  { id: "robots_txt", paths: ["robots.txt", "public/robots.txt"] },
+  { id: "agent_card", paths: [".well-known/agent-card.json", "public/.well-known/agent-card.json"] },
+  { id: "agent_id", paths: [".well-known/agent-id.json", "public/.well-known/agent-id.json"] },
+  { id: "aeo_agent", paths: [".well-known/aeo-agent.json", "public/.well-known/aeo-agent.json"] },
+  { id: "agent_knowledge", paths: [".well-known/agent-knowledge.json", "public/.well-known/agent-knowledge.json"] }
+]);
+
+async function inspectAgentIdOpportunities({ projectRoot = process.cwd(), fsImpl = fs, checks = OPPORTUNITY_CHECKS } = {}) {
+  const root = normalizeProjectRoot(projectRoot);
+  const reportChecks = [];
+  for (const definition of checks) {
+    const presentPaths = [];
+    const unavailablePaths = [];
+    const unavailableErrors = {};
+    const symlinkPaths = [];
+    for (const relativePath of definition.paths) {
+      if (typeof fsImpl.lstat !== "function") {
+        unavailablePaths.push(relativePath);
+        unavailableErrors[relativePath] = "LSTAT_UNAVAILABLE";
+        continue;
+      }
+      try {
+        const candidate = path.resolve(root, relativePath);
+        const withinRoot = path.relative(root, candidate);
+        if (withinRoot === ".." || withinRoot.startsWith(`..${path.sep}`) || path.isAbsolute(withinRoot)) {
+          unavailablePaths.push(relativePath);
+          unavailableErrors[relativePath] = "PATH_ESCAPE";
+          continue;
+        }
+        const stat = await fsImpl.lstat(candidate);
+        if (stat.isSymbolicLink()) {
+          symlinkPaths.push(relativePath);
+          unavailablePaths.push(relativePath);
+          unavailableErrors[relativePath] = "SYMLINK_REJECTED";
+          continue;
+        }
+        if (typeof stat.isFile === "function" && !stat.isFile()) {
+          unavailablePaths.push(relativePath);
+          unavailableErrors[relativePath] = "NOT_REGULAR_FILE";
+          continue;
+        }
+        presentPaths.push(relativePath);
+      } catch (error) {
+        if (!error || error.code !== "ENOENT") {
+          unavailablePaths.push(relativePath);
+          unavailableErrors[relativePath] = (error && ["EACCES", "EPERM"].includes(error.code))
+            ? "PERMISSION_DENIED"
+            : "UNAVAILABLE";
+        }
+      }
+    }
+    reportChecks.push({
+      id: definition.id,
+      status: presentPaths.length ? "present" : unavailablePaths.length ? "unavailable" : "missing",
+      present_paths: presentPaths,
+      unavailable_paths: unavailablePaths,
+      unavailable_errors: unavailableErrors,
+      symlink_paths: symlinkPaths,
+      candidate_paths: [...definition.paths]
+    });
+  }
+  const present = reportChecks.filter((item) => item.status === "present").length;
+  const unavailable = reportChecks.filter((item) => item.status === "unavailable").length;
+  return {
+    schema: "agentx-local-opportunity-report-v1",
+    local_only: true,
+    source_uploaded: false,
+    secrets_scanned: false,
+    content_validated: false,
+    verified: 0,
+    checks: reportChecks,
+    symlink_policy: "skip_and_exclude",
+    summary: {
+      total: reportChecks.length,
+      present,
+      missing: reportChecks.length - present - unavailable,
+      unavailable
+    }
+  };
+}
+
+function buildInstallPlan({ url, projectRoot = process.cwd(), endpoint = DEFAULT_ENDPOINT, framework, packageManager, detected, modules, grantedPermissions } = {}) {
   return Promise.resolve().then(async () => {
     const siteUrl = normalizeSiteUrl(url);
     const root = normalizeProjectRoot(projectRoot);
+    const selection = normalizeInstallSelection(modules, grantedPermissions);
     const detectedProject = detected || await detectProject({ projectRoot: root });
     const selectedFramework = framework || detectedProject.framework;
     const selectedPackageManager = packageManager || detectedProject.package_manager;
+    const opportunityReport = await inspectAgentIdOpportunities({ projectRoot: root });
     if (!/^[a-z][a-z0-9._-]{0,31}$/.test(String(selectedFramework))) throw installError("INVALID_FRAMEWORK", "Framework identifier is invalid.");
     if (!/^[a-z][a-z0-9._-]{0,31}$/.test(String(selectedPackageManager))) throw installError("INVALID_PACKAGE_MANAGER", "Package manager identifier is invalid.");
     const parentEndpoint = String(endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
     const files = selectedFramework === "static" ? [
       { path: `${MANAGED_DIR}/install-state.json`, mode: "private", content: "" },
-      { path: `${MANAGED_DIR}/runner.cjs`, mode: "customer_runner", content: staticRunnerTemplate(siteUrl, parentEndpoint) },
+      { path: `${MANAGED_DIR}/runner.cjs`, mode: "customer_runner", content: staticRunnerTemplate(siteUrl, selection.modules) },
       { path: `${MANAGED_DIR}/README.md`, mode: "documentation", content: readmeTemplate(siteUrl, selectedFramework, selectedPackageManager, parentEndpoint) },
       { path: ".github/workflows/agent-id-sync.yml", mode: "customer_runner_workflow", content: staticWorkflowTemplate(siteUrl, parentEndpoint) }
     ] : [
@@ -328,6 +503,10 @@ function buildInstallPlan({ url, projectRoot = process.cwd(), endpoint = DEFAULT
       project_root: root,
       framework: selectedFramework,
       package_manager: selectedPackageManager,
+      modules: selection.modules,
+      granted_permissions: selection.granted_permissions,
+      module_catalog: INSTALL_MODULES,
+      opportunity_report: opportunityReport,
       approval_required: true,
       side_effects: selectedFramework === "static"
         ? ["write_agent_id_namespace", "write_dedicated_github_actions_workflow"]
@@ -338,9 +517,35 @@ function buildInstallPlan({ url, projectRoot = process.cwd(), endpoint = DEFAULT
         : ["verify_domain_ownership", "install_server_package", "store_SITE_AGENT_KEY_in_server_secret_store", "start_site_agent_sync"],
       files: files.map(({ path: filePath, mode, content }) => ({ path: filePath, mode, sha256: hashText(content) }))
     };
-    base.install_id = hashText(stableJson(base)).slice(0, 24);
-    base.files[0].sha256 = hashText(JSON.stringify(stateTemplate({ ...base, files: base.files }), null, 2) + "\n");
-    return Object.freeze({ ...base, files: files.map((file, index) => ({ ...base.files[index], content: file.content })) });
+    // install_id identifies the deterministic install plan, not the mutable
+    // state file that is generated from that plan at apply time.
+    const installIdentity = {
+      schema: base.schema,
+      version: base.version,
+      site_url: base.site_url,
+      parent_endpoint: base.parent_endpoint,
+      framework: base.framework,
+      package_manager: base.package_manager,
+      modules: base.modules,
+      granted_permissions: base.granted_permissions,
+      approval_required: base.approval_required,
+      side_effects: base.side_effects,
+      excluded_side_effects: base.excluded_side_effects,
+      next_steps: base.next_steps,
+      files: base.files.filter((file) => file.path !== `${MANAGED_DIR}/install-state.json`)
+    };
+    base.install_id = hashText(stableJson(installIdentity)).slice(0, 24);
+    const stateContent = JSON.stringify(stateTemplate({ ...base, files: base.files }), null, 2) + "\n";
+    const stateFileIndex = base.files.findIndex((file) => file.path === `${MANAGED_DIR}/install-state.json`);
+    if (stateFileIndex < 0) throw installError("INSTALL_STATE_FILE_MISSING", "The install plan must include its managed state file.");
+    base.files[stateFileIndex].sha256 = hashText(stateContent);
+    return Object.freeze({
+      ...base,
+      files: files.map((file, index) => ({
+        ...base.files[index],
+        content: file.path === `${MANAGED_DIR}/install-state.json` ? stateContent : file.content
+      }))
+    });
   });
 }
 
@@ -358,15 +563,34 @@ function validatePlan(plan) {
   return root;
 }
 
-async function writeAtomic(filePath, content, mode) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true, mode: mode === "private" ? 0o700 : 0o755 });
+async function syncDirectory(directory, fsImpl = fs) {
+  let handle;
+  try {
+    handle = await fsImpl.open(directory, "r");
+    await handle.sync();
+  } catch (error) {
+    if (!error || !["EINVAL", "ENOTSUP", "EISDIR", "EPERM"].includes(error.code)) throw error;
+  } finally {
+    if (handle) await handle.close();
+  }
+}
+
+async function writeAtomic(filePath, content, mode, fsImpl = fs) {
+  await fsImpl.mkdir(path.dirname(filePath), { recursive: true, mode: mode === "private" ? 0o700 : 0o755 });
   const temp = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  let handle;
   try {
-    await fs.writeFile(temp, content, { encoding: "utf8", mode: mode === "private" ? 0o600 : 0o644 });
-    await fs.rename(temp, filePath);
-    await fs.chmod(filePath, mode === "private" ? 0o600 : 0o644);
+    handle = await fsImpl.open(temp, "wx", mode === "private" ? 0o600 : 0o644);
+    await handle.writeFile(content, { encoding: "utf8" });
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await fsImpl.rename(temp, filePath);
+    await fsImpl.chmod(filePath, mode === "private" ? 0o600 : 0o644);
+    await syncDirectory(path.dirname(filePath), fsImpl);
   } finally {
-    await fs.rm(temp, { force: true }).catch(() => {});
+    if (handle) await handle.close().catch(() => {});
+    await fsImpl.rm(temp, { force: true }).catch(() => {});
   }
 }
 
@@ -560,14 +784,14 @@ function installContents(plan) {
     contents: {
       [`${MANAGED_DIR}/install-state.json`]: JSON.stringify(state, null, 2) + "\n",
       [`${MANAGED_DIR}/site-agent.cjs`]: runtimeTemplate(),
-      [`${MANAGED_DIR}/runner.cjs`]: staticRunnerTemplate(plan.site_url),
+      [`${MANAGED_DIR}/runner.cjs`]: staticRunnerTemplate(plan.site_url, plan.modules),
       [`${MANAGED_DIR}/README.md`]: readmeTemplate(plan.site_url, plan.framework, plan.package_manager, plan.parent_endpoint),
       ".github/workflows/agent-id-sync.yml": staticWorkflowTemplate(plan.site_url)
     }
   };
 }
 
-async function inspectInstallPlan(plan) {
+async function inspectInstallPlan(plan, { fsImpl = fs } = {}) {
   const root = validatePlan(plan);
   const { state, contents } = installContents(plan);
   const prepared = [];
@@ -577,7 +801,7 @@ async function inspectInstallPlan(plan) {
     const content = contents[file.path];
     if (typeof content !== "string" || hashText(content) !== file.sha256) throw installError("PLAN_CONTENT_MISMATCH", `Install plan content mismatch for ${file.path}.`);
     let existing = null;
-    try { existing = await fs.readFile(target, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    try { existing = await fsImpl.readFile(target, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }
     if (existing !== null && existing !== content) throw installError("INSTALL_CONFLICT", `Refusing to overwrite an existing file: ${file.path}`);
     prepared.push({ file, target, content, existing });
   }
@@ -590,30 +814,392 @@ async function preflightInstallPlan(plan) {
     schema: "agentx-install-preflight-v1",
     ok: true,
     install_id: plan.install_id,
-    files: prepared.map(({ file, existing }) => ({ path: file.path, action: existing === null ? "create" : "unchanged" })),
-    side_effects: [],
+    files: prepared.map(({ file, existing }) => ({ path: file.path, action: existing === null ? "create" : "unchanged", sha256: file.sha256 })),
+    side_effects: [...(plan.side_effects || [])],
+    excluded_side_effects: [...(plan.excluded_side_effects || [])],
+    transaction: { atomic_apply: true, rollback_on_failure: true },
+  };
+}
+
+async function pathStatus(fsImpl, target) {
+  try { return await fsImpl.lstat(target); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function ensureInstallDirectory(root, target, fsImpl, createdDirectories) {
+  const relative = path.relative(root, target);
+  if (relative === "" || relative === ".") return;
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw installError("UNSAFE_INSTALL_PATH", "Installation directory escaped the project root.");
+  }
+  let current = root;
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    const stat = await pathStatus(fsImpl, current);
+    if (stat) {
+      if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw installError("UNSAFE_INSTALL_DIRECTORY", `Refusing to traverse a non-directory or symlink: ${path.relative(root, current)}`);
+      }
+      continue;
+    }
+    await fsImpl.mkdir(current, { mode: 0o755 });
+    await syncDirectory(path.dirname(current), fsImpl);
+    createdDirectories.push(current);
+  }
+}
+
+function recordHash(record, field) {
+  const unsigned = { ...record };
+  delete unsigned[field];
+  return hashText(stableJson(unsigned));
+}
+
+function sealRecord(record, field) {
+  const sealed = { ...record };
+  sealed[field] = recordHash(sealed, field);
+  return sealed;
+}
+
+function verifyRecord(record, schema, field) {
+  return Boolean(
+    record
+    && record.schema === schema
+    && typeof record[field] === "string"
+    && record[field] === recordHash(record, field)
+  );
+}
+
+function transactionPaths(root) {
+  return {
+    directory: path.join(root, TRANSACTION_DIR),
+    journal: path.join(root, TRANSACTION_JOURNAL),
+    lock: path.join(root, TRANSACTION_LOCK),
+    marker: path.join(root, COMMIT_MARKER),
+  };
+}
+
+async function removeDurable(target, options = { force: true }, fsImpl = fs) {
+  const stat = await pathStatus(fsImpl, target);
+  if (!stat) return false;
+  await fsImpl.rm(target, options);
+  await syncDirectory(path.dirname(target), fsImpl);
+  return true;
+}
+
+async function fileHash(target, fsImpl = fs) {
+  try { return hashText(await fsImpl.readFile(target)); }
+  catch (error) { if (error.code === "ENOENT") return ""; throw error; }
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error && error.code === "EPERM"; }
+}
+
+async function acquireTransactionLock(root, fsImpl = fs) {
+  const paths = transactionPaths(root);
+  await ensureInstallDirectory(root, paths.directory, fsImpl, []);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let handle;
+    try {
+      handle = await fsImpl.open(paths.lock, "wx", 0o600);
+      await handle.writeFile(JSON.stringify({ pid: process.pid, host: os.hostname(), created_at: Date.now() }) + "\n", "utf8");
+      await handle.sync();
+      await handle.close();
+      await syncDirectory(paths.directory, fsImpl);
+      return async () => {
+        await removeDurable(paths.lock, { force: true }, fsImpl).catch(() => {});
+        await fsImpl.rmdir(paths.directory).catch((error) => {
+          if (!error || !["ENOENT", "ENOTEMPTY"].includes(error.code)) throw error;
+        });
+      };
+    } catch (error) {
+      if (handle) await handle.close().catch(() => {});
+      if (!error || error.code !== "EEXIST" || attempt > 0) throw error;
+      const existing = await readJsonWith(fsImpl, paths.lock).catch(() => null);
+      const sameHost = existing && existing.host === os.hostname();
+      const recent = existing && Number.isFinite(existing.created_at) && Date.now() - existing.created_at < 60 * 60 * 1000;
+      if ((sameHost && processIsAlive(existing.pid)) || (!sameHost && recent)) {
+        throw installError("INSTALL_TRANSACTION_BUSY", "Another installer transaction is active for this project.");
+      }
+      await removeDurable(paths.lock, { force: true }, fsImpl);
+    }
+  }
+  throw installError("INSTALL_TRANSACTION_BUSY", "Unable to acquire the installer transaction lock.");
+}
+
+async function writeJournal(root, journal, fsImpl = fs) {
+  const sealed = sealRecord(journal, "journal_hash");
+  await writeAtomic(transactionPaths(root).journal, JSON.stringify(sealed, null, 2) + "\n", "private", fsImpl);
+  return sealed;
+}
+
+async function readJournal(root, fsImpl = fs) {
+  const journal = await readJsonWith(fsImpl, transactionPaths(root).journal);
+  if (!journal) return null;
+  if (!verifyRecord(journal, TRANSACTION_SCHEMA, "journal_hash")) {
+    throw installError("INSTALL_TRANSACTION_JOURNAL_INVALID", "Installer transaction journal failed integrity validation.");
+  }
+  return journal;
+}
+
+async function writeCommitMarker(root, journal, fsImpl = fs) {
+  const marker = sealRecord({
+    schema: COMMIT_SCHEMA,
+    transaction_id: journal.transaction_id,
+    install_id: journal.install_id,
+    files: journal.files.map(({ path: relative, sha256 }) => ({ path: relative, sha256 })),
+    committed_at: Date.now(),
+  }, "marker_hash");
+  await writeAtomic(transactionPaths(root).marker, JSON.stringify(marker, null, 2) + "\n", "private", fsImpl);
+  return marker;
+}
+
+async function committedMarkerMatches(root, journal, fsImpl = fs) {
+  const marker = await readJsonWith(fsImpl, transactionPaths(root).marker);
+  if (!verifyRecord(marker, COMMIT_SCHEMA, "marker_hash")) return false;
+  if (marker.transaction_id !== journal.transaction_id || marker.install_id !== journal.install_id) return false;
+  if (stableJson(marker.files) !== stableJson(journal.files.map(({ path: relative, sha256 }) => ({ path: relative, sha256 })))) return false;
+  for (const item of marker.files) {
+    if (await fileHash(path.join(root, item.path), fsImpl) !== item.sha256) return false;
+  }
+  return true;
+}
+
+async function cleanupJournal(root, journal, fsImpl = fs) {
+  const paths = transactionPaths(root);
+  if (journal && journal.staging_path) {
+    await removeDurable(path.join(root, journal.staging_path), { recursive: true, force: true }, fsImpl).catch(() => {});
+  }
+  await removeDurable(paths.journal, { force: true }, fsImpl).catch(() => {});
+}
+
+function safeManagedPath(root, relative) {
+  const allowedWorkflow = relative === ".github/workflows/agent-id-sync.yml";
+  if (
+    typeof relative !== "string"
+    || path.isAbsolute(relative)
+    || (!relative.startsWith(`${MANAGED_DIR}/`) && !allowedWorkflow)
+    || relative.split(/[\\/]+/).includes("..")
+  ) {
+    throw installError("UNSAFE_INSTALL_PATH", "Installer transaction contains an unsafe managed path.");
+  }
+  const target = path.resolve(root, relative);
+  if (target !== root && !target.startsWith(root + path.sep)) {
+    throw installError("UNSAFE_INSTALL_PATH", "Installer transaction path escaped the project root.");
+  }
+  return target;
+}
+
+function retainedState(state, preserved) {
+  const retained = {
+    ...state,
+    status: "uninstall_blocked_modified_files",
+    managed_paths: preserved.map((item) => item.path),
+    managed_files: state.managed_files.filter((item) => preserved.some((entry) => entry.path === item.path)),
+  };
+  delete retained.state_hash;
+  retained.state_hash = hashText(stableJson(retained));
+  return retained;
+}
+
+async function finishUninstallJournal(root, journal, fsImpl = fs) {
+  const removed = [];
+  const preserved = [];
+  const missing = [];
+  for (const managed of journal.files) {
+    const relative = managed.path;
+    const target = safeManagedPath(root, relative);
+    const stat = await pathStatus(fsImpl, target);
+    if (!stat) {
+      missing.push(relative);
+      continue;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      preserved.push({ path: relative, reason: "not_regular_file" });
+      continue;
+    }
+    if (await fileHash(target, fsImpl) !== String(managed.sha256 || "")) {
+      preserved.push({ path: relative, reason: "content_modified" });
+      continue;
+    }
+    await removeDurable(target, { force: true }, fsImpl);
+    removed.push(relative);
+  }
+  const statePath = path.join(root, MANAGED_DIR, "install-state.json");
+  if (preserved.length) {
+    const retained = retainedState(journal.state_snapshot, preserved);
+    await writeAtomic(statePath, JSON.stringify(retained, null, 2) + "\n", "private", fsImpl);
+  } else {
+    await removeDurable(statePath, { force: true }, fsImpl);
+  }
+  await removeDurable(transactionPaths(root).marker, { force: true }, fsImpl).catch(() => {});
+  await cleanupJournal(root, journal, fsImpl);
+  return {
+    status: "uninstalled",
+    complete: preserved.length === 0,
+    removed_files: removed,
+    preserved_files: preserved,
+    missing_files: missing,
   };
 }
 
-async function applyInstallPlan(plan, { approved = false } = {}) {
+async function recoverInstallTransaction(root, fsImpl = fs) {
+  const journal = await readJournal(root, fsImpl);
+  if (!journal) return null;
+  if (journal.operation === "uninstall") {
+    return finishUninstallJournal(root, journal, fsImpl);
+  }
+  if (journal.operation !== "install" || !Array.isArray(journal.files)) {
+    throw installError("INSTALL_TRANSACTION_JOURNAL_INVALID", "Installer transaction operation is invalid.");
+  }
+  if (await committedMarkerMatches(root, journal, fsImpl)) {
+    await cleanupJournal(root, journal, fsImpl);
+    return { status: "committed", transaction_id: journal.transaction_id };
+  }
+  const removed = [];
+  const preserved = [];
+  for (const item of journal.files.filter((entry) => entry.action === "create")) {
+    const target = safeManagedPath(root, item.path);
+    const currentHash = await fileHash(target, fsImpl);
+    if (!currentHash) continue;
+    if (currentHash !== item.sha256) {
+      preserved.push(item.path);
+      continue;
+    }
+    await removeDurable(target, { force: true }, fsImpl);
+    removed.push(item.path);
+  }
+  await removeDurable(transactionPaths(root).marker, { force: true }, fsImpl).catch(() => {});
+  if (preserved.length) {
+    return { status: "rollback_incomplete", transaction_id: journal.transaction_id, removed_paths: removed, preserved_paths: preserved };
+  }
+  await cleanupJournal(root, journal, fsImpl);
+  return { status: "rolled_back", transaction_id: journal.transaction_id, removed_paths: removed, preserved_paths: [] };
+}
+
+async function applyInstallPlan(plan, { approved = false, fsImpl = fs } = {}) {
   if (approved !== true) throw installError("INSTALL_APPROVAL_REQUIRED", "Installation requires explicit approved=true.");
-  const { state, prepared } = await inspectInstallPlan(plan);
-  const result = { schema: "agentx-install-receipt-v1", install_id: plan.install_id, changed: false, files: [], state: state.status };
-  for (const { file, target, content, existing } of prepared) {
-    if (existing === null) {
-      await writeAtomic(target, content, file.mode);
-      result.changed = true;
+  const root = validatePlan(plan);
+  const releaseLock = await acquireTransactionLock(root, fsImpl);
+  let journal = null;
+  let result = null;
+  try {
+    const recovery = await recoverInstallTransaction(root, fsImpl);
+    if (recovery && recovery.status === "rollback_incomplete") {
+      throw installError("INSTALL_RECOVERY_REQUIRED", "A previous installation could not be safely rolled back.");
+    }
+    const { state, prepared } = await inspectInstallPlan(plan, { fsImpl });
+    const transactionId = `itx_${crypto.randomUUID().replace(/-/g, "")}`;
+    const stagingRelative = `${TRANSACTION_DIR}/${transactionId}`;
+    const stagingRoot = path.join(root, stagingRelative);
+    result = {
+      schema: "agentx-install-receipt-v1",
+      install_id: plan.install_id,
+      transaction_id: transactionId,
+      changed: prepared.some((item) => item.existing === null),
+      files: prepared.map(({ file, existing }) => ({ path: file.path, changed: existing === null, sha256: file.sha256 })),
+      state: state.status,
+      atomic_apply: true,
+      rollback_on_failure: true,
+      durability: "transaction_journal_commit_marker_fsync",
+    };
+    if (!result.changed) return result;
+
+    journal = await writeJournal(root, {
+      schema: TRANSACTION_SCHEMA,
+      transaction_id: transactionId,
+      operation: "install",
+      phase: "staging",
+      install_id: plan.install_id,
+      staging_path: stagingRelative,
+      files: prepared.map(({ file, existing }, index) => ({
+        path: file.path,
+        sha256: file.sha256,
+        mode: file.mode,
+        action: existing === null ? "create" : "unchanged",
+        stage_name: `${String(index).padStart(3, "0")}.stage`,
+      })),
+      applied_paths: [],
+      started_at: Date.now(),
+    }, fsImpl);
+    await ensureInstallDirectory(root, stagingRoot, fsImpl, []);
+    for (let index = 0; index < prepared.length; index += 1) {
+      const item = prepared[index];
+      if (item.existing !== null) continue;
+      const stagePath = path.join(stagingRoot, `${String(index).padStart(3, "0")}.stage`);
+      await writeAtomic(stagePath, item.content, item.file.mode, fsImpl);
+      const stagedContent = await fsImpl.readFile(stagePath, "utf8");
+      if (hashText(stagedContent) !== item.file.sha256) {
+        throw installError("INSTALL_STAGE_HASH_MISMATCH", `Staged content hash mismatch for ${item.file.path}.`);
+      }
+    }
+    journal = await writeJournal(root, { ...journal, phase: "prepared" }, fsImpl);
+    journal = await writeJournal(root, { ...journal, phase: "committing" }, fsImpl);
+    for (let index = 0; index < prepared.length; index += 1) {
+      const item = prepared[index];
+      if (item.existing !== null) continue;
+      const stagePath = path.join(stagingRoot, `${String(index).padStart(3, "0")}.stage`);
+      await ensureInstallDirectory(root, path.dirname(item.target), fsImpl, []);
+      if (await pathStatus(fsImpl, item.target)) {
+        throw installError("INSTALL_CONFLICT", `Refusing to overwrite a file created during installation: ${item.file.path}`);
+      }
+      await fsImpl.rename(stagePath, item.target);
+      await fsImpl.chmod(item.target, item.file.mode === "private" ? 0o600 : 0o644);
+      await syncDirectory(path.dirname(item.target), fsImpl);
+      journal = await writeJournal(root, {
+        ...journal,
+        applied_paths: [...journal.applied_paths, item.file.path],
+      }, fsImpl);
+    }
+    for (const { file, target } of prepared) {
+      if (await fileHash(target, fsImpl) !== file.sha256) {
+        throw installError("INSTALL_COMMIT_HASH_MISMATCH", `Committed content hash mismatch for ${file.path}.`);
+      }
     }
-    result.files.push({ path: file.path, changed: existing === null, sha256: file.sha256 });
+    await writeCommitMarker(root, journal, fsImpl);
+    await cleanupJournal(root, journal, fsImpl);
+    return result;
+  } catch (cause) {
+    if (["INSTALL_RECOVERY_REQUIRED", "INSTALL_TRANSACTION_JOURNAL_INVALID"].includes(cause.code)) throw cause;
+    if (!journal) throw cause;
+    let rollback = { status: "rolled_back", removed_paths: [], preserved_paths: [] };
+    try { rollback = await recoverInstallTransaction(root, fsImpl) || rollback; }
+    catch (error) {
+      rollback = { status: "rollback_incomplete", removed_paths: [], preserved_paths: [], error: error.code || "ROLLBACK_FAILED" };
+    }
+    if (rollback.status === "committed" && result) {
+      return { ...result, recovered_after_commit: true };
+    }
+    const error = installError("INSTALL_TRANSACTION_FAILED", `Installation transaction failed: ${cause.code || cause.message || "unknown error"}`);
+    error.cause_code = cause.code || "INSTALL_COMMIT_FAILED";
+    error.rollback_receipt = {
+      schema: "agentx-install-failure-rollback-receipt-v1",
+      transaction_id: journal ? journal.transaction_id : "",
+      status: rollback.status,
+      removed_paths: rollback.removed_paths || [],
+      preserved_paths: rollback.preserved_paths || [],
+    };
+    throw error;
+  } finally {
+    await releaseLock();
   }
-  return result;
 }
 
 async function resumeInstall(projectRoot = process.cwd()) {
   const root = normalizeProjectRoot(projectRoot);
+  const releaseLock = await acquireTransactionLock(root, fs);
+  let recovery = null;
+  try { recovery = await recoverInstallTransaction(root, fs); }
+  finally { await releaseLock(); }
+  if (recovery && recovery.status === "rollback_incomplete") {
+    return { schema: "agentx-install-status-v1", state: "recovery_required", project_root: root, recovery, next_steps: ["review_preserved_transaction_files"] };
+  }
   const statePath = path.join(root, MANAGED_DIR, "install-state.json");
   const state = await readJson(statePath);
-  if (!state || state.schema !== STATE_SCHEMA) return { schema: "agentx-install-status-v1", state: "not_installed", project_root: root, next_steps: ["build_install_plan"] };
+  if (!state || state.schema !== STATE_SCHEMA) return { schema: "agentx-install-status-v1", state: "not_installed", project_root: root, recovery, next_steps: ["build_install_plan"] };
+  if (!verifyInstallState(state)) throw installError("INSTALL_STATE_INTEGRITY_INVALID", "Installed state failed integrity validation.");
   return {
     schema: "agentx-install-status-v1",
     state: state.status || "unknown",
@@ -621,6 +1207,7 @@ async function resumeInstall(projectRoot = process.cwd()) {
     site_url: state.site_url || "",
     install_id: state.install_id || "",
     project_root: root,
+    recovery,
     next_steps: state.framework === "static"
       ? (state.verification_status === "verified"
           ? ["store_SITE_AGENT_KEY_as_GitHub_Actions_secret", "run_customer_owned_sync_workflow"]
@@ -683,31 +1270,77 @@ async function writeEnterpriseEnrollmentState(projectRoot, state) {
   return allowed;
 }
 
-async function uninstallInstall(projectRoot = process.cwd(), { approved = false } = {}) {
+async function uninstallInstall(projectRoot = process.cwd(), { approved = false, fsImpl = fs } = {}) {
   if (approved !== true) throw installError("INSTALL_APPROVAL_REQUIRED", "Uninstall requires explicit approved=true.");
   const root = normalizeProjectRoot(projectRoot);
-  const statePath = path.join(root, MANAGED_DIR, "install-state.json");
-  const state = await readJson(statePath);
-  if (!state || state.schema !== STATE_SCHEMA) return { schema: "agentx-uninstall-receipt-v1", removed: false, files: [] };
-  const files = Array.isArray(state.managed_paths) ? state.managed_paths : [];
-  const removed = [];
-  for (const relative of files) {
-    const allowedWorkflow = relative === ".github/workflows/agent-id-sync.yml";
-    if (typeof relative !== "string" || path.isAbsolute(relative) || (!relative.startsWith(`${MANAGED_DIR}/`) && !allowedWorkflow) || relative.split(/[\\/]+/).includes("..")) throw installError("UNSAFE_INSTALL_PATH", "Refusing to remove a file outside managed Agent ID paths.");
-    const target = path.resolve(root, relative);
-    await fs.rm(target, { force: true });
-    removed.push(relative);
+  const releaseLock = await acquireTransactionLock(root, fsImpl);
+  try {
+    const priorRecovery = await recoverInstallTransaction(root, fsImpl);
+    const statePath = path.join(root, MANAGED_DIR, "install-state.json");
+    const state = await readJsonWith(fsImpl, statePath);
+    if (!state || state.schema !== STATE_SCHEMA) {
+      return {
+        schema: "agentx-uninstall-receipt-v1",
+        removed: Boolean(priorRecovery && priorRecovery.status === "uninstalled"),
+        complete: true,
+        files: priorRecovery ? priorRecovery.removed_files || [] : [],
+        recovery: priorRecovery,
+      };
+    }
+    if (!verifyInstallState(state)) {
+      throw installError("INSTALL_STATE_INTEGRITY_INVALID", "Refusing to uninstall because the managed state hash is missing or invalid.");
+    }
+    const files = Array.isArray(state.managed_files) ? state.managed_files : [];
+    for (const managed of files) safeManagedPath(root, managed && managed.path);
+    const transactionId = `utx_${crypto.randomUUID().replace(/-/g, "")}`;
+    const journal = await writeJournal(root, {
+      schema: TRANSACTION_SCHEMA,
+      transaction_id: transactionId,
+      operation: "uninstall",
+      phase: "deleting",
+      install_id: state.install_id || "",
+      files: files.map((item) => ({ path: item.path, sha256: item.sha256 })),
+      state_snapshot: state,
+      approved: true,
+      started_at: Date.now(),
+    }, fsImpl);
+    let completed;
+    try {
+      completed = await finishUninstallJournal(root, journal, fsImpl);
+    } catch (cause) {
+      const error = installError("UNINSTALL_TRANSACTION_FAILED", `Uninstall transaction interrupted: ${cause.code || cause.message || "unknown error"}`);
+      error.cause_code = cause.code || "UNINSTALL_FAILED";
+      error.transaction_id = transactionId;
+      error.recovery = "resumeInstall_or_retry_uninstall";
+      throw error;
+    }
+    return {
+      schema: "agentx-uninstall-receipt-v1",
+      removed: true,
+      complete: completed.complete,
+      files: completed.removed_files,
+      removed_files: completed.removed_files,
+      preserved_files: completed.preserved_files,
+      missing_files: completed.missing_files,
+      retryable_after_review: completed.preserved_files.length > 0,
+      transaction_id: transactionId,
+      durability: "transaction_journal_fsync",
+      install_id: state.install_id || "",
+    };
+  } finally {
+    await releaseLock();
   }
-  await fs.rm(path.join(root, MANAGED_DIR), { recursive: false, force: true }).catch(() => {});
-  return { schema: "agentx-uninstall-receipt-v1", removed: true, files: removed, install_id: state.install_id || "" };
 }
 
 module.exports = {
   INSTALL_SCHEMA,
   STATE_SCHEMA,
+  INSTALL_MODULES,
+  normalizeInstallSelection,
   buildInstallPlan,
   preflightInstallPlan,
   detectProject,
+  inspectAgentIdOpportunities,
   applyInstallPlan,
   resumeInstall,
   uninstallInstall,