@twin3-ai/agent-id 0.1.0 → 0.3.0

package/bin/agent-id.js

@@ -3,16 +3,29 @@ const { configuredEndpoint, TRUSTED_ISSUER_KEY_SHA256 } = require("../runtime-co
 const endpoint = configuredEndpoint();
 const fs = require("fs");
 const path = require("path");
-const { buildInstallPlan, resumeInstall, uninstallInstall, enterpriseInstallStatus, prepareEnterpriseSecretDirectory, writeEnterpriseBootstrapCredential, readEnterpriseBootstrapCredential, replaceEnterpriseBootstrapCredential, removeEnterpriseBootstrapCredential, writeEnterpriseEnrollmentState } = require("../installer.js");
+const { buildInstallPlan, preflightInstallPlan, applyInstallPlan, resumeInstall, uninstallInstall, enterpriseInstallStatus, prepareEnterpriseSecretDirectory, writeEnterpriseBootstrapCredential, readEnterpriseBootstrapCredential, replaceEnterpriseBootstrapCredential, removeEnterpriseBootstrapCredential, writeEnterpriseEnrollmentState } = require("../installer.js");
 const { buildRepositoryPatch, applyRepositoryPatch, rollbackRepositoryPatch } = require("../repository-connector.js");
+const { createRepositoryConnector } = require("../repository-connector.js");
 const { generateSiteAgentIdentity, createEnterpriseSession } = require("../enterprise-identity.js");
-const { buildWellKnownProofDocument, resolveProofTarget, writeWellKnownProofDocument } = require("../domain-proof.js");
+const { buildWellKnownProofDocument, buildEnterpriseIdentityDocument, verifyEnterpriseIdentityDocument, resolveProofTarget, writeWellKnownProofDocument, writeEnterpriseIdentityDocument } = require("../domain-proof.js");
 const { initializeLocalPolicy, loadLocalPolicy, approvePolicyRule } = require("../local-policy.js");
+const { createTaskExecutor } = require("../task-executor.js");
+const { createOptimizationLoop } = require("../optimization-loop.js");
+const crypto = require("node:crypto");
 const { verifyPortableBundle } = require("../trust-verifier.js");
 const { verifyReleaseManifest } = require("../release-verifier.js");
 const { runProductionPreflight } = require("../production-preflight.js");
 const packageMetadata = require("../package.json");
 
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function pinnedCliCommand(command, args = []) {
+  const executable = `npx --yes --package=@twin3-ai/agent-id@${packageMetadata.version} agent-id`;
+  return [executable, command, ...args.map(shellQuote)].join(" ");
+}
+
 async function post(path, body, headers = {}) {
   const res = await fetch(endpoint + path, {
     method: "POST",
@@ -49,6 +62,11 @@ function readFlagValue(argv, flag) {
   return idx >= 0 ? argv[idx + 1] : undefined;
 }
 
+function readCsvFlag(argv, flag) {
+  const value = readFlagValue(argv, flag);
+  return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : undefined;
+}
+
 async function enterpriseSessionForProject(projectRoot) {
   const root = path.resolve(projectRoot || process.cwd());
   const state = JSON.parse(fs.readFileSync(path.join(root, ".agent-id", "enterprise-state.json"), "utf8"));
@@ -62,7 +80,17 @@ async function enterpriseSessionForProject(projectRoot) {
     credential: existing.credential,
     identity
   });
-  return { root, state, session };
+  return { root, state, session, identity, credential: existing.credential };
+}
+
+async function trustedIssuerPublicKey() {
+  const response = await fetch(endpoint + "/.well-known/agentx-issuer-key.json");
+  if (!response.ok) throw new Error("enterprise issuer key unavailable");
+  const descriptor = await response.json();
+  const publicKey = String(descriptor.public_key_pem || "");
+  const actual = `sha256:${crypto.createHash("sha256").update(publicKey).digest("hex")}`;
+  if (!publicKey || actual !== TRUSTED_ISSUER_KEY_SHA256) throw new Error("enterprise issuer key pin mismatch");
+  return publicKey;
 }
 
 function printManagedResult(value) {
@@ -106,7 +134,8 @@ function printProductionPreflight(value) {
     `API domain: ${checks.stable_api_origin ? "verified" : "not ready"}`,
     `Release signature: ${checks.release_signature ? "verified" : "not verified"}`,
     `npm package: ${checks.registry_integrity ? "verified" : "not ready"}`,
-    `Agent surfaces: ${checks.health_endpoint && checks.agent_card ? "verified" : "not ready"}`,
+    `Production binding: ${checks.production_release_binding ? "verified" : "not ready"}`,
+    `Agent surfaces: ${checks.health_endpoint && checks.agent_card && checks.install_manifest && checks.openapi ? "verified" : "not ready"}`,
     value.ok ? `Install: ${value.install_template}` : `Blockers: ${(value.blockers || []).join(", ") || "unknown"}`,
     "Use --json for the complete machine-readable result.",
   ];
@@ -149,86 +178,170 @@ async function releaseCheck({ printResult = true, setExitCode = true } = {}) {
   return result;
 }
 
-async function createEnterpriseEnrollment({ siteUrl, projectRoot, publicRoot, environment = "production", method = "well_known", applyProof = false }) {
-  const secretPaths = await prepareEnterpriseSecretDirectory(projectRoot);
-  const identity = generateSiteAgentIdentity({ keyPath: secretPaths.key_path });
-  const response = await post("/api/site_agents/v1/challenges", {
-    url: siteUrl,
-    public_key: identity.public_key_pem,
-    environment,
-    method,
+function enrollmentArtifactSnapshot(projectRoot, publicRoot) {
+  const project = path.resolve(projectRoot);
+  const proof = resolveProofTarget({ projectRoot: project, publicRoot }).target;
+  const files = [
+    path.join(project, ".agent-id", "secrets", "enterprise-ed25519.pem"),
+    path.join(project, ".agent-id", "secrets", ".gitignore"),
+    path.join(project, ".agent-id", "enterprise-state.json"),
+    proof,
+  ].map((target) => {
+    if (!fs.existsSync(target)) return { target, existed: false };
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`UNSAFE_ENROLLMENT_ARTIFACT: ${target}`);
+    return { target, existed: true, content: fs.readFileSync(target), mode: stat.mode & 0o777 };
   });
-  const challenge = response && response.challenge;
-  if (!challenge || !challenge.challenge_id) {
-    return { ok: false, error: response && response.error || "enterprise_enrollment_failed" };
-  }
-  const domainProof = method === "well_known" ? buildWellKnownProofDocument(challenge) : null;
-  await writeEnterpriseEnrollmentState(projectRoot, {
-    status: "challenge_pending",
-    site_url: siteUrl,
-    environment,
-    agent_id: challenge.agent_id,
-    challenge_id: challenge.challenge_id,
-    public_key_thumbprint: identity.public_key_thumbprint,
-    domain_proof: domainProof,
+  const directoryPaths = [
+    path.join(project, ".agent-id"),
+    path.join(project, ".agent-id", "secrets"),
+    path.dirname(proof),
+  ];
+  const directories = [...new Set(directoryPaths)].map((target) => {
+    if (!fs.existsSync(target)) return { target, existed: false };
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`UNSAFE_ENROLLMENT_DIRECTORY: ${target}`);
+    return { target, existed: true, mode: stat.mode & 0o777 };
   });
-  let proofReceipt = null;
-  if (applyProof) {
-    if (method !== "well_known") throw new Error("one-line apply currently requires --method well_known");
-    proofReceipt = await writeWellKnownProofDocument({
-      challenge: domainProof,
-      projectRoot,
-      publicRoot,
-      approved: true,
-    });
+  return { project, files, directories };
+}
+
+function restoreEnrollmentArtifacts(snapshot) {
+  const receipt = {
+    schema: "agentx-enrollment-local-rollback-receipt-v1",
+    status: "rolled_back",
+    restored_paths: [],
+    removed_paths: [],
+    errors: [],
+  };
+  for (const item of [...snapshot.files].reverse()) {
+    try {
+      if (!item.existed) {
+        fs.rmSync(item.target, { force: true });
+        receipt.removed_paths.push(path.relative(snapshot.project, item.target));
+        continue;
+      }
+      fs.mkdirSync(path.dirname(item.target), { recursive: true });
+      const temporary = `${item.target}.${process.pid}.${crypto.randomUUID()}.restore`;
+      try {
+        fs.writeFileSync(temporary, item.content, { mode: item.mode, flag: "wx" });
+        fs.renameSync(temporary, item.target);
+        fs.chmodSync(item.target, item.mode);
+      } finally {
+        fs.rmSync(temporary, { force: true });
+      }
+      receipt.restored_paths.push(path.relative(snapshot.project, item.target));
+    } catch (error) {
+      receipt.errors.push({ path: path.relative(snapshot.project, item.target), code: error.code || "RESTORE_FAILED" });
+    }
   }
-  return {
-    ok: true,
-    schema: "agentx-enterprise-enrollment-v1",
-    status: "challenge_pending",
-    challenge,
-    domain_proof: domainProof,
-    proof_receipt: proofReceipt,
-    identity: {
-      algorithm: identity.algorithm,
-      public_key_pem: identity.public_key_pem,
+  for (const item of [...snapshot.directories].reverse()) {
+    try {
+      if (item.existed) fs.chmodSync(item.target, item.mode);
+      else fs.rmdirSync(item.target);
+    } catch (error) {
+      if (!item.existed && ["ENOENT", "ENOTEMPTY"].includes(error.code)) continue;
+      receipt.errors.push({ path: path.relative(snapshot.project, item.target), code: error.code || "DIRECTORY_RESTORE_FAILED" });
+    }
+  }
+  if (receipt.errors.length) receipt.status = "rollback_incomplete";
+  return receipt;
+}
+
+async function createEnterpriseEnrollment({ siteUrl, projectRoot, publicRoot, environment = "production", method = "well_known", applyProof = false }) {
+  const snapshot = enrollmentArtifactSnapshot(projectRoot, publicRoot);
+  try {
+    const secretPaths = await prepareEnterpriseSecretDirectory(projectRoot);
+    const identity = generateSiteAgentIdentity({ keyPath: secretPaths.key_path });
+    const response = await post("/api/site_agents/v1/challenges", {
+      url: siteUrl,
+      public_key: identity.public_key_pem,
+      environment,
+      method,
+    });
+    const challenge = response && response.challenge;
+    if (!challenge || !challenge.challenge_id) throw new Error(response && response.error || "enterprise_enrollment_failed");
+    const domainProof = method === "well_known" ? buildWellKnownProofDocument(challenge) : null;
+    await writeEnterpriseEnrollmentState(projectRoot, {
+      status: "challenge_pending",
+      site_url: siteUrl,
+      environment,
+      agent_id: challenge.agent_id,
+      challenge_id: challenge.challenge_id,
       public_key_thumbprint: identity.public_key_thumbprint,
-      private_key_persisted_locally: true,
-    },
-    next_commands: method === "well_known" ? (applyProof ? [
-      `deploy ${proofReceipt.relative_path}, then run: agent-id enterprise-domain-verify --project-root ${projectRoot}`,
-    ] : [
-      `agent-id enterprise-domain-proof --project-root ${projectRoot} --public-root <public-root>`,
-      `agent-id enterprise-domain-proof --project-root ${projectRoot} --public-root <public-root> --apply`,
-      `agent-id enterprise-domain-verify --project-root ${projectRoot}`,
-    ]) : ["publish_domain_proof_then_verify_with_agent_id"],
-    non_claims: [
-      "does_not_issue_shared_site_agent_key",
-      "does_not_persist_access_token",
-      "does_not_grant_mutation_authority",
-      "domain_verification_still_required",
-    ],
-  };
+      domain_proof: domainProof,
+    });
+    let proofReceipt = null;
+    if (applyProof) {
+      if (method !== "well_known") throw new Error("one-line apply currently requires --method well_known");
+      proofReceipt = await writeWellKnownProofDocument({
+        challenge: domainProof,
+        projectRoot,
+        publicRoot,
+        approved: true,
+      });
+    }
+    return {
+      ok: true,
+      schema: "agentx-enterprise-enrollment-v1",
+      status: "challenge_pending",
+      challenge,
+      domain_proof: domainProof,
+      proof_receipt: proofReceipt,
+      identity: {
+        algorithm: identity.algorithm,
+        public_key_pem: identity.public_key_pem,
+        public_key_thumbprint: identity.public_key_thumbprint,
+        private_key_persisted_locally: true,
+      },
+      next_commands: method === "well_known" ? (applyProof ? [
+        pinnedCliCommand("enterprise-domain-verify", ["--project-root", projectRoot]),
+      ] : [
+        pinnedCliCommand("enterprise-domain-proof", ["--project-root", projectRoot, "--public-root", publicRoot]),
+        pinnedCliCommand("enterprise-domain-proof", ["--project-root", projectRoot, "--public-root", publicRoot, "--apply"]),
+        pinnedCliCommand("enterprise-domain-verify", ["--project-root", projectRoot]),
+      ]) : [],
+      next_actions: method === "well_known" ? ["deploy_domain_proof", "verify_domain"] : ["publish_domain_proof", "verify_domain"],
+      non_claims: [
+        "does_not_issue_shared_site_agent_key",
+        "does_not_persist_access_token",
+        "does_not_grant_mutation_authority",
+        "domain_verification_still_required",
+      ],
+    };
+  } catch (error) {
+    error.enrollment_rollback_receipt = restoreEnrollmentArtifacts(snapshot);
+    throw error;
+  }
 }
 
 function printSignedInstallResult(value) {
   if (process.argv.includes("--json")) return print(value);
   const plan = value.plan || {};
   const enrollment = value.enrollment || {};
+  const executableCommand = (enrollment.next_commands || [])[0];
   const lines = value.dry_run ? [
     "Agent ID signed installation plan",
     `Site: ${plan.site_url || "unknown"}`,
     `Framework: ${plan.framework || "unknown"}`,
     "Identity: Ed25519, domain-bound",
     "No files changed",
-    `Next: ${value.next_command}`,
+    "Copy and run:",
+    value.next_command,
   ] : [
     "Agent ID signed installation started",
     `Site: ${plan.site_url || "unknown"}`,
     "Signed identity: created",
     `Domain proof: ${enrollment.proof_receipt?.relative_path || "pending"}`,
-    `Next: ${(enrollment.next_commands || ["deploy the domain proof"])[0]}`,
   ];
+  if (!value.dry_run) {
+    if (executableCommand) {
+      lines.push(`Deploy ${enrollment.proof_receipt?.relative_path || "the domain proof"}, then run:`);
+      lines.push(executableCommand);
+    } else {
+      lines.push("Next action: publish the domain proof, then verify the domain with Agent ID.");
+    }
+  }
   lines.push("Use --json for the complete machine-readable result.");
   console.log(lines.join("\n"));
 }
@@ -1348,22 +1461,28 @@ async function runCli(argv) {
       "  agent-id job-evaluate <job-id>",
       "  agent-id register <url>",
       "  agent-id install-guide <url>",
-      "  agent-id install <url> [--project-root <dir>] [--public-root <dir>] [--apply]",
+      "  agent-id install <url> [--modules identity,audit,measurement,optimization,automation] [--grant identity_publish,public_read,telemetry_submit,insights_read,ai_files_write] [--project-root <dir>] [--public-root <dir>] [--apply]",
       "  agent-id install-resume [--project-root <dir>]",
       "  agent-id install-uninstall [--project-root <dir>] --approve",
       "  agent-id enterprise-enroll <url> [--environment production|staging] [--method well_known|dns_txt|html_meta] [--project-root <dir>]",
       "  agent-id enterprise-domain-proof [--project-root <dir>] [--public-root <dir>] [--apply]",
       "  agent-id enterprise-domain-verify [--project-root <dir>]",
+      "  agent-id enterprise-identity-publish [--project-root <dir>] [--public-root <dir>] [--apply]",
+      "  agent-id enterprise-identity-verify <agent-id-json-file> [--offline]",
       "  agent-id enterprise-credential-rotate [--project-root <dir>] --approve",
       "  agent-id enterprise-credential-revoke [--project-root <dir>] --reason <reason> --approve",
       "  agent-id enterprise-policy-init [--project-root <dir>]",
       "  agent-id enterprise-policy-approve <rule-json-file> [--project-root <dir>] --approve --approved-by <identity>",
       "  agent-id enterprise-status [--project-root <dir>]",
+      "  agent-id dashboard-login [--project-root <dir>] [--json]",
       "  agent-id enterprise-managed-enable [--project-root <dir>] [--json]",
       "  agent-id enterprise-managed-status [--project-root <dir>] [--json]",
       "  agent-id enterprise-managed-pause [--project-root <dir>] [--json]",
       "  agent-id enterprise-managed-resume [--project-root <dir>] [--json]",
       "  agent-id enterprise-managed-runs [--project-root <dir>] [--limit <1-100>] [--json]",
+      "  agent-id enterprise-task-propose <allowlisted-path> <content-file> [--project-root <dir>] [--idempotency-key <key>] [--json]",
+      "  agent-id enterprise-optimize-once [--project-root <dir>] [--approve-task <task-id>] [--json]",
+      "  agent-id enterprise-rollback-once --task-id <task-id> --project-root <dir> --approve [--json]",
       "  agent-id enterprise-contract",
       "  agent-id repository-patch-plan <root> <changes-json-file>",
       "  agent-id repository-patch-apply <plan-json-file> --approve",
@@ -2499,7 +2618,26 @@ async function runCli(argv) {
   if (cmd === "install") {
     if (!url) throw new Error("install requires a site URL");
     const projectRoot = readFlagValue(argv, "--project-root") || process.cwd();
-    const detectedPlan = await buildInstallPlan({ url, projectRoot, endpoint });
+    const modules = readCsvFlag(argv, "--modules");
+    const grantedPermissions = readCsvFlag(argv, "--grant");
+    const detectedPlan = await buildInstallPlan({ url, projectRoot, endpoint, modules, grantedPermissions });
+    const publicRoot = path.resolve(readFlagValue(argv, "--public-root") || projectRoot);
+    let realProjectRoot;
+    let realPublicRoot;
+    try {
+      realProjectRoot = fs.realpathSync(path.resolve(projectRoot));
+      realPublicRoot = fs.realpathSync(publicRoot);
+    } catch (_error) {
+      throw new Error("INVALID_PUBLIC_ROOT: Project root and public root must already exist.");
+    }
+    const relativePublicRoot = path.relative(realProjectRoot, realPublicRoot);
+    if (relativePublicRoot.startsWith("..") || path.isAbsolute(relativePublicRoot)) {
+      throw new Error("UNSAFE_PUBLIC_ROOT: Public root must remain inside the website project.");
+    }
+    const publicProofPath = path.posix.join(...relativePublicRoot.split(path.sep).filter(Boolean), ".well-known", "agent-id.json");
+    const privateKeyPath = ".agent-id/secrets/enterprise-ed25519.pem";
+    const managedFiles = detectedPlan.files.map(({ path: filePath, mode, sha256 }) => ({ path: filePath, mode, sha256 }));
+    const plannedWrites = [...new Set([privateKeyPath, ".agent-id/enterprise-state.json", publicProofPath, ...managedFiles.map((item) => item.path)])];
     const plan = {
       schema: "agentx-signed-install-plan-v1",
       site_url: detectedPlan.site_url,
@@ -2507,8 +2645,15 @@ async function runCli(argv) {
       project_root: detectedPlan.project_root,
       framework: detectedPlan.framework,
       package_manager: detectedPlan.package_manager,
+      modules: detectedPlan.modules,
+      granted_permissions: detectedPlan.granted_permissions,
       identity_mode: "ed25519_domain_bound",
       approval_required: true,
+      private_key_path: privateKeyPath,
+      private_key_behavior: "created_locally_on_apply_never_uploaded",
+      public_proof_path: publicProofPath,
+      managed_files: managedFiles,
+      planned_writes: plannedWrites,
       side_effects: ["create_customer_private_key", "write_agent_id_state", "write_public_domain_proof"],
       excluded_side_effects: ["package_install", "shared_site_agent_key", "customer_content_change", "deployment", "database_change", "default_branch_push"],
     };
@@ -2517,13 +2662,16 @@ async function runCli(argv) {
         ok: true,
         dry_run: true,
         plan,
-        next_command: `agent-id install ${url} --project-root ${projectRoot} --apply`,
-        non_claims: ["does_not_register_domain", "does_not_create_private_key", "does_not_modify_customer_site"]
+        next_command: pinnedCliCommand("install", [url, "--modules", detectedPlan.modules.join(","), "--grant", detectedPlan.granted_permissions.join(","), "--project-root", projectRoot, "--public-root", publicRoot, "--apply"]),
+        non_claims: ["dry_run_does_not_register_domain", "dry_run_does_not_create_private_key", "dry_run_does_not_write_files"]
       });
     }
-    const publicRoot = path.resolve(readFlagValue(argv, "--public-root") || projectRoot);
+    // All local runtime conflicts must be discovered before an identity key,
+    // server-side challenge, or public proof is created.
+    await preflightInstallPlan(detectedPlan);
     const gate = await releaseCheck({ printResult: false, setExitCode: false });
     if (!gate.ok) throw new Error(`release gate blocked: ${gate.blockers.join(", ")}`);
+    const enrollmentSnapshot = enrollmentArtifactSnapshot(path.resolve(projectRoot), publicRoot);
     const enrollment = await createEnterpriseEnrollment({
       siteUrl: url,
       projectRoot: path.resolve(projectRoot),
@@ -2533,12 +2681,25 @@ async function runCli(argv) {
       applyProof: true,
     });
     if (!enrollment.ok) throw new Error(enrollment.error || "enterprise_enrollment_failed");
+    // Enrollment creates the customer's key and publishes the proof, but the
+    // runtime that polls for work is a separate set of files. Without this the
+    // installer that writes them was never called from the CLI, so nothing was
+    // installed, install-resume always reported not_installed, and
+    // install-uninstall removed nothing because there was no state to find.
+    let receipt;
+    try {
+      receipt = await applyInstallPlan(detectedPlan, { approved: true });
+    } catch (error) {
+      error.enrollment_rollback_receipt = restoreEnrollmentArtifacts(enrollmentSnapshot);
+      throw error;
+    }
     return printSignedInstallResult({
       ok: true,
       dry_run: false,
       plan,
       release: gate,
       enrollment,
+      runtime_install: receipt,
       non_claims: ["domain_verification_still_required", "shared_site_agent_key_not_used", "does_not_modify_customer_content"]
     });
   }
@@ -2572,12 +2733,12 @@ async function runCli(argv) {
         schema: "agentx-domain-proof-plan-v1",
         target,
         document,
-        next_command: `agent-id enterprise-domain-proof --project-root ${projectRoot} --public-root ${publicRoot} --apply`,
+        next_command: pinnedCliCommand("enterprise-domain-proof", ["--project-root", projectRoot, "--public-root", publicRoot, "--apply"]),
         non_claims: ["does_not_verify_domain", "does_not_issue_credentials", "does_not_overwrite_customer_managed_files"]
       });
     }
     const receipt = await writeWellKnownProofDocument({ challenge: state.domain_proof, projectRoot, publicRoot, approved: true });
-    return print({ ok: true, dry_run: false, receipt, next_command: `agent-id enterprise-domain-verify --project-root ${projectRoot}` });
+    return print({ ok: true, dry_run: false, receipt, next_command: pinnedCliCommand("enterprise-domain-verify", ["--project-root", projectRoot]) });
   }
   if (cmd === "enterprise-domain-verify") {
     const projectRoot = path.resolve(readFlagValue(argv, "--project-root") || process.cwd());
@@ -2627,7 +2788,7 @@ async function runCli(argv) {
         credential_path: existing.credential_path,
         private_key_path: existing.key_path,
         secret_storage_required: "move both customer secret files into the customer secret manager before production runtime",
-        next_command: `agent-id enterprise-policy-init --project-root ${projectRoot}`
+        next_command: pinnedCliCommand("enterprise-identity-publish", ["--project-root", projectRoot, "--public-root", projectRoot])
       });
     }
     const response = await post("/api/site_agents/v1/challenges/verify", { challenge_id: state.challenge_id });
@@ -2640,7 +2801,7 @@ async function runCli(argv) {
         response.bootstrap_secret
       );
     } catch (_error) {
-      throw new Error(`enterprise_credential_delivery_failed; request a new single-use challenge with: agent-id enterprise-enroll ${state.site_url} --environment ${state.environment} --method well_known --project-root ${projectRoot}`);
+      throw new Error(`enterprise_credential_delivery_failed; request a new single-use challenge with: ${pinnedCliCommand("enterprise-enroll", [state.site_url, "--environment", state.environment, "--method", "well_known", "--project-root", projectRoot])}`);
     }
     await writeEnterpriseEnrollmentState(projectRoot, {
       ...state,
@@ -2658,7 +2819,82 @@ async function runCli(argv) {
       credential_path: secretReceipt.credential_path,
       private_key_path: path.join(projectRoot, ".agent-id", "secrets", "enterprise-ed25519.pem"),
       secret_storage_required: "move both customer secret files into the customer secret manager before production runtime",
-      next_command: `agent-id enterprise-policy-init --project-root ${projectRoot}`
+      next_command: pinnedCliCommand("enterprise-identity-publish", ["--project-root", projectRoot, "--public-root", projectRoot])
+    });
+  }
+  if (cmd === "enterprise-identity-publish") {
+    const projectRoot = path.resolve(readFlagValue(argv, "--project-root") || process.cwd());
+    const publicRoot = path.resolve(readFlagValue(argv, "--public-root") || projectRoot);
+    const { state, identity, credential } = await enterpriseSessionForProject(projectRoot);
+    const document = buildEnterpriseIdentityDocument({
+      state,
+      credential,
+      identity,
+      serviceOrigin: endpoint,
+    });
+    const verification = verifyEnterpriseIdentityDocument(document);
+    if (!argv.includes("--apply")) {
+      return print({
+        ok: verification.ok,
+        dry_run: true,
+        schema: "agentx-site-identity-publish-plan-v1",
+        document,
+        verification,
+        next_command: pinnedCliCommand("enterprise-identity-publish", ["--project-root", projectRoot, "--public-root", publicRoot, "--apply"]),
+        non_claims: ["does_not_write_without_apply", "does_not_register_erc_8004", "does_not_grant_mutation_authority"],
+      });
+    }
+    const receipt = await writeEnterpriseIdentityDocument({ document, projectRoot, publicRoot, approved: true });
+    return print({
+      ok: true,
+      dry_run: false,
+      schema: "agentx-site-identity-publish-result-v1",
+      receipt,
+      verification,
+      next_actions: [
+        `deploy ${receipt.relative_path}`,
+        `verify ${document.credential_status.status_url}`,
+        `verify ${document.services.passport}`,
+        pinnedCliCommand("enterprise-policy-init", ["--project-root", projectRoot]),
+      ],
+    });
+  }
+  if (cmd === "enterprise-identity-verify") {
+    if (!url || url.startsWith("--")) throw new Error("enterprise-identity-verify requires an Agent identity JSON file");
+    const document = JSON.parse(fs.readFileSync(path.resolve(url), "utf8"));
+    const offline = verifyEnterpriseIdentityDocument(document);
+    if (argv.includes("--offline") || !offline.ok) {
+      const failures = offline.ok ? [...offline.failure_codes, "online_status_not_checked"] : offline.failure_codes;
+      return print({
+        ...offline,
+        ok: false,
+        document_valid: offline.ok,
+        trust_established: false,
+        online_checked: false,
+        failure_codes: [...new Set(failures)],
+      });
+    }
+    const expectedStatus = `${endpoint}/agentx/id/${encodeURIComponent(document.agent_id)}/status.json`;
+    if ((document.credential_status || {}).status_url !== expectedStatus) {
+      return print({ ...offline, ok: false, online_checked: false, failure_codes: [...offline.failure_codes, "status_url_not_trusted_issuer"] });
+    }
+    const current = await get(`/agentx/id/${encodeURIComponent(document.agent_id)}/status.json`);
+    const onlineFailures = [];
+    if (!current || current.error) onlineFailures.push("current_status_unavailable");
+    if (current.agent_id !== document.agent_id) onlineFailures.push("current_agent_id_mismatch");
+    if (current.host !== document.host) onlineFailures.push("current_host_mismatch");
+    if (!current.active || current.revoked) onlineFailures.push("current_identity_not_active");
+    if (current.credential_status && current.credential_status !== "active") onlineFailures.push("current_credential_not_active");
+    if (current.credential_id && current.credential_id !== document.credential_status.credential_id) onlineFailures.push("current_credential_mismatch");
+    if (current.public_key_thumbprint !== document.verification_method.public_key_thumbprint) onlineFailures.push("current_public_key_mismatch");
+    return print({
+      ...offline,
+      ok: offline.ok && onlineFailures.length === 0,
+      document_valid: offline.ok,
+      trust_established: offline.ok && onlineFailures.length === 0,
+      online_checked: true,
+      current_status: current,
+      failure_codes: [...new Set([...offline.failure_codes, ...onlineFailures])],
     });
   }
   if (cmd === "enterprise-credential-rotate") {
@@ -2674,7 +2910,16 @@ async function runCli(argv) {
     try { response = await session.rotateCredential(); } finally { session.clear(); }
     const receipt = await replaceEnterpriseBootstrapCredential(projectRoot, response.credential, response.bootstrap_secret, existing.credential.credential_id);
     await writeEnterpriseEnrollmentState(projectRoot, { ...state, status: "verified_domain", credential_id: response.credential.credential_id });
-    return print({ ok: true, schema: "agentx-enterprise-credential-rotation-v1", receipt, next_action: "update_the_customer_secret_manager_copy" });
+    return print({
+      ok: true,
+      schema: "agentx-enterprise-credential-rotation-v1",
+      receipt,
+      next_actions: [
+        "update_the_customer_secret_manager_copy",
+        `agent-id enterprise-identity-publish --project-root ${projectRoot} --public-root <public-root> --apply`,
+        "deploy_and_verify_the_updated_well_known_identity",
+      ],
+    });
   }
   if (cmd === "enterprise-credential-revoke") {
     if (!argv.includes("--approve")) throw new Error("enterprise credential revocation requires --approve");
@@ -2712,6 +2957,19 @@ async function runCli(argv) {
   if (cmd === "enterprise-status") {
     return print(await enterpriseInstallStatus(readFlagValue(argv, "--project-root") || process.cwd()));
   }
+  if (cmd === "dashboard-login") {
+    const projectRoot = readFlagValue(argv, "--project-root") || process.cwd();
+    const { session } = await enterpriseSessionForProject(projectRoot);
+    try {
+      const result = await session.createDashboardPairing();
+      if (argv.includes("--json")) return print(result);
+      console.log(`Dashboard: ${result.login_url}`);
+      console.log(`Valid for ${result.expires_in} seconds and usable once.`);
+      return;
+    } finally {
+      session.clear();
+    }
+  }
   if ([
     "enterprise-managed-enable",
     "enterprise-managed-status",
@@ -2737,6 +2995,73 @@ async function runCli(argv) {
       session.clear();
     }
   }
+  if (cmd === "enterprise-optimize-once") {
+    const projectRoot = readFlagValue(argv, "--project-root") || process.cwd();
+    const { root, state, session, identity, credential } = await enterpriseSessionForProject(projectRoot);
+    const policy = loadLocalPolicy(path.join(root, ".agent-id", "enterprise-policy.json"));
+    identity.subject = { tenant_id: credential.tenant_id, host: credential.host, environment: state.environment, agent_id: credential.agent_id };
+    const executor = createTaskExecutor({
+      issuerPublicKey: await trustedIssuerPublicKey(),
+      identity,
+      policy,
+      connectors: { repository_patch: createRepositoryConnector({ repositoryRoot: root }) },
+      statePath: path.join(root, ".agent-id", "executor-state.json")
+    });
+    const approvedTask = readFlagValue(argv, "--approve-task");
+    try {
+      return print(await createOptimizationLoop({ session, executor }).runOnce({ approvedTaskIds: approvedTask ? [approvedTask] : [] }));
+    } finally {
+      session.clear();
+    }
+  }
+  if (cmd === "enterprise-task-propose") {
+    const projectRoot = readFlagValue(argv, "--project-root") || process.cwd();
+    const contentFile = argv[2];
+    if (!url || !contentFile) throw new Error("enterprise-task-propose requires <allowlisted-path> <content-file>");
+    const policy = loadLocalPolicy(path.join(path.resolve(projectRoot), ".agent-id", "enterprise-policy.json"));
+    const { session } = await enterpriseSessionForProject(projectRoot);
+    try {
+      const idempotencyKey = readFlagValue(argv, "--idempotency-key") || `cli-${crypto.randomUUID()}`;
+      return print(await session.proposeTask({
+        path: url,
+        content: fs.readFileSync(path.resolve(contentFile), "utf8"),
+        policyDigest: policy.digest,
+        idempotencyKey,
+      }));
+    } finally {
+      session.clear();
+    }
+  }
+  if (cmd === "enterprise-rollback-once") {
+    const projectRoot = readFlagValue(argv, "--project-root") || process.cwd();
+    const taskId = readFlagValue(argv, "--task-id");
+    if (!taskId) throw new Error("enterprise-rollback-once requires --task-id");
+    if (!argv.includes("--approve")) throw new Error("enterprise rollback requires --approve");
+    const { root, state, session, identity, credential } = await enterpriseSessionForProject(projectRoot);
+    const policy = loadLocalPolicy(path.join(root, ".agent-id", "enterprise-policy.json"));
+    identity.subject = { tenant_id: credential.tenant_id, host: credential.host, environment: state.environment, agent_id: credential.agent_id };
+    const executor = createTaskExecutor({
+      issuerPublicKey: await trustedIssuerPublicKey(),
+      identity,
+      policy,
+      connectors: { repository_patch: createRepositoryConnector({ repositoryRoot: root }) },
+      statePath: path.join(root, ".agent-id", "executor-state.json")
+    });
+    try {
+      const listed = await session.listTasks();
+      let task = (listed.tasks || []).find((item) => item.task_id === taskId);
+      if (!task) throw new Error("enterprise_task_not_found");
+      if (["deployed", "failed"].includes(task.state)) {
+        task = (await session.transitionTask(taskId, "rollback", task.version)).task;
+      }
+      if (task.state !== "rollback_pending") throw new Error(`enterprise_task_not_rollbackable:${task.state}`);
+      const rollbackReceipt = await executor.rollback(taskId, { approved: true, task_id: taskId });
+      const completed = await session.transitionTask(taskId, "rollback-receipt", task.version, { rollback_receipt: rollbackReceipt });
+      return print({ ok: true, task: completed.task, rollback_receipt: rollbackReceipt });
+    } finally {
+      session.clear();
+    }
+  }
   if (cmd === "repository-patch-plan") {
     const root = url;
     const changesFile = argv[2];
@@ -2790,7 +3115,7 @@ function runMcp() {
 
 async function handleMcpLine(line) {
   const msg = JSON.parse(line);
-  if (msg.method === "initialize") return send(msg.id, { protocolVersion: "2024-11-05", serverInfo: { name: "agent-id", version: "0.1.0" } });
+  if (msg.method === "initialize") return send(msg.id, { protocolVersion: "2024-11-05", serverInfo: { name: "agent-id", version: "0.3.0" } });
   if (msg.method === "tools/list") {
     const tools = [
         { name: "audit_url", description: "Audit a website for SEO/AEO/GEO/Agent readiness.", inputSchema: { type: "object", properties: { url: { type: "string" } }, required: ["url"] } },
@@ -3392,6 +3717,6 @@ async function handleMcpLine(line) {
 }
 
 runCli(process.argv.slice(2)).catch(err => {
-  console.error(err.message);
+  console.error(err.code && !String(err.message).includes(err.code) ? `${err.code}: ${err.message}` : err.message);
   process.exit(1);
 });