@agentvalet/register 1.3.0 → 1.4.0

package/README.md

@@ -15,9 +15,29 @@ No installation required. Authenticate with GitHub, and your agent is registered
 1. Opens your browser to authenticate with GitHub
 2. Creates your AgentValet account (or finds your existing one)
 3. Registers this machine as an agent
-4. Writes config to `.agentvalet/` in the current directory
+4. Writes config and your private key to `~/.agentvalet/` in your **home**
+   directory (not the current directory)
 5. Outputs the environment variables you need
 
+## Already have an agent on this machine?
+
+An agent's private key exists only on your machine — the proxy never sees it,
+and there is no rotation endpoint. Overwriting it destroys that identity, along
+with its grants and audit continuity.
+
+So registering while `~/.agentvalet/agent.key` already belongs to a **different**
+agent stops with an error rather than overwriting it. You have two options:
+
+```bash
+# Keep both — store the new agent under ~/.agentvalet/<label>/
+npx @agentvalet/register claim <bind_secret> --label work-laptop
+
+# Replace the existing one — a timestamped backup is written first
+npx @agentvalet/register --force
+```
+
+Re-registering the *same* agent over its own key is always allowed.
+
 ## Requirements
 
 - Node.js 18+

package/dist/index.js

@@ -180,8 +180,72 @@ function sleep(ms) {
 
 // src/save.ts
 import { writeFile, mkdir } from "fs/promises";
+
+// src/config/key-guard.ts
+import { existsSync, copyFileSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+var KeyClobberError = class extends Error {
+  constructor(keyPath, existingAgentId, message) {
+    super(message);
+    this.keyPath = keyPath;
+    this.existingAgentId = existingAgentId;
+    this.name = "KeyClobberError";
+  }
+  keyPath;
+  existingAgentId;
+};
+function existingKeyOwner(keyPath) {
+  if (!existsSync(keyPath)) return null;
+  const configPath = join(dirname(keyPath), "config.json");
+  if (!existsSync(configPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const id = parsed.agentId ?? parsed.lastAgentId;
+    return typeof id === "string" && id ? id : null;
+  } catch {
+    return null;
+  }
+}
+function backupExistingKey(keyPath) {
+  if (!existsSync(keyPath)) return null;
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  let backup = `${keyPath}.bak.${stamp}`;
+  let n = 1;
+  while (existsSync(backup)) backup = `${keyPath}.bak.${stamp}-${n++}`;
+  copyFileSync(keyPath, backup);
+  return backup;
+}
+function assertSafeToWriteKey(keyPath, incomingAgentId, opts = {}) {
+  if (!existsSync(keyPath)) return;
+  const owner = existingKeyOwner(keyPath);
+  if (owner && owner === incomingAgentId) return;
+  if (opts.force) {
+    backupExistingKey(keyPath);
+    return;
+  }
+  const whose = owner ? `agent ${owner}` : "another agent (owner unknown)";
+  throw new KeyClobberError(
+    keyPath,
+    owner,
+    [
+      `${keyPath} already holds the private key for ${whose}.`,
+      "",
+      "Overwriting it would destroy that identity permanently: the key exists",
+      "only on this machine and there is no way to recover or rotate it.",
+      "",
+      "Options:",
+      `  \u2022 Keep both \u2014 move ${keyPath} aside first, or use 'claim --label <name>'`,
+      "    to store an additional agent under ~/.agentvalet/<name>/.",
+      "  \u2022 Replace it \u2014 re-run with --force. The existing key is copied to",
+      `    ${keyPath}.bak.<timestamp> before being replaced.`
+    ].join("\n")
+  );
+}
+
+// src/save.ts
 async function saveOutput(opts) {
   await mkdir(AGENT_DIR, { recursive: true });
+  assertSafeToWriteKey(AGENT_KEY_PATH, opts.agentId, { force: opts.force });
   await writeFile(AGENT_KEY_PATH, opts.privateKey, { mode: 384 });
   saveConfig({
     agentId: opts.agentId,
@@ -196,8 +260,8 @@ async function saveOutput(opts) {
 }
 
 // src/commands/refresh.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync2, statSync } from "fs";
-import { dirname, join, resolve as resolve2 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync2, statSync } from "fs";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 
 // src/lib/jwt.ts
 import { createSign, createPrivateKey } from "crypto";
@@ -215,13 +279,13 @@ function signJwt(agentId, ownerId, privateKeyPem) {
 }
 
 // src/lib/skill-writer.ts
-import { existsSync, writeFileSync, mkdirSync } from "fs";
+import { existsSync as existsSync2, writeFileSync, mkdirSync } from "fs";
 import { execSync } from "child_process";
 import path from "path";
 import chalk2 from "chalk";
 function writeAgentsMd() {
   const dest = path.join(process.cwd(), "AGENTS.md");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  AGENTS.md already exists \u2014 skipping"));
     return;
   }
@@ -264,7 +328,7 @@ Do not call platform APIs directly. Tell the user:
 }
 function writeSkillMd() {
   const dest = path.join(process.cwd(), "SKILL.md");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  SKILL.md already exists \u2014 skipping"));
     return;
   }
@@ -302,7 +366,7 @@ Dashboard: https://app.agentvalet.ai
 }
 function writeQuickstartDoc(opts) {
   const dest = path.join(process.cwd(), "AGENTVALET.md");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  AGENTVALET.md already exists \u2014 skipping"));
     return;
   }
@@ -385,9 +449,9 @@ AGENT_PRIVATE_KEY_PATH=${keyPath}
 }
 function writeFactoryDroidDroid() {
   const droidsDir = path.join(process.cwd(), ".factory", "droids");
-  if (!existsSync(droidsDir)) mkdirSync(droidsDir, { recursive: true });
+  if (!existsSync2(droidsDir)) mkdirSync(droidsDir, { recursive: true });
   const dest = path.join(droidsDir, "agentvalet.yaml");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  Factory Droid: .factory/droids/agentvalet.yaml already exists"));
     return;
   }
@@ -457,9 +521,9 @@ instructions: |
 }
 function writeFactoryDroidCommand() {
   const commandsDir = path.join(process.cwd(), ".factory", "commands");
-  if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
+  if (!existsSync2(commandsDir)) mkdirSync(commandsDir, { recursive: true });
   const statusDest = path.join(commandsDir, "av-status.md");
-  if (!existsSync(statusDest)) {
+  if (!existsSync2(statusDest)) {
     const statusContent = `# /av-status
 
 Check your AgentValet agent status and approved platform connections.
@@ -482,7 +546,7 @@ Check your AgentValet agent status and approved platform connections.
     console.log(chalk2.dim("  Factory Droid: .factory/commands/av-status.md already exists"));
   }
   const registerDest = path.join(commandsDir, "av-register.md");
-  if (!existsSync(registerDest)) {
+  if (!existsSync2(registerDest)) {
     const registerContent = `# /av-register
 
 Register or re-register this project with AgentValet.
@@ -509,9 +573,9 @@ After running, approve the agent at: https://app.agentvalet.ai/agents
 }
 function writeFactoryDroidReliabilityDroid() {
   const droidsDir = path.join(process.cwd(), ".factory", "droids");
-  if (!existsSync(droidsDir)) mkdirSync(droidsDir, { recursive: true });
+  if (!existsSync2(droidsDir)) mkdirSync(droidsDir, { recursive: true });
   const dest = path.join(droidsDir, "agentvalet-reliability.yaml");
-  if (existsSync(dest)) return;
+  if (existsSync2(dest)) return;
   const content = `# AgentValet Reliability Droid
 # Monitors agent call patterns and surfaces governance issues
 # Commit this file to your repo
@@ -677,7 +741,7 @@ To refresh this file: \`npx @agentvalet/register refresh\`
 }
 
 // src/lib/require-agent.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { resolve } from "path";
 import chalk3 from "chalk";
 var NO_AGENT_MSG = chalk3.red("\n  \u2717 No agent registered.\n") + chalk3.dim(
@@ -710,9 +774,9 @@ function tryResolveAgent(envFile = ".env.agentvalet") {
   if (!keyPath) keyPath = AGENT_KEY_PATH;
   if (!agentId || !ownerId) {
     const envPath = resolve(envFile);
-    if (existsSync2(envPath)) {
+    if (existsSync3(envPath)) {
       try {
-        const vars = parseEnvFile(readFileSync2(envPath, "utf-8"));
+        const vars = parseEnvFile(readFileSync3(envPath, "utf-8"));
         agentId = agentId ?? vars["AGENTVALET_AGENT_ID"];
         ownerId = ownerId ?? vars["AGENTVALET_OWNER_ID"];
         apiUrl = vars["AGENTVALET_API_URL"] ?? apiUrl;
@@ -726,12 +790,12 @@ function tryResolveAgent(envFile = ".env.agentvalet") {
   if (process.env["AGENTVALET_API_URL"]) apiUrl = process.env["AGENTVALET_API_URL"];
   if (process.env["AGENTVALET_PRIVATE_KEY_PATH"]) keyPath = process.env["AGENTVALET_PRIVATE_KEY_PATH"];
   if (!agentId || !ownerId || !keyPath) return null;
-  if (!existsSync2(resolve(keyPath))) return null;
+  if (!existsSync3(resolve(keyPath))) return null;
   return { agentId, ownerId, keyPath, apiUrl };
 }
 
 // src/config/frameworks.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { execSync as execSync2 } from "child_process";
 import os from "os";
 import path2 from "path";
@@ -749,27 +813,27 @@ function codexDesktopInstalled() {
   const home = os.homedir();
   const platform = process.platform;
   if (platform === "darwin") {
-    return existsSync3("/Applications/Codex.app") || existsSync3(path2.join(home, "Applications", "Codex.app"));
+    return existsSync4("/Applications/Codex.app") || existsSync4(path2.join(home, "Applications", "Codex.app"));
   }
   if (platform === "win32") {
     const localAppData = process.env.LOCALAPPDATA ?? path2.join(home, "AppData", "Local");
     const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
-    return existsSync3(path2.join(localAppData, "Programs", "codex")) || existsSync3(path2.join(localAppData, "Programs", "Codex")) || existsSync3(path2.join(programFiles, "Codex"));
+    return existsSync4(path2.join(localAppData, "Programs", "codex")) || existsSync4(path2.join(localAppData, "Programs", "Codex")) || existsSync4(path2.join(programFiles, "Codex"));
   }
-  return existsSync3("/usr/share/applications/codex.desktop") || existsSync3(path2.join(home, ".local", "share", "applications", "codex.desktop"));
+  return existsSync4("/usr/share/applications/codex.desktop") || existsSync4(path2.join(home, ".local", "share", "applications", "codex.desktop"));
 }
 function claudeDesktopInstalled() {
   const home = os.homedir();
   const platform = process.platform;
   if (platform === "darwin") {
-    return existsSync3("/Applications/Claude.app") || existsSync3(path2.join(home, "Library", "Application Support", "Claude"));
+    return existsSync4("/Applications/Claude.app") || existsSync4(path2.join(home, "Library", "Application Support", "Claude"));
   }
   if (platform === "win32") {
     const appData = process.env.APPDATA ?? path2.join(home, "AppData", "Roaming");
     const localAppData = process.env.LOCALAPPDATA ?? path2.join(home, "AppData", "Local");
-    return existsSync3(path2.join(appData, "Claude")) || existsSync3(path2.join(localAppData, "AnthropicClaude")) || existsSync3(path2.join(localAppData, "Programs", "claude"));
+    return existsSync4(path2.join(appData, "Claude")) || existsSync4(path2.join(localAppData, "AnthropicClaude")) || existsSync4(path2.join(localAppData, "Programs", "claude"));
   }
-  return existsSync3(path2.join(home, ".config", "Claude"));
+  return existsSync4(path2.join(home, ".config", "Claude"));
 }
 function cursorInstalled() {
   const home = os.homedir();
@@ -777,24 +841,24 @@ function cursorInstalled() {
   if (platform === "win32") {
     const appData = process.env.APPDATA ?? path2.join(home, "AppData", "Roaming");
     const localAppData = process.env.LOCALAPPDATA ?? path2.join(home, "AppData", "Local");
-    return existsSync3(path2.join(appData, "Cursor")) || existsSync3(path2.join(localAppData, "Programs", "cursor"));
+    return existsSync4(path2.join(appData, "Cursor")) || existsSync4(path2.join(localAppData, "Programs", "cursor"));
   }
   if (platform === "darwin") {
-    return existsSync3(path2.join(home, "Library", "Application Support", "Cursor")) || existsSync3("/Applications/Cursor.app");
+    return existsSync4(path2.join(home, "Library", "Application Support", "Cursor")) || existsSync4("/Applications/Cursor.app");
   }
-  return existsSync3(path2.join(home, ".config", "Cursor")) || existsSync3("/usr/share/applications/cursor.desktop");
+  return existsSync4(path2.join(home, ".config", "Cursor")) || existsSync4("/usr/share/applications/cursor.desktop");
 }
 function detectFrameworks() {
   const home = os.homedir();
   return {
-    codex: existsSync3(path2.join(home, ".codex")) || tryBinary("codex"),
+    codex: existsSync4(path2.join(home, ".codex")) || tryBinary("codex"),
     codexDesktop: codexDesktopInstalled(),
-    claudeCode: existsSync3(path2.join(home, ".claude")) || tryBinary("claude"),
+    claudeCode: existsSync4(path2.join(home, ".claude")) || tryBinary("claude"),
     claudeDesktop: claudeDesktopInstalled(),
-    cursor: existsSync3(path2.join(process.cwd(), ".cursor")) || cursorInstalled(),
+    cursor: existsSync4(path2.join(process.cwd(), ".cursor")) || cursorInstalled(),
     cursorCli: tryBinary("cursor-agent"),
-    openclaw: existsSync3(path2.join(home, ".openclaw")),
-    factoryDroid: existsSync3(path2.join(home, ".factory")) || existsSync3(path2.join(process.cwd(), ".factory"))
+    openclaw: existsSync4(path2.join(home, ".openclaw")),
+    factoryDroid: existsSync4(path2.join(home, ".factory")) || existsSync4(path2.join(process.cwd(), ".factory"))
   };
 }
 function resolveAgentType(detected) {
@@ -862,13 +926,13 @@ var CLAUDE_END = "<!-- agentvalet:end -->";
 var HOOK_COMMAND = "npx @agentvalet/register refresh --if-stale --quiet 2>/dev/null || true";
 var HOOK_MARKER = "agentvalet/register refresh";
 function projectRootFor(outputPath) {
-  return dirname(dirname(resolve2(outputPath)));
+  return dirname2(dirname2(resolve2(outputPath)));
 }
 function writePermissionsFromEvent(agentId, ownerId, platforms, outputPath = "./.claude/agentvalet-permissions.md") {
   const content = generatePermissionsFile(agentId, ownerId, platforms);
   const resolvedPath = resolve2(outputPath);
   const projectRoot = projectRootFor(resolvedPath);
-  mkdirSync2(dirname(resolvedPath), { recursive: true });
+  mkdirSync2(dirname2(resolvedPath), { recursive: true });
   writeFileSync2(resolvedPath, content, "utf-8");
   embedInClaudeMd(content, projectRoot);
   ensureHook(projectRoot);
@@ -908,8 +972,8 @@ async function runRefresh(options) {
     try {
       const stat = statSync(outputPath);
       const fileIsFresh = Date.now() - stat.mtimeMs < 36e5;
-      const claudeMdPath = join(projectRoot, "CLAUDE.md");
-      const claudeMd = existsSync4(claudeMdPath) ? readFileSync3(claudeMdPath, "utf-8") : "";
+      const claudeMdPath = join2(projectRoot, "CLAUDE.md");
+      const claudeMd = existsSync5(claudeMdPath) ? readFileSync4(claudeMdPath, "utf-8") : "";
       const blockStart = claudeMd.indexOf(CLAUDE_START);
       const blockEnd = claudeMd.indexOf(CLAUDE_END);
       const blockContent = blockStart !== -1 && blockEnd !== -1 ? claudeMd.slice(blockStart, blockEnd) : "";
@@ -919,14 +983,14 @@ async function runRefresh(options) {
     }
   }
   const creds = tryResolveAgent(options.envFile);
-  if (!creds || !existsSync4(resolve2(creds.keyPath))) {
+  if (!creds || !existsSync5(resolve2(creds.keyPath))) {
     console.error("  \u2717 No agent registered.\n  Run the following command first to register an agent in this directory:\n\n    npx @agentvalet/register\n");
     process.exit(1);
   }
   const { agentId, ownerId, keyPath, apiUrl } = creds;
   let privateKeyPem;
   try {
-    privateKeyPem = readFileSync3(keyPath, "utf-8");
+    privateKeyPem = readFileSync4(keyPath, "utf-8");
   } catch {
     throw new Error(`Cannot read private key: ${keyPath}`);
   }
@@ -944,17 +1008,17 @@ async function runRefresh(options) {
   const json = await res.json();
   const platforms = json.data?.platforms ?? [];
   const content = generatePermissionsFile(agentId, ownerId, platforms);
-  mkdirSync2(dirname(outputPath), { recursive: true });
+  mkdirSync2(dirname2(outputPath), { recursive: true });
   writeFileSync2(outputPath, content, "utf-8");
   embedInClaudeMd(content, projectRoot);
   ensureHook(projectRoot);
   const detected = detectFrameworks();
   const refreshed = [];
   if (detected.codex || detected.codexDesktop) {
-    if (embedPermissionsBlock(join(projectRoot, "AGENTS.md"), content)) refreshed.push("AGENTS.md");
+    if (embedPermissionsBlock(join2(projectRoot, "AGENTS.md"), content)) refreshed.push("AGENTS.md");
   }
   if (detected.openclaw) {
-    if (embedPermissionsBlock(join(projectRoot, "SKILL.md"), content)) refreshed.push("SKILL.md");
+    if (embedPermissionsBlock(join2(projectRoot, "SKILL.md"), content)) refreshed.push("SKILL.md");
   }
   if (!options.quiet) {
     const extras = refreshed.length > 0 ? ` (also: ${refreshed.join(", ")})` : "";
@@ -962,9 +1026,9 @@ async function runRefresh(options) {
   }
 }
 function embedPermissionsBlock(filePath, permissionsContent) {
-  if (!existsSync4(filePath)) return false;
+  if (!existsSync5(filePath)) return false;
   try {
-    const existing = readFileSync3(filePath, "utf-8");
+    const existing = readFileSync4(filePath, "utf-8");
     const block = `${PERMISSIONS_START}
 ${permissionsContent.trimEnd()}
 ${PERMISSIONS_END}`;
@@ -987,18 +1051,18 @@ ${block}
   }
 }
 function embedInClaudeMd(permissionsContent, projectRoot) {
-  const claudeMdPath = join(projectRoot, "CLAUDE.md");
+  const claudeMdPath = join2(projectRoot, "CLAUDE.md");
   const block = `${CLAUDE_START}
 ${permissionsContent.trimEnd()}
 ${CLAUDE_END}`;
-  if (!existsSync4(claudeMdPath)) {
+  if (!existsSync5(claudeMdPath)) {
     writeFileSync2(claudeMdPath, `# Agent Instructions
 
 ${block}
 `, "utf-8");
     return;
   }
-  const existing = readFileSync3(claudeMdPath, "utf-8");
+  const existing = readFileSync4(claudeMdPath, "utf-8");
   if (existing.includes(CLAUDE_START)) {
     const replaced = existing.replace(
       new RegExp(`${CLAUDE_START}[\\s\\S]*?${CLAUDE_END}`, "m"),
@@ -1014,11 +1078,11 @@ ${block}
   }
 }
 function ensureHook(projectRoot) {
-  const settingsPath = join(projectRoot, ".claude", "settings.local.json");
+  const settingsPath = join2(projectRoot, ".claude", "settings.local.json");
   let settings = {};
-  if (existsSync4(settingsPath)) {
+  if (existsSync5(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
     } catch {
       return;
     }
@@ -1046,16 +1110,16 @@ function ensureHook(projectRoot) {
     perms.allow = [...allow, ...missing];
     settings.permissions = perms;
   }
-  mkdirSync2(dirname(settingsPath), { recursive: true });
+  mkdirSync2(dirname2(settingsPath), { recursive: true });
   writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
   ensureMcpJson(projectRoot);
 }
 function ensureMcpJson(projectRoot) {
-  const mcpJsonPath = join(projectRoot, ".mcp.json");
+  const mcpJsonPath = join2(projectRoot, ".mcp.json");
   let mcpConfig = {};
-  if (existsSync4(mcpJsonPath)) {
+  if (existsSync5(mcpJsonPath)) {
     try {
-      mcpConfig = JSON.parse(readFileSync3(mcpJsonPath, "utf-8"));
+      mcpConfig = JSON.parse(readFileSync4(mcpJsonPath, "utf-8"));
     } catch {
       return;
     }
@@ -1254,7 +1318,7 @@ async function writeLocalConfig(config) {
 // src/output/env.ts
 import chalk6 from "chalk";
 import { appendFile as appendFile2, writeFile as writeFile3 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import path4 from "path";
 function formatEnvBlock(vars) {
   return Object.entries(vars).map(([key, value]) => {
@@ -1265,7 +1329,7 @@ function formatEnvBlock(vars) {
 
 // src/config/ide.ts
 import { mkdir as mkdir3, writeFile as writeFile4, readFile as readFile2, appendFile as appendFile3, copyFile } from "fs/promises";
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import path5 from "path";
 import os2 from "os";
 function buildMcpEntry(params) {
@@ -1302,7 +1366,7 @@ function claudeDesktopFriendly() {
 }
 async function mergeJsonFile(filePath, key, value) {
   let existing = {};
-  if (existsSync6(filePath)) {
+  if (existsSync7(filePath)) {
     try {
       const text = await readFile2(filePath, "utf8");
       existing = JSON.parse(text);
@@ -1324,8 +1388,8 @@ env = { AGENT_ID = "${params.agentId}", OWNER_ID = "${params.ownerId}", PROXY_UR
 }
 async function appendCodexConfig(configPath) {
   const dir = path5.dirname(configPath);
-  if (!existsSync6(dir)) await mkdir3(dir, { recursive: true });
-  const existing = existsSync6(configPath) ? await readFile2(configPath, "utf8") : "";
+  if (!existsSync7(dir)) await mkdir3(dir, { recursive: true });
+  const existing = existsSync7(configPath) ? await readFile2(configPath, "utf8") : "";
   if (existing.includes("[mcp_servers.agentvalet]")) return false;
   return true;
 }
@@ -1334,7 +1398,7 @@ async function writeGlobalFrameworkConfigs(params) {
   const codexDir = path5.join(os2.homedir(), ".codex");
   const codexConfigPath = path5.join(codexDir, "config.toml");
   try {
-    if (!existsSync6(codexDir)) await mkdir3(codexDir, { recursive: true });
+    if (!existsSync7(codexDir)) await mkdir3(codexDir, { recursive: true });
     if (await appendCodexConfig(codexConfigPath)) {
       await appendFile3(codexConfigPath, buildCodexTomlBlock(params), "utf8");
       written.push("~/.codex/config.toml");
@@ -1359,7 +1423,7 @@ async function writeCodexProjectConfig(params) {
   return written;
 }
 async function stripAgentvaletFromMcpJson(filePath) {
-  if (!existsSync6(filePath)) return false;
+  if (!existsSync7(filePath)) return false;
   try {
     const text = await readFile2(filePath, "utf8");
     const config = JSON.parse(text);
@@ -1383,7 +1447,7 @@ async function cleanProjectScopedEntries() {
     cleaned.push(".cursor/mcp.json (project entry removed)");
   }
   const factoryProjectMcp = path5.join(cwd, ".factory/mcp.json");
-  if (existsSync6(factoryProjectMcp)) {
+  if (existsSync7(factoryProjectMcp)) {
     try {
       const text = await readFile2(factoryProjectMcp, "utf8");
       const config = JSON.parse(text);
@@ -1474,7 +1538,7 @@ async function writeIdeConfigs(params) {
 }
 async function mergeFactoryDroidMcpJson(filePath, key, value) {
   let existing = {};
-  if (existsSync6(filePath)) {
+  if (existsSync7(filePath)) {
     try {
       const text = await readFile2(filePath, "utf8");
       existing = JSON.parse(text);
@@ -1488,7 +1552,7 @@ async function mergeFactoryDroidMcpJson(filePath, key, value) {
 }
 async function updateGitignoreForFactoryDroid() {
   const gitignorePath = path5.join(process.cwd(), ".gitignore");
-  if (!existsSync6(gitignorePath)) return;
+  if (!existsSync7(gitignorePath)) return;
   const existing = await readFile2(gitignorePath, "utf8");
   if (existing.includes(".factory/mcp.json")) return;
   const additions = [
@@ -1870,8 +1934,8 @@ import chalk10 from "chalk";
 // src/commands/uninstall.ts
 import { Command as Command2 } from "commander";
 import chalk9 from "chalk";
-import { existsSync as existsSync7, readFileSync as readFileSync4, writeFileSync as writeFileSync3, rmSync } from "fs";
-import { resolve as resolve3, join as join2 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync3, rmSync } from "fs";
+import { resolve as resolve3, join as join3 } from "path";
 import { homedir } from "os";
 var CLAUDE_START2 = "<!-- agentvalet:start -->";
 var CLAUDE_END2 = "<!-- agentvalet:end -->";
@@ -1879,9 +1943,9 @@ var PERMISSIONS_START2 = "<!-- agentvalet:permissions:start -->";
 var PERMISSIONS_END2 = "<!-- agentvalet:permissions:end -->";
 var HOOK_MARKER2 = "agentvalet/register refresh";
 function stripPermissionsBlock(filePath) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const content = readFileSync4(filePath, "utf-8");
+    const content = readFileSync5(filePath, "utf-8");
     if (!content.includes(PERMISSIONS_START2)) return false;
     const stripped = content.replace(new RegExp(`${PERMISSIONS_START2}[\\s\\S]*?${PERMISSIONS_END2}`, "m"), "").replace(/(\r?\n){3,}/g, "\n\n").trimEnd();
     writeFileSync3(filePath, stripped + "\n", "utf-8");
@@ -1892,8 +1956,8 @@ function stripPermissionsBlock(filePath) {
 }
 function stripClaudeMd() {
   const path8 = resolve3("CLAUDE.md");
-  if (!existsSync7(path8)) return;
-  let content = readFileSync4(path8, "utf-8");
+  if (!existsSync8(path8)) return;
+  let content = readFileSync5(path8, "utf-8");
   content = content.replace(new RegExp(`${CLAUDE_START2}[\\s\\S]*?${CLAUDE_END2}`, "m"), "");
   content = content.replace(/^@\.claude\/agentvalet-permissions\.md\s*$/m, "");
   content = content.replace(/(\r?\n){3,}/g, "\n\n").trim();
@@ -1901,9 +1965,9 @@ function stripClaudeMd() {
 }
 function stripSettingsJson() {
   const path8 = resolve3(".claude/settings.local.json");
-  if (!existsSync7(path8)) return;
+  if (!existsSync8(path8)) return;
   try {
-    const settings = JSON.parse(readFileSync4(path8, "utf-8"));
+    const settings = JSON.parse(readFileSync5(path8, "utf-8"));
     const hooks = settings.hooks ?? {};
     const ups = hooks.UserPromptSubmit ?? [];
     hooks.UserPromptSubmit = ups.filter(
@@ -1919,9 +1983,9 @@ function stripSettingsJson() {
   }
 }
 function stripMcpJson(filePath, options = {}) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const config = JSON.parse(readFileSync4(filePath, "utf-8"));
+    const config = JSON.parse(readFileSync5(filePath, "utf-8"));
     let removed = false;
     if (options.wrapped === false) {
       if (config["agentvalet"] !== void 0) {
@@ -1945,9 +2009,9 @@ function stripMcpJson(filePath, options = {}) {
   }
 }
 function stripCodexTomlAt(filePath) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const content = readFileSync4(filePath, "utf-8");
+    const content = readFileSync5(filePath, "utf-8");
     if (!content.includes("[mcp_servers.agentvalet]")) return false;
     const stripped = content.replace(
       /\r?\n?\[mcp_servers\.agentvalet\][\s\S]*?(?=\r?\n\[|\r?\n*$)/,
@@ -1960,9 +2024,9 @@ function stripCodexTomlAt(filePath) {
   }
 }
 function isAgentValetGeneratedDoc(filePath, markers) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const content = readFileSync4(filePath, "utf-8");
+    const content = readFileSync5(filePath, "utf-8");
     const firstLine = content.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
     return markers.some((m) => firstLine.startsWith(m));
   } catch {
@@ -1974,13 +2038,13 @@ function cleanLocally() {
   const stripped = [];
   const r = (p) => {
     const abs = resolve3(p);
-    if (existsSync7(abs)) {
+    if (existsSync8(abs)) {
       rmSync(abs, { recursive: true, force: true });
       removed.push(abs);
     }
   };
   const rAbs = (abs) => {
-    if (existsSync7(abs)) {
+    if (existsSync8(abs)) {
       rmSync(abs, { recursive: true, force: true });
       removed.push(abs);
     }
@@ -2003,12 +2067,12 @@ function cleanLocally() {
   if (stripMcpJson(resolve3(".cursor/mcp.json"))) stripped.push(".cursor/mcp.json");
   if (stripMcpJson(resolve3(".factory/mcp.json"), { wrapped: false })) stripped.push(".factory/mcp.json");
   const home = homedir();
-  if (stripMcpJson(join2(home, ".claude.json"))) stripped.push("~/.claude.json");
-  const claudeDesktopConfig = process.platform === "darwin" ? join2(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join2(process.env.APPDATA ?? join2(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json") : join2(home, ".config", "Claude", "claude_desktop_config.json");
+  if (stripMcpJson(join3(home, ".claude.json"))) stripped.push("~/.claude.json");
+  const claudeDesktopConfig = process.platform === "darwin" ? join3(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join3(process.env.APPDATA ?? join3(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json") : join3(home, ".config", "Claude", "claude_desktop_config.json");
   if (stripMcpJson(claudeDesktopConfig)) stripped.push("claude_desktop_config.json");
-  if (stripMcpJson(join2(home, ".cursor", "mcp.json"))) stripped.push("~/.cursor/mcp.json");
-  if (stripMcpJson(join2(home, ".factory", "mcp.json"), { wrapped: false })) stripped.push("~/.factory/mcp.json");
-  if (stripCodexTomlAt(join2(home, ".codex", "config.toml"))) stripped.push("~/.codex/config.toml");
+  if (stripMcpJson(join3(home, ".cursor", "mcp.json"))) stripped.push("~/.cursor/mcp.json");
+  if (stripMcpJson(join3(home, ".factory", "mcp.json"), { wrapped: false })) stripped.push("~/.factory/mcp.json");
+  if (stripCodexTomlAt(join3(home, ".codex", "config.toml"))) stripped.push("~/.codex/config.toml");
   if (stripCodexTomlAt(resolve3(".codex/config.toml"))) stripped.push(".codex/config.toml");
   stripClaudeMd();
   stripSettingsJson();
@@ -2113,7 +2177,7 @@ function uninstallCommand() {
     }
     let privateKeyPem;
     try {
-      privateKeyPem = readFileSync4(creds.keyPath, "utf-8").trim();
+      privateKeyPem = readFileSync5(creds.keyPath, "utf-8").trim();
     } catch {
     }
     if (!privateKeyPem) {
@@ -2230,13 +2294,13 @@ function revokeCommand() {
 import { Command as Command4 } from "commander";
 import chalk11 from "chalk";
 import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile8 } from "fs/promises";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname3 } from "path";
 
 // src/lib/claude-config.ts
 import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { readFile as readFile3, writeFile as writeFile6, mkdir as mkdir4, access } from "fs/promises";
-var CLAUDE_CONFIG_PATH = join3(homedir2(), ".claude", "config");
+var CLAUDE_CONFIG_PATH = join4(homedir2(), ".claude", "config");
 async function writeKeyToClaudeConfig(agentId, privateKeyPem) {
   let config = {};
   try {
@@ -2247,7 +2311,7 @@ async function writeKeyToClaudeConfig(agentId, privateKeyPem) {
   }
   config.agent_keys = config.agent_keys ?? {};
   config.agent_keys[agentId] = Buffer.from(privateKeyPem).toString("base64");
-  await mkdir4(join3(homedir2(), ".claude"), { recursive: true });
+  await mkdir4(join4(homedir2(), ".claude"), { recursive: true });
   await writeFile6(CLAUDE_CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
 }
 
@@ -2282,7 +2346,7 @@ function injectCommand() {
     "--target <target>",
     "Where to write the key: agentvalet (default \u2014 modern store + MCP configs), env-local (.env.local), claude-legacy (~/.claude/config, deprecated)",
     "agentvalet"
-  ).option("--no-frameworks", "Skip IDE/framework configuration prompts (only with --target agentvalet)").option("--project", "Write project-scoped framework configs instead of user-scoped").action(async (opts) => {
+  ).option("--no-frameworks", "Skip IDE/framework configuration prompts (only with --target agentvalet)").option("--project", "Write project-scoped framework configs instead of user-scoped").option("--force", "Replace an existing agent key (a timestamped backup is written first)").action(async (opts) => {
     let privateKeyPem;
     try {
       privateKeyPem = await readFile5(opts.keyFile, "utf-8");
@@ -2302,7 +2366,8 @@ function injectCommand() {
           console.error(chalk11.dim("  Find it at https://app.agentvalet.ai or in your existing ~/.agentvalet/config.json"));
           process.exit(1);
         }
-        await mkdir5(dirname2(AGENT_KEY_PATH), { recursive: true });
+        await mkdir5(dirname3(AGENT_KEY_PATH), { recursive: true });
+        assertSafeToWriteKey(AGENT_KEY_PATH, opts.agentId, { force: opts.force });
         await writeFile8(AGENT_KEY_PATH, privateKeyPem, { mode: 384 });
         saveConfig({
           agentId: opts.agentId,
@@ -2357,7 +2422,7 @@ function injectCommand() {
         process.exit(1);
       }
     } catch (err) {
-      console.error(chalk11.red(String(err)));
+      console.error(chalk11.red(err instanceof KeyClobberError ? err.message : String(err)));
       process.exit(1);
     }
     console.log(chalk11.green("\n  Done. Your agent is ready to use."));
@@ -2400,7 +2465,7 @@ async function bindInstallToken(proxyUrl, bootstrapToken) {
   return { ...body, privateKeyPem: privateKey };
 }
 function installCommand() {
-  return new Command5("install").description("Install an agent on this machine using a one-time install token (generates the keypair locally and binds it)").argument("<token>", "install token (itok_...) from the dashboard").option("--no-frameworks", "skip IDE/framework configuration prompts").option("--project", "write project-scoped configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").action(async (token, opts) => {
+  return new Command5("install").description("Install an agent on this machine using a one-time install token (generates the keypair locally and binds it)").argument("<token>", "install token (itok_...) from the dashboard").option("--no-frameworks", "skip IDE/framework configuration prompts").option("--project", "write project-scoped configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").option("--force", "replace an existing agent key (a timestamped backup is written first)").action(async (token, opts) => {
     const scope = opts.project ? "project" : "user";
     if (!token.startsWith("itok_")) {
       console.error(chalk12.red('Invalid install token. Tokens start with "itok_".'));
@@ -2426,8 +2491,14 @@ function installCommand() {
     const agent_name = claim.agent_id;
     try {
       await mkdir6(AGENT_DIR, { recursive: true });
+      assertSafeToWriteKey(AGENT_KEY_PATH, agent_id, { force: opts.force });
       await writeFile9(AGENT_KEY_PATH, private_key_pem, { mode: 384 });
     } catch (err) {
+      if (err instanceof KeyClobberError) {
+        console.error(chalk12.red(`
+  \u2717 ${err.message}`));
+        process.exit(3);
+      }
       console.error(chalk12.red(`
   \u2717 Failed to write key: ${err instanceof Error ? err.message : err}`));
       process.exit(3);
@@ -2563,14 +2634,14 @@ function installCommand() {
 // src/commands/claim.ts
 import { Command as Command6 } from "commander";
 import { generateKeyPairSync as generateKeyPairSync2 } from "crypto";
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, existsSync as existsSync8 } from "fs";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, existsSync as existsSync9 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import chalk13 from "chalk";
 var DEFAULT_PROXY_URL = "https://api.agentvalet.ai";
 function resolveAgentDir(label) {
-  const root = join4(homedir3(), ".agentvalet");
-  return label ? join4(root, label) : root;
+  const root = join5(homedir3(), ".agentvalet");
+  return label ? join5(root, label) : root;
 }
 function sanitiseLabel(label) {
   return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -2614,9 +2685,9 @@ function claimCommand() {
       process.exit(3);
     }
     const agentDir = resolveAgentDir(label);
-    const keyPath = join4(agentDir, "agent.key");
-    const identityPath = join4(agentDir, "agent.json");
-    if (existsSync8(keyPath)) {
+    const keyPath = join5(agentDir, "agent.key");
+    const identityPath = join5(agentDir, "agent.json");
+    if (existsSync9(keyPath)) {
       const msg = label ? `An agent already exists at ${keyPath}. Pick a different --label or remove the directory first.` : `A default agent already exists at ${keyPath}. Pass --label <name> to claim alongside it without overwriting.`;
       console.error(isJson ? JSON.stringify({ error: msg }) : chalk13.red(msg));
       process.exit(3);
@@ -2708,7 +2779,7 @@ function collectScope(value, previous) {
   return [...previous, value];
 }
 var program = new Command7();
-program.name("agentvalet-register").description("Self-register an AI agent with AgentValet").version(version).option("--owner <uuid>", "Owner ID (or set AGENTVALET_OWNER env var)").option("--name <name>", "Agent name").option("--description <desc>", "Agent description").option("--scope <platform:scope>", "Requested scope, repeatable", collectScope, []).option("--api-url <url>", "AgentValet API base URL", "https://api.agentvalet.ai").option("--json", "Machine-readable JSON output").option("--no-wait", "Register only, do not wait for approval").option("--timeout <seconds>", "Approval wait timeout in seconds", "300").option("--project", "Write project-scoped MCP configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").action(async (opts) => {
+program.name("agentvalet-register").description("Self-register an AI agent with AgentValet").version(version).option("--owner <uuid>", "Owner ID (or set AGENTVALET_OWNER env var)").option("--name <name>", "Agent name").option("--description <desc>", "Agent description").option("--scope <platform:scope>", "Requested scope, repeatable", collectScope, []).option("--api-url <url>", "AgentValet API base URL", "https://api.agentvalet.ai").option("--json", "Machine-readable JSON output").option("--no-wait", "Register only, do not wait for approval").option("--timeout <seconds>", "Approval wait timeout in seconds", "300").option("--project", "Write project-scoped MCP configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").option("--force", "Replace an existing agent's key (a timestamped backup is written first)").action(async (opts) => {
   const isJson = !!opts.json;
   let ownerId = opts.owner ?? process.env.AGENTVALET_OWNER ?? "";
   let agentName = opts.name ?? "";
@@ -2824,10 +2895,15 @@ Approve at: https://app.agentvalet.ai/agents
         agentId,
         ownerId: resolvedOwnerId,
         privateKey,
-        apiUrl: opts.apiUrl
+        apiUrl: opts.apiUrl,
+        force: !!opts.force
       }));
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
+      if (err instanceof KeyClobberError) {
+        console.error(isJson ? JSON.stringify({ error: msg, existing_agent_id: err.existingAgentId }) : chalk14.red(msg));
+        process.exit(3);
+      }
       console.error(isJson ? JSON.stringify({ error: msg }) : chalk14.red(`Failed to save output: ${msg}`));
       process.exit(3);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/register",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Self-register AI agents with AgentValet",
   "type": "module",
   "bin": {