@rryando/arcs 3.9.2 → 3.11.0

package/scripts/build-opencode-bundle.mjs

@@ -41,11 +41,12 @@ function pruneUndeclaredFiles(rootPath, allowedFiles) {
 let defaultOutputRootCurrent = defaultOutputRoot;
 
 /**
- * Generates the ARCS Orchestrator and ARCS Caveman prompt .txt files into
- * <outputRoot>/prompts/. The TypeScript modules src/cli/arcs-orchestrate.ts
- * and src/cli/arcs-orchestrate-caveman.ts remain the canonical source; these
- * .txt files are committed mirrors so the bundle is self-describing alongside
- * the static sub-agent prompts.
+ * Generates the ARCS Orchestrator, ARCS Caveman, and ARCS Flash prompt .txt
+ * files into <outputRoot>/prompts/. The TypeScript modules
+ * src/cli/arcs-orchestrate.ts, src/cli/arcs-orchestrate-caveman.ts, and
+ * src/cli/arcs-flash.ts remain the canonical source; these .txt files are
+ * committed mirrors so the bundle is self-describing alongside the static
+ * sub-agent prompts.
  *
  * Requires `tsc` to have run first (dist/cli/arcs-orchestrate.js must exist).
  * package.json's build:opencode-bundle chains `tsc` before this script.
@@ -53,19 +54,28 @@ let defaultOutputRootCurrent = defaultOutputRoot;
 async function generateOrchestratorPrompts(outputRoot) {
   const orchestrateModulePath = resolve(repoRoot, "dist/cli/arcs-orchestrate.js");
   const cavemanModulePath = resolve(repoRoot, "dist/cli/arcs-orchestrate-caveman.js");
+  const flashModulePath = resolve(repoRoot, "dist/cli/arcs-flash.js");
 
-  if (!existsSync(orchestrateModulePath) || !existsSync(cavemanModulePath)) {
+  if (
+    !existsSync(orchestrateModulePath) ||
+    !existsSync(cavemanModulePath) ||
+    !existsSync(flashModulePath)
+  ) {
     throw new Error(
       `Compiled orchestrator modules missing. Run \`npm run build\` before bundle build.\n` +
         `  Expected: ${orchestrateModulePath}\n` +
-        `  Expected: ${cavemanModulePath}`,    );
+        `  Expected: ${cavemanModulePath}\n` +
+        `  Expected: ${flashModulePath}`,
+    );
   }
 
   const orchestrateModule = await import(pathToFileURL(orchestrateModulePath).href);
   const cavemanModule = await import(pathToFileURL(cavemanModulePath).href);
+  const flashModule = await import(pathToFileURL(flashModulePath).href);
 
   const orchestrateText = orchestrateModule.ORCHESTRATE_PROMPT_TEXT;
   const cavemanText = cavemanModule.ORCHESTRATE_CAVEMAN_PROMPT_TEXT;
+  const flashText = flashModule.FLASH_PROMPT_TEXT;
 
   if (typeof orchestrateText !== "string" || orchestrateText.length === 0) {
     throw new Error("ORCHESTRATE_PROMPT_TEXT not exported as non-empty string");
@@ -73,12 +83,16 @@ async function generateOrchestratorPrompts(outputRoot) {
   if (typeof cavemanText !== "string" || cavemanText.length === 0) {
     throw new Error("ORCHESTRATE_CAVEMAN_PROMPT_TEXT not exported as non-empty string");
   }
+  if (typeof flashText !== "string" || flashText.length === 0) {
+    throw new Error("FLASH_PROMPT_TEXT not exported as non-empty string");
+  }
 
   const promptsDir = resolve(outputRoot, "prompts");
   mkdirSync(promptsDir, { recursive: true });
 
   const orchestratePath = resolve(promptsDir, "arcs-orchestrate.txt");
   const cavemanPath = resolve(promptsDir, "arcs-orchestrate-caveman.txt");
+  const flashPath = resolve(promptsDir, "arcs-flash.txt");
 
   // Banner prepended to every generated prompt file. Uses HTML comment syntax
   // so it's invisible when rendered as markdown but obvious to anyone opening
@@ -102,6 +116,7 @@ async function generateOrchestratorPrompts(outputRoot) {
     `${banner("src/cli/arcs-orchestrate-caveman.ts")}${cavemanText}\n`,
     "utf-8",
   );
+  writeFileSync(flashPath, `${banner("src/cli/arcs-flash.ts")}${flashText}\n`, "utf-8");
 }
 
 async function main() {
@@ -140,11 +155,8 @@ async function main() {
   ]);
 
   mkdirSync(outputRoot, { recursive: true });
-  pruneUndeclaredFiles(outputRoot, allowedOutputFiles);
-
-  // Generate orchestrator prompt mirrors after prune so they always end up
-  // on disk fresh from the canonical TS sources.
   await generateOrchestratorPrompts(outputRoot);
+  pruneUndeclaredFiles(outputRoot, allowedOutputFiles);
 }
 
 try {

package/scripts/claude-code-session-hook.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * ARCS ↔ Claude Code session-bridge hook.
+ *
+ * Registered four times in settings.json (SessionStart, UserPromptSubmit,
+ * SessionEnd, Stop) and dispatches internally on the `hook_event_name` field
+ * Claude Code writes to stdin. Install with `arcs hooks install-claude-code
+ * <slug>`, which generates the token and prints the snippet to paste.
+ *
+ * HARD RULE: this script never blocks the session. Any failure — ARCS not
+ * running, token rejected, timeout, malformed JSON — is swallowed, nothing is
+ * printed, and the exit code stays 0. Exit code 2 (the "block" signal) is never
+ * produced. A broken bridge must be invisible, never an obstacle to the user's
+ * actual Claude Code session.
+ *
+ * Config comes from the environment, assigned inline in the settings.json
+ * command string:
+ *   ARCS_HOOK_TOKEN  per-project token (required)
+ *   ARCS_HOOK_SLUG   ARCS project slug (required)
+ *   ARCS_HOOK_URL    ARCS web server URL (default http://127.0.0.1:4173)
+ */
+
+const DEFAULT_URL = "http://127.0.0.1:4173";
+/** Short by design: a hung ARCS server must not stall prompt submission. */
+const TIMEOUT_MS = 1500;
+const EVENTS = new Set(["SessionStart", "UserPromptSubmit", "SessionEnd", "Stop"]);
+
+/** Never rejects: an unreadable stdin yields "" and the run turns into a no-op. */
+function readStdin() {
+  return new Promise((resolveStdin) => {
+    let raw = "";
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.stdin.destroy();
+      resolveStdin(raw);
+    };
+    const timer = setTimeout(finish, TIMEOUT_MS);
+
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on("end", finish);
+    process.stdin.on("error", finish);
+  });
+}
+
+/**
+ * Labelled and separated so the agent can tell queued out-of-band instructions
+ * from the prompt the user just typed.
+ */
+function formatQueued(messages) {
+  const body = messages.map((m, i) => `[${i + 1}] ${String(m).trim()}`).join("\n\n");
+  return `Messages queued from the ARCS web UI, delivered at this checkpoint:\n\n${body}`;
+}
+
+async function main() {
+  const raw = await readStdin();
+  if (!raw.trim()) return;
+
+  const event = JSON.parse(raw);
+  const eventName = event?.hook_event_name;
+  const sessionId = event?.session_id;
+  if (!EVENTS.has(eventName) || typeof sessionId !== "string" || !sessionId) return;
+
+  const token = process.env.ARCS_HOOK_TOKEN;
+  const slug = process.env.ARCS_HOOK_SLUG;
+  if (!token || !slug) return;
+  const baseUrl = (process.env.ARCS_HOOK_URL || DEFAULT_URL).replace(/\/+$/, "");
+
+  const response = await fetch(`${baseUrl}/api/hook/${encodeURIComponent(slug)}/event`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      hook_event_name: eventName,
+      session_id: sessionId,
+      ...(typeof event.cwd === "string" && { cwd: event.cwd }),
+      ...(typeof event.source === "string" && { source: event.source }),
+      ...(typeof event.reason === "string" && { reason: event.reason }),
+      ...(typeof event.transcript_path === "string" && { transcript_path: event.transcript_path }),
+    }),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (!response.ok) return;
+
+  // Only UserPromptSubmit can inject context; the other events are pure
+  // notifications and answer with empty stdout.
+  if (eventName !== "UserPromptSubmit") return;
+
+  const envelope = await response.json();
+  const messages = envelope?.data?.queuedMessages;
+  if (!Array.isArray(messages) || messages.length === 0) return;
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: formatQueued(messages),
+      },
+    }),
+  );
+}
+
+// Belt and braces around the hard rule: even a bug in this file (or a stray
+// async rejection) must not surface as a non-zero exit for the user.
+process.on("uncaughtException", () => {
+  process.exitCode = 0;
+});
+process.on("unhandledRejection", () => {
+  process.exitCode = 0;
+});
+
+// No process.exit(): letting the event loop drain guarantees stdout is flushed
+// before the process ends, and the default exit code is already 0.
+main()
+  .catch(() => {})
+  .finally(() => {
+    process.exitCode = 0;
+  });

