@rryando/arcs 3.10.0 → 4.0.0

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

@@ -0,0 +1,171 @@
+#!/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.
+ *
+ * Two of the four can put text in front of the model: SessionStart mirrors
+ * ARCS's staged environment (project, workspace, DAG position) into the new
+ * session, and UserPromptSubmit delivers messages queued from the web UI. Both
+ * emit Claude Code's `hookSpecificOutput` envelope on stdout; the other two
+ * print nothing.
+ *
+ * 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)
+ */
+
+// DEFAULT_URL and EVENTS are literals on purpose: this file runs standalone out
+// of the user's settings.json and importing ARCS would give the HARD RULE above
+// a way to fail. `src/utils/hook-contract.ts` owns the same two values for the
+// TypeScript side, and `test/hook-contract-parity.test.ts` parses THIS source
+// and fails if the two ever diverge — so keep the shapes greppable: a
+// double-quoted DEFAULT_URL, and a flat `new Set([...])` of string literals.
+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"]);
+/**
+ * Refusal bound on a context block the server sends, in characters.
+ *
+ * The server caps the SessionStart block at 2500 (`SESSION_START_STAGE_CAP` in
+ * `src/web-server/routes/hook-events.ts`); this is the CLIENT's own limit, so a
+ * misbehaving, mismatched or hostile ARCS cannot shove an unbounded body into
+ * the head of the user's live session. Over the bound the block is dropped
+ * whole rather than clipped — a clip would sever a wrapper's closing delimiter.
+ * `test/claude-code-hook-script.test.ts` parses this literal and fails if the
+ * server's cap ever climbs above it, so the two cannot silently cross.
+ */
+const MAX_CONTEXT_CHARS = 4000;
+
+/** 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;
+
+  // Two events can inject context: SessionStart mirrors ARCS's staged
+  // environment into the fresh session, UserPromptSubmit delivers whatever the
+  // web UI queued. SessionEnd and Stop are pure notifications and answer with
+  // empty stdout.
+  if (eventName !== "SessionStart" && eventName !== "UserPromptSubmit") return;
+
+  const envelope = await response.json();
+
+  if (eventName === "SessionStart") {
+    const staged = envelope?.data?.stagedContext;
+    // Every rejection here is a silent no-op, never a repair: an absent field,
+    // a non-string, an empty string and an oversized body all mean "ARCS has
+    // nothing usable to stage", and the session proceeds exactly as if the
+    // bridge were not installed.
+    if (typeof staged !== "string" || staged === "" || staged.length > MAX_CONTEXT_CHARS) return;
+
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: staged,
+        },
+      }),
+    );
+    return;
+  }
+
+  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,9 @@
 //   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 from an
+//      explicit DEPLOY_PRIMARY_AGENT selection, else through the
+//      DEFAULT_AGENT_PRECEDENCE list (default: "arcs-orchestrate")
 //
 // Env vars:
 //   DEPLOY_BUNDLE_ROOT   — override bundle root (default: opencode/arcs)
@@ -16,10 +19,13 @@
 //   DEPLOY_PROJECT_ROOT  — override project root (default: repository root)
 //   DEPLOY_SCOPE         — `global` or `project` (default: `global`)
 //   DEPLOY_DRY_RUN       — "false" to actually write; anything else = dry-run (default: dry-run)
+//   DEPLOY_PRIMARY_AGENT — user-selected default primary agent id; empty/unset falls
+//                          back to DEFAULT_AGENT_PRECEDENCE
 //
 // Outputs JSON to stdout: DeployResult
 // Exit code: 0 on success, 1 on error.
 
+import { createHash } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
@@ -32,7 +38,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 +79,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 +114,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 +215,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 +239,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 +292,47 @@ 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 isSelectablePrimary(agent) {
+  return Boolean(agent) && agent.kind === "primary" && isActiveAgentForMode(agent, "claudecode");
+}
+
+function selectDefaultAgent(registry) {
+  // An explicit user selection outranks the pinned precedence — but only when it
+  // names a real Claude-Code-active primary. A user who asked for X must never
+  // silently get Y, so an unusable selection hard-fails instead of degrading
+  // into the precedence walk.
+  const requestedId = (process.env.DEPLOY_PRIMARY_AGENT ?? "").trim();
+  if (requestedId !== "") {
+    const requested = registry.find((record) => record.id === requestedId);
+    if (isSelectablePrimary(requested)) return requested;
+    const selectable = registry.filter(isSelectablePrimary).map((record) => record.id);
+    throw new Error(
+      `DEPLOY_PRIMARY_AGENT "${requestedId}" is not an active Claude Code primary agent. Selectable: ${selectable.join(", ") || "(none)"}`,
+    );
+  }
+
+  for (const id of DEFAULT_AGENT_PRECEDENCE) {
+    const agent = registry.find((record) => record.id === id);
+    if (isSelectablePrimary(agent)) {
+      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 +351,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 +371,8 @@ function planSettingsUpdate() {
 // ---------------------------------------------------------------------------
 
 function main() {
+  const registry = readAgentRegistry();
+  const previousManifest = readInstalledManifest();
   const agentSources = buildAgentSources();
   const skillSources = buildSkillSources();
   const settingsPlan = planSettingsUpdate();
@@ -375,20 +420,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 +436,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 +479,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.