package/scripts/deploy-claudecode-bundle.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 // Deploy claudecode ARCS bundle from repo to Claude Code config.
 //
 // Direction: repo → config ONLY. Never writes config → repo.
@@ -8,7 +9,8 @@
 //   2. Skills tree       → <destination>/skills/arcs-<name>/...
 //      (Claude Code skills must be flat under skills/; we use the `arcs-`
 //       prefix as a namespace so orphan pruning never touches user skills.)
-//   3. Default agent     → settings.json `agent` field set to "arcs-orchestrate"
+//   3. Default agent     → settings.json `agent` field, resolved through the
+//      explicit DEFAULT_AGENT_PRECEDENCE list (default: "arcs-orchestrate")
 //
 // Env vars:
 //   DEPLOY_BUNDLE_ROOT   — override bundle root (default: opencode/arcs)
@@ -20,6 +22,7 @@
 // Outputs JSON to stdout: DeployResult
 // Exit code: 0 on success, 1 on error.
 
+import { createHash } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
@@ -32,7 +35,13 @@ import {
 import { homedir } from "node:os";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { wireCodegraphMcp, wireRtk } from "./lib/bundle-helpers.mjs";
+import {
+  isActiveAgentForMode,
+  isRetiredAgentForMode,
+  validateRetirementReplacements,
+  wireCodegraphMcp,
+  wireRtk,
+} from "./lib/bundle-helpers.mjs";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(scriptDir, "..");
@@ -67,9 +76,30 @@ const dryRun = process.env.DEPLOY_DRY_RUN !== "false";
 
 const destination = scope === "project" ? projectRoot : configRoot;
 
-const DEFAULT_AGENT = "arcs-orchestrate";
 const SKILL_PREFIX = "arcs-";
 
+function isPromptPath(value) {
+  if (typeof value !== "string" || value.includes("\\")) return false;
+  const segments = value.split("/");
+  return (
+    segments.length >= 2 &&
+    segments[0] === "prompts" &&
+    segments.slice(1).every((segment) => segment !== "" && segment !== "." && segment !== "..") &&
+    segments.at(-1).endsWith(".txt")
+  );
+}
+
+function resolveBundlePromptPath(value) {
+  if (!isPromptPath(value)) throw new Error(`Invalid bundle prompt path: ${value}`);
+  const promptsRoot = resolve(bundleRoot, "prompts");
+  const resolvedPath = resolve(promptsRoot, ...value.split("/").slice(1));
+  const relativePath = relative(promptsRoot, resolvedPath);
+  if (relativePath.split(/[\\/]/).includes("..")) {
+    throw new Error(`Bundle prompt path escapes prompts/: ${value}`);
+  }
+  return resolvedPath;
+}
+
 // ---------------------------------------------------------------------------
 // Model tier configuration
 // ---------------------------------------------------------------------------
@@ -81,102 +111,80 @@ const tierModels = {
   light: process.env.DEPLOY_MODEL_LIGHT || "inherit",
 };
 
-/** Maps each agent stem to a tier. Falls back to "standard". */
-const agentTierMap = {
-  "software-engineer": "heavy",
-  "docs-researcher": "heavy",
-  "arcs-docs": "heavy",
-  "oncall-ops": "heavy",
-  "arcs-orchestrate": "standard",
-  "arcs-orchestrate-caveman": "standard",
-  "devil-advocate": "standard",
-  "graph-explorer": "light",
-  "code-reviewer": "light",
-  "tech-architect": "light",
-};
+function readAgentRegistry() {
+  const manifestPath = resolve(bundleRoot, "manifest.json");
+  if (!existsSync(manifestPath)) throw new Error(`Agent registry not found at ${manifestPath}`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  if (!Array.isArray(manifest.agents))
+    throw new Error("Invalid agent registry: agents must be an array");
+
+  const ids = new Set();
+  const sources = new Set();
+  const destinations = new Set();
+  for (const agent of manifest.agents) {
+    const valid =
+      agent &&
+      typeof agent.id === "string" &&
+      /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent.id) &&
+      ["active", "retired"].includes(agent.status) &&
+      ["primary", "subagent"].includes(agent.kind) &&
+      ["heavy", "standard", "light"].includes(agent.tier) &&
+      Array.isArray(agent.modes) &&
+      agent.modes.length > 0 &&
+      agent.modes.every((mode) => ["opencode", "claudecode"].includes(mode)) &&
+      isPromptPath(agent.source) &&
+      isPromptPath(agent.destination) &&
+      typeof agent.description === "string" &&
+      agent.description.length > 0 &&
+      agent.permissions &&
+      ["allow", "deny"].includes(agent.permissions.edit) &&
+      ["allow", "deny"].includes(agent.permissions.bash) &&
+      ["allow", "deny"].includes(agent.permissions.webfetch) &&
+      ["allow", "deny"].includes(agent.permissions.mcp) &&
+      ["allow", "deny"].includes(agent.permissions.task);
+    if (!valid) throw new Error(`Invalid agent registry record: ${JSON.stringify(agent)}`);
+    if (ids.has(agent.id)) throw new Error(`Duplicate agent registry id: ${agent.id}`);
+    if (sources.has(agent.source))
+      throw new Error(`Duplicate agent registry source: ${agent.source}`);
+    if (destinations.has(agent.destination))
+      throw new Error(`Duplicate agent registry destination: ${agent.destination}`);
+    ids.add(agent.id);
+    sources.add(agent.source);
+    destinations.add(agent.destination);
+  }
+  validateRetirementReplacements(manifest.agents);
+  return manifest.agents;
+}
 
-// Agent descriptions mirror opencode/arcs/manifest.json (canonical) — keep in sync.
-const agentMetadata = {
-  "software-engineer": {
-    name: "Software Engineer",
-    description:
-      "Implementation specialist. Writes code, runs tests, ships features. Loads quick-dev, code-agent, test-driven-development, and executing-plans skills as needed.",
-    tools: "Read, Write, Edit, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "devil-advocate": {
-    name: "Devil's Advocate",
-    description:
-      "Adversarial phase-gate agent. Checks work at phase boundaries using KISS/YAGNI/DRY principles. Runs tests, reads diffs, delivers pass/block verdicts. Cannot edit code.",
-    tools: "Read, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "graph-explorer": {
-    name: "Graph Explorer",
-    description:
-      "DAG-first codebase and knowledge exploration specialist. Queries arcs search, related, and context first, then codegraph MCP code-intelligence tools, before falling back to raw file-system tools. Replaces vanilla explore for ARCS projects.",
-    tools: "Read, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "tech-architect": {
-    name: "Technical Architect",
-    description:
-      "Architecture and analysis specialist. Deep structural reasoning, refactor guidance, trade-off evaluation, and root cause analysis without making hasty edits.",
-    tools: "Read, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "code-reviewer": {
-    name: "Code Reviewer",
-    description:
-      "Reviews code changes for production readiness and catches correctness, maintainability, and testing issues.",
-    tools: "Read, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "arcs-docs": {
-    name: "ARCS Docs Specialist",
-    description:
-      "ARCS documentation specialist. Manages plans, knowledge entries, diagrams, and DAG health. Knows ARCS structure intimately.",
-    tools: "Read, Write, Edit, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "docs-researcher": {
-    name: "Docs Researcher",
-    description:
-      "Handles documentation writing, research synthesis, OCR-adjacent extraction, and document-heavy analysis tasks.",
-    tools: "Read, Write, Edit, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "oncall-ops": {
-    name: "On-Call Ops",
-    description:
-      "Debugging and diagnosis specialist. Finds root causes through systematic investigation, log triage, bisect, and performance profiling.",
-    tools: "Read, Write, Edit, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "arcs-orchestrate": {
-    name: "ARCS Orchestrator",
-    description:
-      "The central coordinator for executing plans, managing agent dispatch, and handling DAG workflows.",
-    // Task is required: orchestrators dispatch sub-agents. Omitting it leaves
-    // the delegator with no way to delegate.
-    tools: "Task, Read, Write, Edit, Glob, Grep, Bash",
-    model: "inherit",
-  },
-  "arcs-orchestrate-caveman": {
-    name: "ARCS Orchestrator (Caveman)",
-    description:
-      "A terse, high-efficiency orchestrator that drives tasks without extra commentary.",
-    // Task is required: orchestrators dispatch sub-agents. Omitting it leaves
-    // the delegator with no way to delegate.
-    tools: "Task, Read, Write, Edit, Glob, Grep, Bash",
-    model: "inherit",
-  },
-};
+function claudeTools(agent) {
+  const tools = [];
+  if (agent.permissions.task === "allow") tools.push("Task");
+  tools.push("Read");
+  if (agent.permissions.edit === "allow") tools.push("Write", "Edit");
+  tools.push("Glob", "Grep");
+  if (agent.permissions.bash === "allow") tools.push("Bash");
+  return tools.join(", ");
+}
 
 function ensureParentDir(filePath) {
   mkdirSync(dirname(filePath), { recursive: true });
 }
 
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function readInstalledManifest() {
+  const manifestPath = resolve(destination, configRelativePath(".arcs-bundle.json"));
+  if (!existsSync(manifestPath)) return null;
+  try {
+    const value = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    return value?.bundleId === "arcs-claudecode-bundle" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 function configRelativePath(suffix) {
   return scope === "project" ? `.claude/${suffix}` : suffix;
 }
@@ -204,26 +212,23 @@ function buildAgentSources() {
     throw new Error(`Prompts directory not found at ${promptsDir}`);
   }
 
-  const promptFiles = readdirSync(promptsDir).filter((f) => f.endsWith(".txt"));
-  const sources = [];
-
+  const registry = readAgentRegistry();
+  const registeredSources = new Set(registry.map((agent) => agent.source));
+  const promptFiles = readdirSync(promptsDir).filter((file) => file.endsWith(".txt"));
   for (const file of promptFiles) {
-    const stem = file.slice(0, -4);
-    const sourcePath = resolve(promptsDir, file);
-    const promptContent = readFileSync(sourcePath, "utf-8");
+    const source = `prompts/${file}`;
+    if (!registeredSources.has(source)) throw new Error(`Unregistered prompt file: ${source}`);
+  }
 
-    const meta = agentMetadata[stem] || {
-      name: stem
-        .split("-")
-        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-        .join(" "),
-      description: `ARCS ${stem} agent.`,
-      tools: "Read, Write, Edit, Glob, Grep, Bash",
-      model: "inherit",
-    };
+  const sources = [];
 
-    const tier = agentTierMap[stem] || "standard";
-    const model = tierModels[tier];
+  for (const agent of registry.filter((record) => isActiveAgentForMode(record, "claudecode"))) {
+    const stem = agent.id;
+    const sourcePath = resolveBundlePromptPath(agent.source);
+    if (!existsSync(sourcePath))
+      throw new Error(`Registered agent prompt not found: ${agent.source}`);
+    const promptContent = readFileSync(sourcePath, "utf-8");
+    const model = tierModels[agent.tier];
 
     // Claude Code requires `name` to be a kebab-case identifier (lowercase
     // letters + hyphens). The filename stem already satisfies this and is
@@ -231,17 +236,12 @@ function buildAgentSources() {
     // `description`. The default-agent setting (DEFAULT_AGENT) references this
     // same stem, so it resolves. Display names with spaces/parens/apostrophes
     // (meta.name) are invalid here and caused intermittent init failures.
-    const toolsCsv = meta.tools
-      .split(",")
-      .map((t) => t.trim())
-      .join(", ");
-
     const compiledContent = [
       "---",
       `name: ${stem}`,
-      `description: ${meta.description}`,
+      `description: ${agent.description}`,
       `model: ${model}`,
-      `tools: ${toolsCsv}`,
+      `tools: ${claudeTools(agent)}`,
       "---",
       "",
       promptContent,
@@ -289,7 +289,29 @@ function buildSkillSources() {
 // 3. settings.json merge — set default agent
 // ---------------------------------------------------------------------------
 
+// Which primary becomes the deployed default is an explicit, ordered policy —
+// never "whichever active primary happens to come first in manifest.json".
+// Registry array order must not be able to promote an agent: a new primary
+// (e.g. the speed-optimized arcs-flash) becomes eligible only by being listed
+// here, and only at the rank it is listed at. Earlier entries always win, so a
+// lower-ranked primary is a fallback, never a silent replacement.
+const DEFAULT_AGENT_PRECEDENCE = ["arcs-orchestrate", "arcs-orchestrate-caveman", "arcs-flash"];
+
+function selectDefaultAgent(registry) {
+  for (const id of DEFAULT_AGENT_PRECEDENCE) {
+    const agent = registry.find((record) => record.id === id);
+    if (agent && agent.kind === "primary" && isActiveAgentForMode(agent, "claudecode")) {
+      return agent;
+    }
+  }
+  throw new Error(
+    `No active Claude Code primary agent in default precedence: ${DEFAULT_AGENT_PRECEDENCE.join(", ")}`,
+  );
+}
+
 function planSettingsUpdate() {
+  const defaultAgent = selectDefaultAgent(readAgentRegistry());
+
   const settingsConfigRelative = configRelativePath("settings.json");
   const settingsAbsolute = resolve(destination, settingsConfigRelative);
 
@@ -308,7 +330,7 @@ function planSettingsUpdate() {
     }
   }
 
-  const merged = { ...parsed, agent: DEFAULT_AGENT };
+  const merged = { ...parsed, agent: defaultAgent.id };
   const serialized = `${JSON.stringify(merged, null, 2)}\n`;
 
   let status;
@@ -328,6 +350,8 @@ function planSettingsUpdate() {
 // ---------------------------------------------------------------------------
 
 function main() {
+  const registry = readAgentRegistry();
+  const previousManifest = readInstalledManifest();
   const agentSources = buildAgentSources();
   const skillSources = buildSkillSources();
   const settingsPlan = planSettingsUpdate();
@@ -375,20 +399,6 @@ function main() {
   // Orphans
   const filesRemoved = [];
 
-  // Agent orphans — only `.md` files whose stem we recognize from agentMetadata
-  const agentsTargetDir = resolve(destination, configRelativePath("agents"));
-  const activeAgentStems = new Set(agentSources.map((f) => f.stem));
-  if (existsSync(agentsTargetDir)) {
-    for (const entry of readdirSync(agentsTargetDir, { withFileTypes: true })) {
-      if (entry.isFile() && entry.name.endsWith(".md")) {
-        const stem = entry.name.slice(0, -3);
-        if (agentMetadata[stem] && !activeAgentStems.has(stem)) {
-          filesRemoved.push(configRelativePath(`agents/${entry.name}`));
-        }
-      }
-    }
-  }
-
   // Skill orphans — only `arcs-*/` directories that aren't in current source.
   // The prefix gives us a safe namespace; foreign user skills are never touched.
   const skillsTargetDir = resolve(destination, configRelativePath("skills"));
@@ -405,6 +415,22 @@ function main() {
     }
   }
 
+  const retiredById = new Map(
+    registry
+      .filter((agent) => isRetiredAgentForMode(agent, "claudecode"))
+      .map((agent) => [agent.id, agent]),
+  );
+  for (const ownership of previousManifest?.agents ?? []) {
+    const retired = retiredById.get(ownership.id);
+    if (!retired) continue;
+    const expectedDestination = configRelativePath(`agents/${retired.id}.md`);
+    if (ownership.promptDestination !== expectedDestination) continue;
+    const installedPath = resolve(destination, ownership.promptDestination);
+    if (existsSync(installedPath) && sha256(readFileSync(installedPath)) === ownership.sourceHash) {
+      filesRemoved.push(ownership.promptDestination);
+    }
+  }
+
   // Pass 2: Write if not dry-run
   if (!dryRun) {
     for (const { compiledContent, configRelative } of agentSources) {
@@ -432,6 +458,33 @@ function main() {
         rmSync(abs, { recursive: isDir, force: true });
       }
     }
+
+    const installedManifestPath = resolve(destination, configRelativePath(".arcs-bundle.json"));
+    ensureParentDir(installedManifestPath);
+    writeFileSync(
+      installedManifestPath,
+      `${JSON.stringify(
+        {
+          bundleId: "arcs-claudecode-bundle",
+          installMode: `claudecode-${scope}`,
+          sourceBundleVersion: "deploy-script",
+          sourceBundleHash: sha256(readFileSync(resolve(bundleRoot, "manifest.json"))),
+          installedAt: new Date().toISOString(),
+          // Persisted so a later `arcs init` can reuse the previous tier
+          // selection instead of re-prompting for it.
+          tierModels,
+          ownedPaths: [],
+          agents: agentSources.map((agent) => ({
+            id: agent.stem,
+            promptDestination: agent.configRelative,
+            sourceHash: sha256(agent.compiledContent),
+          })),
+        },
+        null,
+        2,
+      )}\n`,
+      "utf-8",
+    );
   }
 
   // Best-effort: wire the codegraph MCP server. Skipped on dry-run; never fatal.