arcane-cli 1.12.0 → 1.12.2

package/dist/index.js

@@ -6,25 +6,296 @@ const require = __createRequire(import.meta.url);
 import { Command } from "commander";
 import { createRequire as createRequire3 } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname12, join as join22 } from "path";
+import { dirname as dirname13, join as join23 } from "path";
 
 // src/commands/init.ts
 import { select as select3, confirm as confirm2, input as input3 } from "@inquirer/prompts";
-import { dirname as dirname4, join as join7 } from "path";
+import { dirname as dirname5, join as join8 } from "path";
 import chalk2 from "chalk";
 
 // src/modules/copier.ts
 import {
   mkdir,
   access,
+  lstat,
   readdir,
   readFile,
   rm,
   rmdir,
+  unlink,
   writeFile
 } from "fs/promises";
 import { createHash } from "crypto";
 import path from "path";
+
+// src/modules/git.ts
+import { execFile } from "child_process";
+var GitTimeoutError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "GitTimeoutError";
+  }
+};
+var NETWORK_SUBCOMMANDS = /* @__PURE__ */ new Set(["fetch", "pull", "push", "clone", "ls-remote", "send-email"]);
+var WRITE_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "init",
+  "commit",
+  "add",
+  "checkout",
+  "switch",
+  "merge",
+  "rebase",
+  "reset",
+  "tag",
+  "mv",
+  "rm",
+  "cherry-pick",
+  "revert",
+  "stash",
+  "apply",
+  "am",
+  "restore",
+  "submodule",
+  "sparse-checkout",
+  "maintenance",
+  "notes"
+]);
+var AMBIGUOUS_AS_WRITE = /* @__PURE__ */ new Set(["branch", "config", "remote", "worktree"]);
+var READ_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "status",
+  "rev-parse",
+  "log",
+  "diff",
+  "show",
+  "describe",
+  "cat-file",
+  "ls-files",
+  "ls-tree",
+  "symbolic-ref",
+  "show-ref",
+  "for-each-ref",
+  "merge-base",
+  "blame",
+  "shortlog",
+  "grep",
+  "reflog",
+  "diff-tree",
+  "rev-list",
+  "name-rev",
+  "count-objects",
+  "verify-commit",
+  "verify-tag",
+  "help",
+  "version"
+]);
+var GLOBAL_FLAGS_WITH_SEPARATE_VALUE = /* @__PURE__ */ new Set(["-c", "-C"]);
+var DEFAULT_TIMEOUTS_MS = {
+  read: 15e3,
+  write: 3e4,
+  network: 12e4
+};
+function classifyGitCommand(args) {
+  let subcommand;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (GLOBAL_FLAGS_WITH_SEPARATE_VALUE.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-")) continue;
+    subcommand = arg;
+    break;
+  }
+  if (!subcommand) return "read";
+  if (NETWORK_SUBCOMMANDS.has(subcommand)) return "network";
+  if (WRITE_SUBCOMMANDS.has(subcommand) || AMBIGUOUS_AS_WRITE.has(subcommand)) return "write";
+  if (READ_SUBCOMMANDS.has(subcommand)) return "read";
+  return "write";
+}
+function buildGitEnv() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: "0",
+    GCM_INTERACTIVE: "Never",
+    GIT_OPTIONAL_LOCKS: "0"
+  };
+}
+function runGit(cwd, args, options = {}) {
+  const commandClass = options.commandClass ?? classifyGitCommand(args);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUTS_MS[commandClass] ?? DEFAULT_TIMEOUTS_MS.write;
+  return new Promise((resolve6, reject) => {
+    const child = execFile(
+      "git",
+      args,
+      {
+        cwd,
+        env: buildGitEnv(),
+        timeout: timeoutMs,
+        // SIGTERM (Node's default) rather than SIGKILL: gives git a chance
+        // to run its own cleanup on POSIX, relevant to EF-20's own concern
+        // about a killed operation leaving refs/locks in an uncertain state.
+        // Moot on Windows -- Node docs: both map to an abrupt TerminateProcess
+        // there -- but this module isn't Windows-gated.
+        killSignal: "SIGTERM",
+        windowsHide: true,
+        encoding: "utf8"
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          if (error.killed) {
+            reject(
+              new GitTimeoutError(
+                // NOTE: embeds the raw args, including any secrets a future
+                // network-class caller might pass (e.g. a credentialed
+                // clone URL). No current caller does; redact before one does.
+                `git ${args.join(" ")} timed out after ${timeoutMs}ms (class: ${commandClass})`,
+                { cause: error }
+              )
+            );
+            return;
+          }
+          reject(error);
+          return;
+        }
+        resolve6({ stdout, stderr });
+      }
+    );
+    child.stdin?.end();
+  });
+}
+async function inspectGitRepository(cwd) {
+  try {
+    const { stdout: stdout2 } = await runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
+    if (stdout2.trim() !== "true") {
+      return { status: "not-repository" };
+    }
+  } catch {
+    return { status: "not-repository" };
+  }
+  try {
+    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+  } catch {
+    return { status: "no-commits" };
+  }
+  const { stdout } = await runGit(cwd, ["status", "--porcelain", "-uall"]);
+  const lines = stdout.trim();
+  return {
+    status: "ready",
+    uncommittedChanges: lines.length === 0 ? 0 : lines.split("\n").length
+  };
+}
+async function correctUnbornMasterDefault(cwd) {
+  let current;
+  try {
+    const { stdout } = await runGit(cwd, ["symbolic-ref", "--short", "HEAD"]);
+    current = stdout.trim();
+  } catch {
+    return { corrected: false, to: "main" };
+  }
+  if (current !== "master") {
+    return { corrected: false, to: "main" };
+  }
+  try {
+    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+    return { corrected: false, to: "main" };
+  } catch {
+  }
+  let mainRef;
+  try {
+    mainRef = await runGit(cwd, ["for-each-ref", "--format=%(objectname)", "refs/heads/main"]);
+  } catch {
+    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  }
+  if (mainRef.stdout.trim() !== "") {
+    return { corrected: false, to: "main" };
+  }
+  if (mainRef.stderr.trim() !== "") {
+    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  }
+  try {
+    await runGit(cwd, ["symbolic-ref", "-q", "refs/heads/main"]);
+    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  } catch (error) {
+    if (error.code !== 1) {
+      return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+    }
+  }
+  await runGit(cwd, ["symbolic-ref", "HEAD", "refs/heads/main"]);
+  return { corrected: true, from: current, to: "main" };
+}
+async function ensureLocalPullRebase(cwd) {
+  let rawLocalValue;
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--get", "pull.rebase"]);
+    rawLocalValue = stdout.trim();
+  } catch {
+    rawLocalValue = void 0;
+  }
+  if (rawLocalValue === void 0) {
+    await runGit(cwd, ["config", "--local", "pull.rebase", "true"]);
+    return { action: "set" };
+  }
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--type=bool", "--get", "pull.rebase"]);
+    if (stdout.trim() === "false") {
+      return { action: "explicit-false-preserved" };
+    }
+    return { action: "already-set" };
+  } catch {
+    return { action: "already-set" };
+  }
+}
+async function listSymlinkTrackedPaths(cwd) {
+  const paths = /* @__PURE__ */ new Set();
+  let stdout;
+  try {
+    ({ stdout } = await runGit(cwd, ["ls-files", "-s", "-z"]));
+  } catch {
+    return paths;
+  }
+  for (const entry of stdout.split("\0")) {
+    const tab = entry.indexOf("	");
+    if (tab < 0) continue;
+    const [mode] = entry.slice(0, tab).split(" ");
+    if (mode === "120000") paths.add(entry.slice(tab + 1));
+  }
+  return paths;
+}
+async function recordRegularFileInIndex(cwd, relativePath) {
+  const { stdout } = await runGit(cwd, ["hash-object", "-w", "--", relativePath]);
+  const { stdout: prefix } = await runGit(cwd, ["rev-parse", "--show-prefix"]);
+  const rootRelative = `${prefix.trim()}${relativePath.replace(/\\/g, "/")}`;
+  await runGit(cwd, ["update-index", "--add", "--cacheinfo", `100644,${stdout.trim()},${rootRelative}`]);
+}
+async function isUneditedTrackedFile(cwd, relativePath) {
+  let status;
+  try {
+    ({ stdout: status } = await runGit(cwd, ["status", "--porcelain", "-z", "--", relativePath]));
+  } catch {
+    return { verdict: "unknown", detail: "not a git repository, or git is unavailable" };
+  }
+  if (status.startsWith("??")) return { verdict: "untracked", detail: "git does not track it" };
+  if (status.length > 0) return { verdict: "edited", detail: "it has uncommitted changes" };
+  try {
+    const { stdout: shallow } = await runGit(cwd, ["rev-parse", "--is-shallow-repository"]);
+    if (shallow.trim() === "true") {
+      return { verdict: "unknown", detail: "this is a shallow clone, so the history is truncated" };
+    }
+  } catch {
+  }
+  let log;
+  try {
+    ({ stdout: log } = await runGit(cwd, ["log", "--format=%H", "--", relativePath]));
+  } catch {
+    return { verdict: "unknown", detail: "git log could not read its history" };
+  }
+  const commits = log.split("\n").filter(Boolean).length;
+  if (commits === 0) return { verdict: "untracked", detail: "no commit contains it" };
+  if (commits > 1) return { verdict: "edited", detail: `${commits} commits touched it` };
+  return { verdict: "unedited", detail: "tracked, clean, and added by its only commit" };
+}
+
+// src/modules/copier.ts
 function normalizeLineEndings(content) {
   if (!content.includes(13)) return content;
   const out = Buffer.allocUnsafe(content.length);
@@ -72,7 +343,52 @@ async function fileExists(filePath) {
     return false;
   }
 }
-async function copyFile(srcPath, targetDir, relativePath, opts = {}) {
+async function replaceSymlinkedDestination(destPath, relativePath, opts) {
+  let isLink;
+  try {
+    isLink = (await lstat(destPath)).isSymbolicLink();
+  } catch {
+    return null;
+  }
+  if (isLink) {
+    await unlink(destPath);
+    return "symlink";
+  }
+  if (opts.linkTracked?.has(relativePath.replace(/\\/g, "/"))) {
+    await unlink(destPath);
+    return "index-symlink";
+  }
+  return null;
+}
+function looksLikeBarePath(body) {
+  const trimmed = body.trim();
+  return trimmed.length <= 512 && /^\.{1,2}\/\S+$/.test(trimmed) && !trimmed.includes("://");
+}
+async function managedPathLinkShape(targetDir, relativePath, linkTracked, bodyHeuristic) {
+  const destPath = path.resolve(targetDir, relativePath);
+  try {
+    if ((await lstat(destPath)).isSymbolicLink()) return "symlink";
+  } catch {
+    return null;
+  }
+  if (linkTracked?.has(relativePath.replace(/\\/g, "/"))) return "index-symlink";
+  if (!bodyHeuristic) return null;
+  try {
+    return looksLikeBarePath(await readFile(destPath, "utf-8")) ? "path-body" : null;
+  } catch {
+    return null;
+  }
+}
+async function writeManagedFile(targetDir, relativePath, content, opts = {}) {
+  validateTargetPath(targetDir, relativePath);
+  const destPath = path.resolve(targetDir, relativePath);
+  await ensureDir(path.dirname(destPath));
+  const shape = await replaceSymlinkedDestination(destPath, relativePath, opts);
+  await writeFile(destPath, content);
+  if (shape === "index-symlink") await recordRegularFileInIndex(targetDir, relativePath);
+  if (shape !== null) opts.conversions?.push({ file: relativePath, shape });
+}
+async function copyFile(srcPath, targetDir, relativePath, opts = {}) {
   validateTargetPath(targetDir, relativePath);
   const destPath = path.resolve(targetDir, relativePath);
   await ensureDir(path.dirname(destPath));
@@ -83,7 +399,7 @@ async function copyFile(srcPath, targetDir, relativePath, opts = {}) {
   }
   const content = await readFile(srcPath);
   const hash = hashContent(content);
-  await writeFile(destPath, content);
+  await writeManagedFile(targetDir, relativePath, content, opts);
   return hash;
 }
 async function removeWithin(targetDir, relativePath) {
@@ -976,7 +1292,7 @@ function listProfiles() {
 }
 
 // src/modules/user-tier.ts
-import { lstat, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm as rm2, rmdir as rmdir2, writeFile as writeFile3 } from "fs/promises";
+import { lstat as lstat2, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm as rm2, rmdir as rmdir2, writeFile as writeFile3 } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
 
@@ -1192,7 +1508,7 @@ async function renderUserFanout(storeRoot, spellIds, fallbackDir) {
 }
 async function classifyTarget(path4) {
   try {
-    const stats = await lstat(path4);
+    const stats = await lstat2(path4);
     return stats.isFile() ? "file" : "other";
   } catch (err) {
     if (err.code === "ENOENT") return "absent";
@@ -1417,7 +1733,7 @@ var WORDMARK = [
 var INDENT = "  ";
 var LOCKUP_WIDTH = INDENT.length + Math.max(...WORDMARK.map((l) => l.length));
 function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve6) => setTimeout(resolve6, ms));
 }
 function isAnimatable() {
   return !!process.stdout.isTTY && process.env["TERM"] !== "dumb" && process.env["CI"] !== "true" && process.env["ARCANE_DISABLE_ANIMATION"] !== "true" && (process.stdout.columns ?? 80) >= LOCKUP_WIDTH;
@@ -2194,7 +2510,10 @@ ${rules}
 **Denied:** ${def.tools.denied.join(", ")}
 `;
 }
-function renderSpellRoutingSection() {
+function renderSpellRoutingSection(spellScope) {
+  const userTierRule = spellScope === "user" ? `
+This repository takes its spells from the user tier (\`~/.arcane\`), not from files it carries. If a spell named here does not resolve for your client, stop and say that \`spell init --user\` is needed on this machine; do not improvise the workflow from general knowledge.
+` : "";
   return `## Spell Routing
 
 | When you're about to... | Invoke |
@@ -2208,7 +2527,7 @@ function renderSpellRoutingSection() {
 | Review code or a PR | \`spell-review\` |
 
 If a spell exists for the workflow you are about to perform, invoke it \u2014 do not improvise the workflow from general knowledge, even when the user doesn't name the spell.
-`;
+${userTierRule}`;
 }
 async function loadBranchNamingFragment(assetsDir) {
   try {
@@ -2370,7 +2689,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       unmanagedAgentFiles.push(...await existingAgentFiles(agentsDir));
     }
     if (!userTier) {
-      const copilotSection = `${renderSpellRoutingSection()}
+      const copilotSection = `${renderSpellRoutingSection(options.spellScope)}
 ${branchNaming}${renderAgentRosterSection(resolved)}`;
       const copilotMerged = await mergeIntoFile(
         targetDir,
@@ -2386,7 +2705,7 @@ ${branchNaming}${renderAgentRosterSection(resolved)}`;
     return { synced, skipped, hasUnresolvedRoles, userAgentFiles, unmanagedAgentFiles };
   }
   if (options.claude !== false) {
-    const claudeSection = `${renderSpellRoutingSection()}
+    const claudeSection = `${renderSpellRoutingSection(options.spellScope)}
 ${branchNaming}${renderAgentRosterSection(resolved)}`;
     const claudeMerged = await mergeIntoFile(
       targetDir,
@@ -2397,7 +2716,7 @@ ${branchNaming}${renderAgentRosterSection(resolved)}`;
     if (claudeMerged) synced.push("CLAUDE.md (agents section)");
   }
   if (options.codex !== false) {
-    const codexSection = `${renderSpellRoutingSection()}
+    const codexSection = `${renderSpellRoutingSection(options.spellScope)}
 ${branchNaming}${renderAgentRosterSection(resolved)}`;
     const codexMerged = await mergeIntoFile(
       targetDir,
@@ -2604,374 +2923,156 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   }
   for (const roleId of selectedRoleIds) {
     const src = join4(assetsDir, "agents", `${roleId}.yaml`);
-    const dest = join4(arcaneDir, `${roleId}.yaml`);
-    if (!options.dryRun) {
-      try {
-        await copyFile2(src, dest);
-      } catch {
-        console.warn(`  ! Could not copy definition for "${roleId}" \u2014 skipping`);
-      }
-    } else {
-      console.log(`  [dry-run] Would copy: ${label2}/agents/${roleId}.yaml`);
-    }
-  }
-  if (options.dryRun) {
-    console.log(
-      `
-  [dry-run] Would initialize roster with ${selectedRoleIds.length} agents`
-    );
-    return;
-  }
-  printStep("Syncing agent definitions to all clients...");
-  const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
-    targetDir,
-    assetsDir,
-    roster,
-    { dryRun: false, scope }
-  );
-  printSuccess("Agent roster initialized");
-  console.log(`    \u{1F4CB} Profile: ${profileId} \xB7 Naming: ${namingStrategy} \xB7 Agents: ${rosterEntries.length}`);
-  console.log(
-    `    \u{1F504} Synced: ${synced.length} outputs (${scope === "user" ? "agent personas in ~/.claude/agents" : "Copilot, Claude, Codex, OpenClaw"})`
-  );
-  if (skipped.length > 0) {
-    console.log(`    \u26A0\uFE0F  Skipped: ${skipped.length} (${skipped.join(", ")})`);
-  }
-  console.log();
-  console.log(
-    `    \u{1F4A1} Customize: edit ${label2}/agents.yaml \u2192 spell agents sync${scope === "user" ? " --user" : ""}`
-  );
-  console.log();
-  if (hasUnresolvedRoles) {
-    console.error(
-      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
-    );
-    process.exitCode = 1;
-  }
-}
-async function runAgentsSync(options, targetDir, assetsDir) {
-  const scope = options.scope ?? "repo";
-  let roster;
-  let definitionsDir;
-  let fromUserTier = false;
-  try {
-    ({ roster, definitionsDir, fromUserTier } = await resolveRoster(targetDir, scope));
-  } catch (err) {
-    if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
-      console.error(err.message);
-      process.exit(1);
-      return;
-    }
-    throw err;
-  }
-  if (options.dryRun) {
-    console.log("\n  [dry-run] Would sync agents from roster:\n");
-  } else {
-    console.log("\n  Syncing agents...\n");
-  }
-  if (fromUserTier && scope === "repo") {
-    console.log(
-      "  This repository has no roster of its own and takes its spells from the user tier,\n  so its roster tables are built from ~/.arcane/agents.yaml.\n"
-    );
-  }
-  const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
-    targetDir,
-    assetsDir,
-    roster,
-    { ...options, scope, ...definitionsDir === void 0 ? {} : { definitionsDir } }
-  );
-  if (options.dryRun) {
-    console.log(`
-  [dry-run] ${synced.length} outputs would be generated`);
-    return;
-  }
-  console.log(`
-  \u2713 Synced ${synced.length} outputs`);
-  for (const item of synced) {
-    console.log(`    + ${item}`);
-  }
-  if (skipped.length > 0) {
-    console.log(`
-  ! Skipped ${skipped.length}:`);
-    for (const item of skipped) {
-      console.log(`    - ${item}`);
-    }
-  }
-  console.log();
-  if (hasUnresolvedRoles) {
-    console.error(
-      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
-    );
-    process.exitCode = 1;
-  }
-}
-async function runAgentsList(targetDir, scope = "repo") {
-  let roster;
-  try {
-    roster = await loadRoster(targetDir, scope);
-  } catch (err) {
-    if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
-      console.error(err.message);
-      process.exit(1);
-      return;
-    }
-    throw err;
-  }
-  const nameWidth = Math.max(
-    "Name".length,
-    ...roster.roster.map((e) => (e.name ?? e.definition).length)
-  );
-  const defWidth = Math.max(
-    "Role ID".length,
-    ...roster.roster.map((e) => e.definition.length)
-  );
-  const idWidth = Math.max(
-    "OpenClaw ID".length,
-    ...roster.roster.map((e) => e.id.length)
-  );
-  const pad = (s, n) => s.padEnd(n);
-  console.log(
-    `
-  Profile: ${roster.agent_profile}  |  Naming: ${roster.naming_strategy}  |  Agents: ${roster.roster.length}
-`
-  );
-  console.log(
-    `  ${pad("Name", nameWidth)}  ${pad("Role ID", defWidth)}  ${pad("OpenClaw ID", idWidth)}`
-  );
-  console.log(
-    `  ${"-".repeat(nameWidth)}  ${"-".repeat(defWidth)}  ${"-".repeat(idWidth)}`
-  );
-  for (const entry of roster.roster) {
-    console.log(
-      `  ${pad(entry.name ?? "(unnamed)", nameWidth)}  ${pad(entry.definition, defWidth)}  ${pad(entry.id, idWidth)}`
-    );
-  }
-  console.log();
-}
-
-// src/modules/hub.ts
-import { confirm, select as select2, input as input2 } from "@inquirer/prompts";
-import { readdir as readdir5, writeFile as writeFile7 } from "fs/promises";
-import { join as join5 } from "path";
-
-// src/modules/git.ts
-import { execFile } from "child_process";
-var GitTimeoutError = class extends Error {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "GitTimeoutError";
-  }
-};
-var NETWORK_SUBCOMMANDS = /* @__PURE__ */ new Set(["fetch", "pull", "push", "clone", "ls-remote", "send-email"]);
-var WRITE_SUBCOMMANDS = /* @__PURE__ */ new Set([
-  "init",
-  "commit",
-  "add",
-  "checkout",
-  "switch",
-  "merge",
-  "rebase",
-  "reset",
-  "tag",
-  "mv",
-  "rm",
-  "cherry-pick",
-  "revert",
-  "stash",
-  "apply",
-  "am",
-  "restore",
-  "submodule",
-  "sparse-checkout",
-  "maintenance",
-  "notes"
-]);
-var AMBIGUOUS_AS_WRITE = /* @__PURE__ */ new Set(["branch", "config", "remote", "worktree"]);
-var READ_SUBCOMMANDS = /* @__PURE__ */ new Set([
-  "status",
-  "rev-parse",
-  "log",
-  "diff",
-  "show",
-  "describe",
-  "cat-file",
-  "ls-files",
-  "ls-tree",
-  "symbolic-ref",
-  "show-ref",
-  "for-each-ref",
-  "merge-base",
-  "blame",
-  "shortlog",
-  "grep",
-  "reflog",
-  "diff-tree",
-  "rev-list",
-  "name-rev",
-  "count-objects",
-  "verify-commit",
-  "verify-tag",
-  "help",
-  "version"
-]);
-var GLOBAL_FLAGS_WITH_SEPARATE_VALUE = /* @__PURE__ */ new Set(["-c", "-C"]);
-var DEFAULT_TIMEOUTS_MS = {
-  read: 15e3,
-  write: 3e4,
-  network: 12e4
-};
-function classifyGitCommand(args) {
-  let subcommand;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (GLOBAL_FLAGS_WITH_SEPARATE_VALUE.has(arg)) {
-      i++;
-      continue;
-    }
-    if (arg.startsWith("-")) continue;
-    subcommand = arg;
-    break;
-  }
-  if (!subcommand) return "read";
-  if (NETWORK_SUBCOMMANDS.has(subcommand)) return "network";
-  if (WRITE_SUBCOMMANDS.has(subcommand) || AMBIGUOUS_AS_WRITE.has(subcommand)) return "write";
-  if (READ_SUBCOMMANDS.has(subcommand)) return "read";
-  return "write";
-}
-function buildGitEnv() {
-  return {
-    ...process.env,
-    GIT_TERMINAL_PROMPT: "0",
-    GCM_INTERACTIVE: "Never",
-    GIT_OPTIONAL_LOCKS: "0"
-  };
-}
-function runGit(cwd, args, options = {}) {
-  const commandClass = options.commandClass ?? classifyGitCommand(args);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUTS_MS[commandClass] ?? DEFAULT_TIMEOUTS_MS.write;
-  return new Promise((resolve5, reject) => {
-    const child = execFile(
-      "git",
-      args,
-      {
-        cwd,
-        env: buildGitEnv(),
-        timeout: timeoutMs,
-        // SIGTERM (Node's default) rather than SIGKILL: gives git a chance
-        // to run its own cleanup on POSIX, relevant to EF-20's own concern
-        // about a killed operation leaving refs/locks in an uncertain state.
-        // Moot on Windows -- Node docs: both map to an abrupt TerminateProcess
-        // there -- but this module isn't Windows-gated.
-        killSignal: "SIGTERM",
-        windowsHide: true,
-        encoding: "utf8"
-      },
-      (error, stdout, stderr) => {
-        if (error) {
-          if (error.killed) {
-            reject(
-              new GitTimeoutError(
-                // NOTE: embeds the raw args, including any secrets a future
-                // network-class caller might pass (e.g. a credentialed
-                // clone URL). No current caller does; redact before one does.
-                `git ${args.join(" ")} timed out after ${timeoutMs}ms (class: ${commandClass})`,
-                { cause: error }
-              )
-            );
-            return;
-          }
-          reject(error);
-          return;
-        }
-        resolve5({ stdout, stderr });
+    const dest = join4(arcaneDir, `${roleId}.yaml`);
+    if (!options.dryRun) {
+      try {
+        await copyFile2(src, dest);
+      } catch {
+        console.warn(`  ! Could not copy definition for "${roleId}" \u2014 skipping`);
       }
-    );
-    child.stdin?.end();
-  });
-}
-async function inspectGitRepository(cwd) {
-  try {
-    const { stdout: stdout2 } = await runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
-    if (stdout2.trim() !== "true") {
-      return { status: "not-repository" };
+    } else {
+      console.log(`  [dry-run] Would copy: ${label2}/agents/${roleId}.yaml`);
     }
-  } catch {
-    return { status: "not-repository" };
   }
-  try {
-    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
-  } catch {
-    return { status: "no-commits" };
+  if (options.dryRun) {
+    console.log(
+      `
+  [dry-run] Would initialize roster with ${selectedRoleIds.length} agents`
+    );
+    return;
   }
-  const { stdout } = await runGit(cwd, ["status", "--porcelain", "-uall"]);
-  const lines = stdout.trim();
-  return {
-    status: "ready",
-    uncommittedChanges: lines.length === 0 ? 0 : lines.split("\n").length
-  };
-}
-async function correctUnbornMasterDefault(cwd) {
-  let current;
-  try {
-    const { stdout } = await runGit(cwd, ["symbolic-ref", "--short", "HEAD"]);
-    current = stdout.trim();
-  } catch {
-    return { corrected: false, to: "main" };
+  printStep("Syncing agent definitions to all clients...");
+  const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
+    targetDir,
+    assetsDir,
+    roster,
+    { dryRun: false, scope }
+  );
+  printSuccess("Agent roster initialized");
+  console.log(`    \u{1F4CB} Profile: ${profileId} \xB7 Naming: ${namingStrategy} \xB7 Agents: ${rosterEntries.length}`);
+  console.log(
+    `    \u{1F504} Synced: ${synced.length} outputs (${scope === "user" ? "agent personas in ~/.claude/agents" : "Copilot, Claude, Codex, OpenClaw"})`
+  );
+  if (skipped.length > 0) {
+    console.log(`    \u26A0\uFE0F  Skipped: ${skipped.length} (${skipped.join(", ")})`);
   }
-  if (current !== "master") {
-    return { corrected: false, to: "main" };
+  console.log();
+  console.log(
+    `    \u{1F4A1} Customize: edit ${label2}/agents.yaml \u2192 spell agents sync${scope === "user" ? " --user" : ""}`
+  );
+  console.log();
+  if (hasUnresolvedRoles) {
+    console.error(
+      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
+    );
+    process.exitCode = 1;
   }
+}
+async function runAgentsSync(options, targetDir, assetsDir) {
+  const scope = options.scope ?? "repo";
+  let roster;
+  let definitionsDir;
+  let fromUserTier = false;
   try {
-    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
-    return { corrected: false, to: "main" };
-  } catch {
+    ({ roster, definitionsDir, fromUserTier } = await resolveRoster(targetDir, scope));
+  } catch (err) {
+    if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
+      console.error(err.message);
+      process.exit(1);
+      return;
+    }
+    throw err;
   }
-  let mainRef;
-  try {
-    mainRef = await runGit(cwd, ["for-each-ref", "--format=%(objectname)", "refs/heads/main"]);
-  } catch {
-    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  if (options.dryRun) {
+    console.log("\n  [dry-run] Would sync agents from roster:\n");
+  } else {
+    console.log("\n  Syncing agents...\n");
   }
-  if (mainRef.stdout.trim() !== "") {
-    return { corrected: false, to: "main" };
+  if (fromUserTier && scope === "repo") {
+    console.log(
+      "  This repository has no roster of its own and takes its spells from the user tier,\n  so its roster tables are built from ~/.arcane/agents.yaml.\n"
+    );
   }
-  if (mainRef.stderr.trim() !== "") {
-    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
+  const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
+    targetDir,
+    assetsDir,
+    roster,
+    { ...options, scope, ...definitionsDir === void 0 ? {} : { definitionsDir } }
+  );
+  if (options.dryRun) {
+    console.log(`
+  [dry-run] ${synced.length} outputs would be generated`);
+    return;
   }
-  try {
-    await runGit(cwd, ["symbolic-ref", "-q", "refs/heads/main"]);
-    return { corrected: false, to: "main", blockedReason: "target-unreadable" };
-  } catch (error) {
-    if (error.code !== 1) {
-      return { corrected: false, to: "main", blockedReason: "target-unreadable" };
-    }
+  console.log(`
+  \u2713 Synced ${synced.length} outputs`);
+  for (const item of synced) {
+    console.log(`    + ${item}`);
   }
-  await runGit(cwd, ["symbolic-ref", "HEAD", "refs/heads/main"]);
-  return { corrected: true, from: current, to: "main" };
-}
-async function ensureLocalPullRebase(cwd) {
-  let rawLocalValue;
-  try {
-    const { stdout } = await runGit(cwd, ["config", "--local", "--get", "pull.rebase"]);
-    rawLocalValue = stdout.trim();
-  } catch {
-    rawLocalValue = void 0;
+  if (skipped.length > 0) {
+    console.log(`
+  ! Skipped ${skipped.length}:`);
+    for (const item of skipped) {
+      console.log(`    - ${item}`);
+    }
   }
-  if (rawLocalValue === void 0) {
-    await runGit(cwd, ["config", "--local", "pull.rebase", "true"]);
-    return { action: "set" };
+  console.log();
+  if (hasUnresolvedRoles) {
+    console.error(
+      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
+    );
+    process.exitCode = 1;
   }
+}
+async function runAgentsList(targetDir, scope = "repo") {
+  let roster;
   try {
-    const { stdout } = await runGit(cwd, ["config", "--local", "--type=bool", "--get", "pull.rebase"]);
-    if (stdout.trim() === "false") {
-      return { action: "explicit-false-preserved" };
+    roster = await loadRoster(targetDir, scope);
+  } catch (err) {
+    if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
+      console.error(err.message);
+      process.exit(1);
+      return;
     }
-    return { action: "already-set" };
-  } catch {
-    return { action: "already-set" };
+    throw err;
+  }
+  const nameWidth = Math.max(
+    "Name".length,
+    ...roster.roster.map((e) => (e.name ?? e.definition).length)
+  );
+  const defWidth = Math.max(
+    "Role ID".length,
+    ...roster.roster.map((e) => e.definition.length)
+  );
+  const idWidth = Math.max(
+    "OpenClaw ID".length,
+    ...roster.roster.map((e) => e.id.length)
+  );
+  const pad = (s, n) => s.padEnd(n);
+  console.log(
+    `
+  Profile: ${roster.agent_profile}  |  Naming: ${roster.naming_strategy}  |  Agents: ${roster.roster.length}
+`
+  );
+  console.log(
+    `  ${pad("Name", nameWidth)}  ${pad("Role ID", defWidth)}  ${pad("OpenClaw ID", idWidth)}`
+  );
+  console.log(
+    `  ${"-".repeat(nameWidth)}  ${"-".repeat(defWidth)}  ${"-".repeat(idWidth)}`
+  );
+  for (const entry of roster.roster) {
+    console.log(
+      `  ${pad(entry.name ?? "(unnamed)", nameWidth)}  ${pad(entry.definition, defWidth)}  ${pad(entry.id, idWidth)}`
+    );
   }
+  console.log();
 }
 
+// src/modules/hub.ts
+import { confirm, select as select2, input as input2 } from "@inquirer/prompts";
+import { readdir as readdir5, writeFile as writeFile7 } from "fs/promises";
+import { join as join5 } from "path";
+
 // src/modules/ado-context.ts
 function remoteUrlHost(url) {
   const trimmed = url.trim();
@@ -3336,7 +3437,27 @@ async function offerRegistryScaffold(targetDir, businessRoot) {
 // src/modules/push-safety.ts
 import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile8, chmod, access as access3, rm as rm4, readdir as readdir6 } from "fs/promises";
 import { constants } from "fs";
-import { join as join6, resolve as resolve2, dirname as dirname3, basename } from "path";
+import { join as join7, resolve as resolve3, dirname as dirname4, basename as basename2 } from "path";
+
+// src/modules/real-path.ts
+import { realpathSync } from "fs";
+import { basename, dirname as dirname3, join as join6, resolve as resolve2 } from "path";
+function resolveRealPath(path4) {
+  const missing = [];
+  let existing = path4;
+  for (; ; ) {
+    try {
+      return join6(realpathSync.native(existing), ...missing);
+    } catch {
+      const parent = dirname3(existing);
+      if (parent === existing) return resolve2(path4);
+      missing.unshift(basename(existing));
+      existing = parent;
+    }
+  }
+}
+
+// src/modules/push-safety.ts
 var DISABLED_PUSH_URL = "arcane-push-blocked-run-spell-unblock-push://this-repository";
 var NO_PUSH_URL_MARKER = (remote) => `remote.${remote}.arcaneHadNoPushUrl`;
 var ARCANE_HOOKS_DIR = ".arcane/hooks";
@@ -3365,10 +3486,12 @@ function isArcaneHooksPath(root, value) {
   const windows = process.platform === "win32";
   const normalize = (p) => {
     const separated = windows ? p.replace(/\\/g, "/") : p;
-    const absolute = resolve2(root, separated).replace(/\\/g, "/").replace(/\/+$/, "");
+    const resolved = resolve3(root, separated);
+    const absolute = (windows ? resolved.replace(/\\/g, "/") : resolved).replace(/\/+$/, "");
     return windows ? absolute.toLowerCase() : absolute;
   };
-  return normalize(value) === normalize(ARCANE_HOOKS_DIR);
+  if (normalize(value) === normalize(ARCANE_HOOKS_DIR)) return true;
+  return normalize(resolveRealPath(resolve3(root, value))) === normalize(join7(resolveRealPath(root), ARCANE_HOOKS_DIR));
 }
 var PRE_PUSH_HOOK_BODY = `#!/bin/sh
 # Installed by Arcane because this repository's .arcane.json sets
@@ -3413,8 +3536,8 @@ async function repositoryRoot(cwd) {
     ]);
     const commonDir = stdout.trim();
     if (commonDir !== "") {
-      const parent = dirname3(commonDir);
-      if (basename(commonDir) === ".git" && parent !== "") return parent;
+      const parent = dirname4(commonDir);
+      if (basename2(commonDir) === ".git" && parent !== "") return parent;
     }
   } catch {
   }
@@ -3427,10 +3550,11 @@ async function repositoryRoot(cwd) {
   return cwd;
 }
 async function hookFilePath(cwd, hookName = "pre-push") {
-  return join6(await repositoryRoot(cwd), ARCANE_HOOKS_DIR, hookName);
+  return join7(await repositoryRoot(cwd), ARCANE_HOOKS_DIR, hookName);
 }
 async function hooksPathValue(cwd) {
-  return join6(await repositoryRoot(cwd), ARCANE_HOOKS_DIR).replace(/\\/g, "/");
+  const value = join7(await repositoryRoot(cwd), ARCANE_HOOKS_DIR);
+  return process.platform === "win32" ? value.replace(/\\/g, "/") : value;
 }
 async function installHook(cwd, hookName, body) {
   const root = await repositoryRoot(cwd);
@@ -3449,11 +3573,11 @@ async function installHook(cwd, hookName, body) {
       return { status: "refused-default-hooks", hooks: displaced };
     }
   }
-  const hookPath = join6(root, ARCANE_HOOKS_DIR, hookName);
+  const hookPath = join7(root, ARCANE_HOOKS_DIR, hookName);
   if (existing !== void 0 && await hookFileMatches(cwd, hookName, body)) {
     return { status: "already-ours" };
   }
-  await mkdir5(join6(root, ARCANE_HOOKS_DIR), { recursive: true });
+  await mkdir5(join7(root, ARCANE_HOOKS_DIR), { recursive: true });
   await writeFile8(hookPath, body, "utf-8");
   await chmod(hookPath, 493);
   await runGit(cwd, ["config", "--local", "core.hooksPath", await hooksPathValue(cwd)]);
@@ -3498,7 +3622,7 @@ async function defaultHooks(cwd) {
   let hooksDir;
   try {
     const { stdout } = await runGit(cwd, ["rev-parse", "--git-common-dir"]);
-    hooksDir = join6(resolve2(cwd, stdout.trim()), "hooks");
+    hooksDir = join7(resolve3(cwd, stdout.trim()), "hooks");
   } catch {
     return [];
   }
@@ -3534,7 +3658,7 @@ async function removeHook(cwd, hookName) {
     await rm4(await hookFilePath(cwd, hookName), { force: true });
   } catch {
   }
-  const hooksDir = join6(root, ARCANE_HOOKS_DIR);
+  const hooksDir = join7(root, ARCANE_HOOKS_DIR);
   let remaining = [];
   try {
     remaining = await readdir6(hooksDir);
@@ -3937,7 +4061,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   }
   let flags = {};
   try {
-    flags = resolveManifestFlags(options.manifestFlags, {}, join7(targetDir, ".arcane.json"));
+    flags = resolveManifestFlags(options.manifestFlags, {}, join8(targetDir, ".arcane.json"));
   } catch (err) {
     if (!(err instanceof ManifestFlagError)) throw err;
     console.error(`
@@ -4072,7 +4196,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     const installedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
       if (options.dryRun) {
         printDryRun(`Would copy: ${file}`);
       } else {
@@ -4089,7 +4213,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       fileCount++;
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join7(assetsDir, dir);
+      const srcDirPath = join8(assetsDir, dir);
       if (options.dryRun) {
         printDryRun(`Would copy directory: ${dir}/`);
       } else {
@@ -4118,7 +4242,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   if (options.dryRun) {
     if (hasAgents) {
       const agentFiles = await import("fs").then(
-        (fsModule) => fsModule.promises.readdir(join7(assetsDir, "agents"))
+        (fsModule) => fsModule.promises.readdir(join8(assetsDir, "agents"))
       );
       const yamlFiles = agentFiles.filter((f) => f.endsWith(".yaml")).sort();
       printDryRun("Would run agent setup (interactive):");
@@ -4357,7 +4481,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
   console.log(chalk2.hex("#a855f7")(`
   \u2726 Arcane v${packageVersion}
 `));
-  const homeDir = dirname4(storeRoot);
+  const homeDir = dirname5(storeRoot);
   const components = USER_TIER_COMPONENTS.map(
     (name) => componentForScope(getComponent(name), "user")
   );
@@ -4375,7 +4499,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
     for (const id of spellIds) {
       for (const client2 of ["codex", "claude"]) {
         const relativePath = USER_FANOUT_PATHS[client2](id);
-        if (await fileExists(join7(homeDir, relativePath))) {
+        if (await fileExists(join8(homeDir, relativePath))) {
           printDryRun(`Would leave alone (exists, not written by Arcane): ~/${relativePath}`);
         } else {
           printDryRun(`Would write: ~/${relativePath}`);
@@ -4393,7 +4517,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
     const installedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
       fileHashes[file] = await copyFile(srcPath, storeRoot, file, { force: options.force });
       installedFiles.push(file);
       fileCount++;
@@ -4440,23 +4564,23 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
 
 // src/modules/component-install.ts
 import { readFile as readFile8, stat, writeFile as writeFile9 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 async function planComponentInstall(component, targetDir, assetsDir, opts = {}) {
   const files = [];
   const stateOf = async (file, src) => {
-    const dest = join8(targetDir, file);
+    const dest = join9(targetDir, file);
     if (!await fileExists(dest)) return { file, src, state: "missing" };
     if ((await stat(dest)).isDirectory()) return { file, src, state: "directory" };
     const same = await hashFile(dest) === await hashFile(src);
     return { file, src, state: same ? "identical" : "differs" };
   };
   for (const file of component.files) {
-    files.push(await stateOf(file, join8(assetsDir, component.sourceOverrides?.[file] ?? file)));
+    files.push(await stateOf(file, join9(assetsDir, component.sourceOverrides?.[file] ?? file)));
   }
   for (const dir of component.directories ?? []) {
-    const srcDir = join8(assetsDir, dir);
+    const srcDir = join9(assetsDir, dir);
     for (const file of await listDirectoryFiles(srcDir, dir)) {
-      files.push(await stateOf(file, join8(assetsDir, file)));
+      files.push(await stateOf(file, join9(assetsDir, file)));
     }
   }
   const of = (...states) => files.filter((f) => states.includes(f.state));
@@ -4468,14 +4592,14 @@ async function planComponentInstall(component, targetDir, assetsDir, opts = {})
   }
   return { component, files, toCopy: of("missing", "identical"), kept: [], conflicts: of("differs", "directory") };
 }
-async function executeInstallPlan(plan, targetDir) {
+async function executeInstallPlan(plan, targetDir, opts = {}) {
   const files = [];
   const fileHashes = {};
   const written = [];
   try {
     for (const { file, src, state } of plan.toCopy) {
-      const previous = state === "missing" ? null : await readFile8(join8(targetDir, file));
-      fileHashes[file] = await copyFile(src, targetDir, file, { force: true });
+      const previous = state === "missing" ? null : await readFile8(join9(targetDir, file));
+      fileHashes[file] = await copyFile(src, targetDir, file, { force: true, ...opts });
       written.push({ file, previous });
       files.push(file);
     }
@@ -4492,7 +4616,7 @@ async function rollback(written, targetDir) {
         await removeWithin(targetDir, file);
         await removeEmptyAncestors(targetDir, file);
       } else {
-        await writeFile9(join8(targetDir, file), previous);
+        await writeFile9(join9(targetDir, file), previous);
       }
     } catch {
     }
@@ -4628,8 +4752,8 @@ async function runAdd(names, options, targetDir, assetsDir, packageVersion) {
 }
 
 // src/commands/update.ts
-import { dirname as dirname5, join as join10 } from "path";
-import { readFile as readFile9, writeFile as writeFile10 } from "fs/promises";
+import { dirname as dirname6, join as join11 } from "path";
+import { readFile as readFile9 } from "fs/promises";
 
 // src/modules/merge3.ts
 var CONFLICT_START = "<<<<<<< yours (edited)";
@@ -4760,7 +4884,7 @@ function merge3(base, ours, theirs) {
 }
 
 // src/modules/registry-changes.ts
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 function findMissingRequires(installed, profile) {
   const names = new Set(installed.flatMap((c) => LEGACY_COMPONENT_MIGRATIONS[c.name] ?? [c.name]));
   const promised = listProfiles().find((p) => p.id === profile)?.components;
@@ -4806,7 +4930,7 @@ async function findNewlyAvailable(targetDir, profile, installed, spellScope) {
     const alreadyPresent = [];
     if (component.skipExisting) {
       for (const file of component.files) {
-        if (await fileExists(join9(targetDir, file))) alreadyPresent.push(file);
+        if (await fileExists(join10(targetDir, file))) alreadyPresent.push(file);
       }
       if (component.files.length > 0 && alreadyPresent.length === component.files.length) continue;
     }
@@ -4922,11 +5046,11 @@ function describeInstallPlan(plan) {
   }
   return lines;
 }
-async function executeUpdateInstalls(plan, targetDir, packageVersion) {
+async function executeUpdateInstalls(plan, targetDir, packageVersion, copyOpts = {}) {
   const installed = [];
   const lines = [];
   for (const item of plan.items) {
-    const { files, fileHashes } = await executeInstallPlan(item.plan, targetDir);
+    const { files, fileHashes } = await executeInstallPlan(item.plan, targetDir, copyOpts);
     installed.push({
       name: item.plan.component.name,
       files,
@@ -4963,7 +5087,7 @@ async function missingTierWarning(scope, spellScope, homeDir) {
   } catch {
     return [
       "",
-      `  ! This repository takes its spells from the user tier, and ${storeRoot} is not installed.`,
+      `  ! This repository takes its spells from the user tier, and ${storeRoot} is not installed (or its manifest cannot be read).`,
       "    No client can reach a spell here: the routing block in CLAUDE.md and AGENTS.md still",
       "    names spells that resolve to nothing, so an agent improvises the workflow instead of",
       "    failing. Fix it with one of:",
@@ -5065,12 +5189,21 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
     console.log(`  ! Refused (path escapes the target directory): ${file}`);
     return "reported";
   }
-  const filePath = join10(targetDir, file);
+  const filePath = join11(targetDir, file);
   if (!await fileExists(filePath)) return "not-found";
   if (!prune) return "reported";
   if (recordedHash === void 0) {
-    console.log(`  ! Orphaned, not pruned (no recorded hash to verify it's untouched): ${file}`);
-    return "reported";
+    const evidence = await isUneditedTrackedFile(targetDir, file);
+    if (evidence.verdict !== "unedited") {
+      console.log(
+        `  ! Orphaned, not pruned: ${file} \u2014 no recorded hash, and git cannot confirm it is untouched (${evidence.detail}). Delete it yourself (git rm -- <path> if git tracks it), then run spell update --prune again to drop it from .arcane.json.`
+      );
+      return "reported";
+    }
+    await removeWithin(targetDir, file);
+    await removeEmptyAncestors(targetDir, file);
+    console.log(`  Pruned orphaned file (no recorded hash; git shows it ${evidence.detail}): ${file}`);
+    return "pruned";
   }
   if (!await fileMatchesHash(filePath, recordedHash)) {
     console.log(`  ! Orphaned but edited since install \u2014 not pruning: ${file}`);
@@ -5087,7 +5220,7 @@ async function isReleasableUserOwnedFile(targetDir, file, recordedHash) {
   } catch {
     return false;
   }
-  const filePath = join10(targetDir, file);
+  const filePath = join11(targetDir, file);
   if (!await fileExists(filePath)) return false;
   if (recordedHash === void 0) return true;
   return !await fileMatchesHash(filePath, recordedHash);
@@ -5098,7 +5231,7 @@ async function retainReportedOrphan(targetDir, file, recordedHash, into) {
   } catch {
     return;
   }
-  if (!await fileExists(join10(targetDir, file))) return;
+  if (!await fileExists(join11(targetDir, file))) return;
   if (!into.files.includes(file)) into.files.push(file);
   if (recordedHash !== void 0) {
     into.fileHashes ??= {};
@@ -5127,7 +5260,7 @@ async function findMissingTrackedFiles(targetDir, components, scope = "repo", sp
     const candidates = readopted.has(installed.name) ? component.files : installed.files;
     for (const file of candidates) {
       if (!component.files.includes(file)) continue;
-      if (!await fileExists(join10(targetDir, file))) missing.push(file);
+      if (!await fileExists(join11(targetDir, file))) missing.push(file);
     }
   }
   return missing;
@@ -5169,7 +5302,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   const movedFilesPresent = /* @__PURE__ */ new Set();
   for (const move of COMPONENT_FILE_MOVES) {
     for (const file of move.files) {
-      if (await fileExists(join10(targetDir, file))) movedFilesPresent.add(file);
+      if (await fileExists(join11(targetDir, file))) movedFilesPresent.add(file);
     }
   }
   manifest = {
@@ -5200,7 +5333,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       return;
     }
     try {
-      flagPatch = resolveManifestFlags(options.manifestFlags, manifest, join10(targetDir, ".arcane.json"));
+      flagPatch = resolveManifestFlags(options.manifestFlags, manifest, join11(targetDir, ".arcane.json"));
     } catch (err) {
       if (!(err instanceof ManifestFlagError)) throw err;
       console.error(`
@@ -5213,8 +5346,16 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   const answered = { ...manifest, ...flagPatch };
   const spellScope = effectiveSpellScope(manifest);
   const readopted = findReadoptedSpellComponents(manifest.components, scope, spellScope);
-  const homeDir = dirname5(targetDir);
-  for (const line of await missingTierWarning(scope, spellScope)) console.log(line);
+  const homeDir = dirname6(targetDir);
+  const tierGate = await missingTierWarning(scope, spellScope);
+  if (tierGate.length > 0) {
+    for (const line of tierGate) console.error(line);
+    console.error(
+      "  \u2717 Update refused: nothing was written. Install the tier or change spell_scope, then run `spell update` again."
+    );
+    process.exit(1);
+    return;
+  }
   if (scope === "repo") {
     console.warn(
       `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
@@ -5245,6 +5386,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       return;
     }
   }
+  const linkTracked = scope === "repo" ? await listSymlinkTrackedPaths(targetDir) : /* @__PURE__ */ new Set();
+  const conversions = [];
   const registryChanges = {
     retired: findTrackedRetirements(manifest.components),
     ...scope === "repo" ? {
@@ -5284,7 +5427,10 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       for (const line of describeInstallPlan(installPlan)) console.log(line);
       return [];
     }
-    const { installed, lines } = await executeUpdateInstalls(installPlan, targetDir, packageVersion);
+    const { installed, lines } = await executeUpdateInstalls(installPlan, targetDir, packageVersion, {
+      linkTracked,
+      conversions
+    });
     for (const line of lines) console.log(line);
     return installed;
   };
@@ -5400,7 +5546,16 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         if (options.prune && !options.dryRun && installed.files.every((f) => orphanReport.find((o) => o.file === f)?.status !== "reported")) {
           continue;
         }
-        updatedComponents.push(installed);
+        const keptHashes = {};
+        for (const file of stillTracked) {
+          const hash = installed.fileHashes?.[file];
+          if (hash !== void 0) keptHashes[file] = hash;
+        }
+        updatedComponents.push({
+          ...installed,
+          files: stillTracked,
+          ...installed.fileHashes ? { fileHashes: keptHashes } : {}
+        });
         continue;
       }
       throw err;
@@ -5408,8 +5563,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     const updatedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join10(assetsDir, component.sourceOverrides?.[file] ?? file);
-      const targetExists = await fileExists(join10(targetDir, file));
+      const srcPath = join11(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const targetExists = await fileExists(join11(targetDir, file));
       const preserveExisting = Boolean(component.skipExisting) && targetExists;
       const recordedHash = installed.fileHashes?.[file];
       if (component.initOnly && !targetExists) {
@@ -5429,7 +5584,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
           continue;
         }
       }
-      const editedByOperator = recordedHash !== void 0 && targetExists && !preserveExisting && !await fileMatchesHash(join10(targetDir, file), recordedHash);
+      const linkShape = targetExists ? await managedPathLinkShape(targetDir, file, linkTracked, isClientShimPath(file)) : null;
+      const editedByOperator = recordedHash !== void 0 && targetExists && !preserveExisting && linkShape === null && !await fileMatchesHash(join11(targetDir, file), recordedHash);
       if (preserveExisting) {
         console.log(`  ${options.dryRun ? "[dry-run] Would preserve" : "Preserved"}: ${file}`);
       } else if (editedByOperator && isClientShimPath(file)) {
@@ -5439,7 +5595,9 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
           `  ${options.dryRun ? "[dry-run] Would keep" : "Kept"} customized (not merged): ${file}`
         );
       } else if (options.dryRun) {
-        console.log(`  [dry-run] Would ${sameVersionRestore ? "restore missing" : "update"}: ${file}`);
+        console.log(
+          `  [dry-run] Would ${linkShape !== null ? "convert to a regular file (it is a symlink, or a link written out as text)" : sameVersionRestore ? "restore missing" : "update"}: ${file}`
+        );
         fileCount++;
       } else {
         let handled = false;
@@ -5456,11 +5614,11 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
             handled = true;
           } else {
             const [currentContent, newContent] = await Promise.all([
-              readFile9(join10(targetDir, file), "utf-8"),
+              readFile9(join11(targetDir, file), "utf-8"),
               readFile9(srcPath, "utf-8")
             ]);
             const result = merge3(oldVendorContent, currentContent, newContent);
-            await writeFile10(join10(targetDir, file), result.content, "utf-8");
+            await writeManagedFile(targetDir, file, result.content, { linkTracked, conversions });
             fileHashes[file] = await hashFile(srcPath);
             if (result.hasConflict) {
               conflictedFiles.push(file);
@@ -5472,7 +5630,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
           }
         }
         if (!handled) {
-          fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: true });
+          fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: true, linkTracked, conversions });
+          if (linkShape === "path-body") conversions.push({ file, shape: "path-body" });
           if (sameVersionRestore) console.log(`  Restored missing: ${file}`);
         }
         fileCount++;
@@ -5482,11 +5641,11 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       }
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join10(assetsDir, dir);
+      const srcDirPath = join11(assetsDir, dir);
       if (options.dryRun) {
         console.log(`  [dry-run] Would update directory: ${dir}/`);
       } else {
-        const copied = await copyDirectory(srcDirPath, targetDir, dir, { force: true });
+        const copied = await copyDirectory(srcDirPath, targetDir, dir, { force: true, linkTracked, conversions });
         for (const { path: copiedPath, hash } of copied) {
           updatedFiles.push(copiedPath);
           fileHashes[copiedPath] = hash;
@@ -5550,6 +5709,21 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
       console.log("  Run `spell update --prune` to remove the ones that are safe to delete.");
     }
   }
+  if (conversions.length > 0) {
+    console.log(`
+  Converted ${conversions.length} symlinked managed file(s) to regular files (#357):`);
+    const describe = {
+      "index-symlink": "the index tracked it as a symlink (mode 120000); rewritten and staged as a regular file",
+      symlink: "was a symlink in the working tree; now a regular file (stage the typechange with git add)",
+      "path-body": "its body was only a link target, a symlink written out as text; rewritten as a real file"
+    };
+    for (const c of conversions) console.log(`    ${c.file} \u2014 ${describe[c.shape]}`);
+    if (conversions.some((c) => c.shape === "index-symlink")) {
+      console.log(
+        "  Commit the staged typechange, or every other checkout keeps reading a link whose target is the file's own text."
+      );
+    }
+  }
   printRegistryChanges();
   if (customizedShims.length > 0) {
     const verb = options.dryRun ? "[dry-run] Would keep" : "Kept";
@@ -5642,11 +5816,11 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
 }
 
 // src/commands/status.ts
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 
 // src/modules/version-check.ts
-import { readFile as readFile10, writeFile as writeFile11, mkdir as mkdir6 } from "fs/promises";
-import { dirname as dirname6, join as join11 } from "path";
+import { readFile as readFile10, writeFile as writeFile10, mkdir as mkdir6 } from "fs/promises";
+import { dirname as dirname7, join as join12 } from "path";
 import { homedir as homedir3 } from "os";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
@@ -5660,7 +5834,7 @@ function getFeedUrl() {
   }
   return url;
 }
-var DEFAULT_CACHE_PATH = join11(homedir3(), ".arcane", "version-cache.json");
+var DEFAULT_CACHE_PATH = join12(homedir3(), ".arcane", "version-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function readCache(cachePath) {
   try {
@@ -5675,9 +5849,9 @@ async function readCache(cachePath) {
   }
 }
 async function writeCache(cachePath, latest) {
-  await mkdir6(dirname6(cachePath), { recursive: true });
+  await mkdir6(dirname7(cachePath), { recursive: true });
   const entry = { latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile11(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+  await writeFile10(cachePath, JSON.stringify(entry, null, 2), "utf-8");
 }
 async function getLatestVersion(feedUrl) {
   const normalizedBase = feedUrl.endsWith("/") ? feedUrl : feedUrl + "/";
@@ -5816,7 +5990,7 @@ async function runStatus(targetDir, packageVersion, options = {}) {
   console.log("");
   if (scope === "user") {
     console.log(`  Scope: user \u2014 ${targetDir}`);
-    const health = await inspectUserTierFanout(dirname7(targetDir), manifest.fanout);
+    const health = await inspectUserTierFanout(dirname8(targetDir), manifest.fanout);
     console.log(
       `  Client files: ${health.total} (${health.byClient.codex} ${FANOUT_CLIENT_LABELS.codex}, ${health.byClient.claude} ${FANOUT_CLIENT_LABELS.claude})`
     );
@@ -5879,7 +6053,7 @@ async function runStatus(targetDir, packageVersion, options = {}) {
 
 // src/commands/uninstall.ts
 import { rm as rm5 } from "fs/promises";
-import { dirname as dirname8, join as join12 } from "path";
+import { dirname as dirname9, join as join13 } from "path";
 import { confirm as confirm3 } from "@inquirer/prompts";
 async function runUninstall(options, targetDir) {
   let manifest;
@@ -5962,16 +6136,16 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
       }
     }
   }
-  await rm5(join12(targetDir, ".arcane.json"), { force: true });
+  await rm5(join13(targetDir, ".arcane.json"), { force: true });
   const agentDirs = [
     ".github/agents",
     ".arcane/agents",
     ".arcane/generated"
   ];
   for (const dir of agentDirs) {
-    await rm5(join12(targetDir, dir), { recursive: true, force: true });
+    await rm5(join13(targetDir, dir), { recursive: true, force: true });
   }
-  await rm5(join12(targetDir, ".arcane/agents.yaml"), { force: true });
+  await rm5(join13(targetDir, ".arcane/agents.yaml"), { force: true });
   const markerFiles = [
     "CLAUDE.md",
     "AGENTS.md",
@@ -5988,7 +6162,7 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
 \u2713 Uninstalled \u2014 ${removed} files removed.`);
 }
 async function uninstallUserTier(options, storeRoot, manifest) {
-  const homeDir = dirname8(storeRoot);
+  const homeDir = dirname9(storeRoot);
   const storeFiles = manifest.components.flatMap((c) => c.files);
   const recordedCount = Object.keys(manifest.fanout ?? {}).length;
   if (options.dryRun) {
@@ -6033,10 +6207,10 @@ async function uninstallUserTier(options, storeRoot, manifest) {
       console.log(`  ! Skipped ${file}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  await rm5(join12(storeRoot, ".arcane.json"), { force: true });
-  await rm5(join12(storeRoot, "agents"), { recursive: true, force: true });
-  await rm5(join12(storeRoot, "agents.yaml"), { force: true });
-  await removeDirectoryIfEmpty(join12(storeRoot, USER_TIER_SPELLS_DIR));
+  await rm5(join13(storeRoot, ".arcane.json"), { force: true });
+  await rm5(join13(storeRoot, "agents"), { recursive: true, force: true });
+  await rm5(join13(storeRoot, "agents.yaml"), { force: true });
+  await removeDirectoryIfEmpty(join13(storeRoot, USER_TIER_SPELLS_DIR));
   await removeDirectoryIfEmpty(storeRoot);
   for (const line of describeFanoutOutcomes(fanout.outcomes)) console.log(`  ${line}`);
   const pruned = fanout.outcomes.filter((o) => o.status === "pruned").length;
@@ -6049,7 +6223,7 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 
 // src/commands/doctor.ts
 import { access as access4, readdir as readdir9, readFile as readFile13, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
-import { join as join15, dirname as dirname9 } from "path";
+import { join as join16, dirname as dirname10 } from "path";
 
 // src/config/incidents.ts
 var INCIDENT_QUEUE = [
@@ -6118,7 +6292,7 @@ function evaluateIncidentGate(records) {
 
 // src/modules/denylist-scan.ts
 import { readFile as readFile11, readdir as readdir7 } from "fs/promises";
-import { join as join13, relative } from "path";
+import { join as join14, relative } from "path";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -6169,7 +6343,7 @@ async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT
     return collected;
   }
   for (const entry of entries) {
-    const absolutePath = join13(root, entry.name);
+    const absolutePath = join14(root, entry.name);
     if (entry.isDirectory()) {
       if (SKIP_DIRECTORIES.has(entry.name)) continue;
       collected.push(...await collectScannableFiles(absolutePath, repoRoot, extensions));
@@ -6196,7 +6370,7 @@ import { existsSync, readFileSync } from "fs";
 import { win32 } from "path";
 var EXTERNAL_CLI_TIMEOUT_MS = 1e4;
 function execFileWithTimeout(file, args, timeoutMs, options = {}) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     const child = execFile2(
       file,
       args,
@@ -6212,7 +6386,7 @@ function execFileWithTimeout(file, args, timeoutMs, options = {}) {
           reject(error);
           return;
         }
-        resolve5({ stdout, stderr });
+        resolve6({ stdout, stderr });
       }
     );
     child.stdin?.end();
@@ -6430,7 +6604,7 @@ function parseAdoRemote(url) {
 
 // src/modules/placeholders.ts
 import { readdir as readdir8, readFile as readFile12 } from "fs/promises";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 var PLACEHOLDER_STANDARD_FILE = "spell-authoring-standards.md";
 var RUNTIME_PLACEHOLDERS_START = "<!-- runtime-placeholders:start -->";
 var RUNTIME_PLACEHOLDERS_END = "<!-- runtime-placeholders:end -->";
@@ -6525,7 +6699,7 @@ function parseRuntimePlaceholders(standardContent) {
 async function scanGovernancePlaceholders(governanceDir) {
   let standard;
   try {
-    standard = await readFile12(join14(governanceDir, PLACEHOLDER_STANDARD_FILE), "utf8");
+    standard = await readFile12(join15(governanceDir, PLACEHOLDER_STANDARD_FILE), "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return { status: "skipped", reason: `${PLACEHOLDER_STANDARD_FILE} is not installed` };
@@ -6544,7 +6718,7 @@ async function scanGovernancePlaceholders(governanceDir) {
   const templateDocs = [];
   const findings = [];
   for (const file of files) {
-    const content = await readFile12(join14(governanceDir, file), "utf8");
+    const content = await readFile12(join15(governanceDir, file), "utf8");
     const status = parseFrontmatterStatus(content);
     if (status === "template") templateDocs.push(file);
     if (status !== "active") continue;
@@ -6575,8 +6749,8 @@ async function checkNodeVersion() {
 async function checkVSCodeExtension(id, label2, homeDir = resolveHomeDir()) {
   const name = `VS Code extension: ${label2}`;
   const flavours = [
-    { dir: join15(homeDir, ".vscode", "extensions"), bin: "code" },
-    { dir: join15(homeDir, ".vscode-insiders", "extensions"), bin: "code-insiders" }
+    { dir: join16(homeDir, ".vscode", "extensions"), bin: "code" },
+    { dir: join16(homeDir, ".vscode-insiders", "extensions"), bin: "code-insiders" }
   ];
   let installBin = null;
   for (const flavour of flavours) {
@@ -6604,11 +6778,11 @@ async function checkVSCodeExtension(id, label2, homeDir = resolveHomeDir()) {
 }
 async function checkArcaneManifest(targetDir) {
   const name = "Arcane manifest (.arcane.json)";
-  const manifestPath2 = join15(targetDir, ".arcane.json");
+  const manifestPath2 = join16(targetDir, ".arcane.json");
   try {
     await access4(manifestPath2);
   } catch {
-    const selfHostedManifestPath = join15(targetDir, "src", "assets", ".arcane.json");
+    const selfHostedManifestPath = join16(targetDir, "src", "assets", ".arcane.json");
     try {
       const raw = await readFile13(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
@@ -6714,7 +6888,7 @@ async function checkSessionContinuity(targetDir) {
   const results = [];
   for (const file of SESSION_CONTINUITY_FILES) {
     const name = `Session file: ${file}`;
-    const filePath = join15(targetDir, file);
+    const filePath = join16(targetDir, file);
     try {
       await access4(filePath);
       results.push({ name, passed: true, message: "present" });
@@ -6732,12 +6906,12 @@ async function checkSessionContinuity(targetDir) {
 async function fixSessionContinuity(targetDir, assetsDir) {
   const created = [];
   for (const file of SESSION_CONTINUITY_FILES) {
-    const destPath = join15(targetDir, file);
+    const destPath = join16(targetDir, file);
     try {
       await access4(destPath);
     } catch {
-      const srcPath = join15(assetsDir, file);
-      await mkdir7(dirname9(destPath), { recursive: true });
+      const srcPath = join16(assetsDir, file);
+      await mkdir7(dirname10(destPath), { recursive: true });
       await fsCopyFile(srcPath, destPath);
       created.push(file);
     }
@@ -6864,7 +7038,7 @@ async function checkGovernancePlaceholders(targetDir) {
   const name = "Governance placeholders (ARC-051)";
   let scan;
   try {
-    scan = await scanGovernancePlaceholders(join15(targetDir, ".arcane", "governance"));
+    scan = await scanGovernancePlaceholders(join16(targetDir, ".arcane", "governance"));
   } catch (err) {
     return {
       name,
@@ -6951,7 +7125,7 @@ async function checkNewlyAvailableComponents(targetDir) {
 }
 async function checkMcpConfig(targetDir) {
   const name = "MCP config (per-server timeout, I12)";
-  const filePath = join15(targetDir, ".mcp.json");
+  const filePath = join16(targetDir, ".mcp.json");
   let raw;
   try {
     raw = await readFile13(filePath, "utf8");
@@ -7034,7 +7208,7 @@ function isDelegationsFile(value) {
 }
 async function checkDelegations(targetDir) {
   const name = "Standing delegations (T13)";
-  const filePath = join15(targetDir, ".arcane", "delegations.json");
+  const filePath = join16(targetDir, ".arcane", "delegations.json");
   let raw;
   try {
     raw = await readFile13(filePath, "utf8");
@@ -7116,6 +7290,49 @@ async function checkPlatformBranchPolicy(targetDir) {
     message: "remote is neither GitHub nor Azure DevOps \u2014 platform policy verification not available for this provider"
   };
 }
+async function checkManagedFileModes(targetDir) {
+  const name = "Managed files are regular files (#357)";
+  let manifest;
+  try {
+    manifest = await readManifest(targetDir);
+  } catch {
+    return { name, passed: true, skipped: true, message: "no .arcane.json \u2014 nothing to check" };
+  }
+  try {
+    await runGit(targetDir, ["rev-parse", "--git-dir"]);
+  } catch {
+    return { name, passed: true, skipped: true, message: "not a git repository \u2014 the index cannot be read" };
+  }
+  const managed = [...new Set(manifest.components.flatMap((c) => c.files))];
+  const linkTracked = await listSymlinkTrackedPaths(targetDir);
+  const asLinks = managed.filter((file) => linkTracked.has(file));
+  const pathBodies = [];
+  for (const file of managed) {
+    if (!isClientShimPath(file) || asLinks.includes(file)) continue;
+    let body;
+    try {
+      body = await readFile13(join16(targetDir, file), "utf-8");
+    } catch {
+      continue;
+    }
+    if (looksLikeBarePath(body)) pathBodies.push(file);
+  }
+  if (asLinks.length === 0 && pathBodies.length === 0) {
+    return { name, passed: true, message: `${managed.length} managed path(s), all regular files` };
+  }
+  const parts = [];
+  if (asLinks.length > 0) {
+    parts.push(`${asLinks.length} tracked as a symlink (mode 120000): ${asLinks.join(", ")}`);
+  }
+  if (pathBodies.length > 0) {
+    parts.push(`${pathBodies.length} client shim(s) whose body is only a path: ${pathBodies.join(", ")}`);
+  }
+  return {
+    name,
+    passed: false,
+    message: parts.join("; ") + " \u2014 clients silently skip or empty these spells. Run `spell update` (it rewrites them as regular files and stages the typechange), then commit."
+  };
+}
 async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
   const name = "Spell scope (ARC-045)";
   let manifest;
@@ -7147,7 +7364,7 @@ async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
   let probed = false;
   const probe = "spell-status.md";
   try {
-    const entries = await readdir9(join15(storeRoot, USER_TIER_SPELLS_DIR));
+    const entries = await readdir9(join16(storeRoot, USER_TIER_SPELLS_DIR));
     const spells = entries.filter((e) => e.startsWith("spell-") && e.endsWith(".md"));
     spellCount = spells.length;
     probed = spells.includes(probe);
@@ -7211,6 +7428,7 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkMcpConfig(targetDir),
     checkUserTier(resolveHomeDir(), options.packageVersion),
     checkSpellScope(targetDir),
+    checkManagedFileModes(targetDir),
     checkGovernancePlaceholders(targetDir),
     checkComponentRequires(targetDir),
     checkNewlyAvailableComponents(targetDir)
@@ -7261,7 +7479,7 @@ import { readFile as readFile15 } from "fs/promises";
 
 // src/modules/ward.ts
 import { readdir as readdir10, readFile as readFile14 } from "fs/promises";
-import { join as join16, relative as relative2 } from "path";
+import { join as join17, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
@@ -7324,7 +7542,7 @@ async function scanFilenames(root, rules, repoRoot = root) {
     return findings;
   }
   for (const entry of entries) {
-    const absolutePath = join16(root, entry.name);
+    const absolutePath = join17(root, entry.name);
     if (entry.isDirectory()) {
       if (SKIP_DIRECTORIES.has(entry.name)) continue;
       findings.push(...await scanFilenames(absolutePath, rules, repoRoot));
@@ -7439,7 +7657,7 @@ async function runWardCli(targetDir, options = {}, exclusions = []) {
 }
 
 // src/commands/unblock-push.ts
-import { basename as basename2, resolve as resolve3 } from "path";
+import { basename as basename3, resolve as resolve4 } from "path";
 import { input as input4 } from "@inquirer/prompts";
 async function runUnblockPush(targetDir) {
   let manifest;
@@ -7471,7 +7689,7 @@ async function runUnblockPush(targetDir) {
     process.exit(1);
     return;
   }
-  const repoName = basename2(resolve3(targetDir));
+  const repoName = basename3(resolve4(targetDir));
   if (repoName === "") {
     console.error(
       "Could not determine a repository name to confirm against (is this repository at a filesystem root?). Refusing to unblock."
@@ -7760,10 +7978,10 @@ import * as client from "openid-client";
 // src/modules/result-pages.ts
 import { createHash as createHash3 } from "crypto";
 import { readFile as readFile16 } from "fs/promises";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 var RESULT_KINDS = ["success", "denied", "failure"];
 function resultPagePath(kind) {
-  return join17("sign-in", `sign-in-callback-${kind}.html`);
+  return join18("sign-in", `sign-in-callback-${kind}.html`);
 }
 function styleHashes(html) {
   return [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)].map((match) => {
@@ -7811,7 +8029,7 @@ var PLAIN_RESULT_PAGES = {
 async function loadResultPages(assetsDir) {
   try {
     const [success, denied, failure] = await Promise.all(
-      RESULT_KINDS.map(async (kind) => resultPage(await readFile16(join17(assetsDir, resultPagePath(kind)), "utf8")))
+      RESULT_KINDS.map(async (kind) => resultPage(await readFile16(join18(assetsDir, resultPagePath(kind)), "utf8")))
     );
     return { success, denied, failure };
   } catch {
@@ -7889,9 +8107,9 @@ async function browserLogin(config, options) {
   const state = client.randomState();
   const nonce = client.randomNonce();
   const server = createServer();
-  await new Promise((resolve5, reject) => {
+  await new Promise((resolve6, reject) => {
     server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => resolve5());
+    server.listen(0, "127.0.0.1", () => resolve6());
   });
   const address = server.address();
   if (address === null || typeof address === "string") {
@@ -7917,7 +8135,7 @@ async function browserLogin(config, options) {
     server.closeAllConnections?.();
     server.close();
   };
-  const tokens = new Promise((resolve5, reject) => {
+  const tokens = new Promise((resolve6, reject) => {
     server.on("request", (req, res) => {
       const url = new URL(req.url ?? "/", redirectUri);
       if (RESULT_PATHS.has(url.pathname)) {
@@ -7928,7 +8146,7 @@ async function browserLogin(config, options) {
         const served = browserResult;
         const page = pages[served.kind];
         const settle = () => {
-          if (served.kind === "success") resolve5(served.result);
+          if (served.kind === "success") resolve6(served.result);
           else reject(served.error);
         };
         res.once("finish", settle).once("close", settle);
@@ -7957,7 +8175,7 @@ async function browserLogin(config, options) {
         }).end();
         if (result.kind === "success") {
           if (timer) clearTimeout(timer);
-          timer = setTimeout(() => resolve5(result.result), Math.min(timeoutMs, 5e3));
+          timer = setTimeout(() => resolve6(result.result), Math.min(timeoutMs, 5e3));
         }
       };
       const errorCode = url.searchParams.get("error");
@@ -8009,12 +8227,12 @@ async function refreshSession(config, refreshToken, scopes) {
 }
 function openInDefaultBrowser(url) {
   const [command, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     try {
-      const child = execFile3(command, args, { windowsHide: true }, (error) => resolve5(!error));
-      child.on("error", () => resolve5(false));
+      const child = execFile3(command, args, { windowsHide: true }, (error) => resolve6(!error));
+      child.on("error", () => resolve6(false));
     } catch {
-      resolve5(false);
+      resolve6(false);
     }
   });
 }
@@ -8023,7 +8241,7 @@ function openInDefaultBrowser(url) {
 import { execFileSync } from "child_process";
 import { mkdirSync, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync, existsSync as existsSync2 } from "fs";
 import { userInfo } from "os";
-import { dirname as dirname10, join as join18 } from "path";
+import { dirname as dirname11, join as join19 } from "path";
 
 // src/modules/keychain-backend.ts
 import { createRequire as createRequire2 } from "module";
@@ -8112,7 +8330,7 @@ var FileSecretBackend = class {
       rmSync(this.filePath, { force: true });
       return;
     }
-    mkdirSync(dirname10(this.filePath), { recursive: true });
+    mkdirSync(dirname11(this.filePath), { recursive: true });
     const tmp = `${this.filePath}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify(entries), { encoding: "utf8", mode: 384 });
     try {
@@ -8157,7 +8375,7 @@ function restrictToCurrentUser(filePath) {
   });
 }
 function insecureSessionFilePath(homeDir) {
-  return join18(userTierRoot(homeDir), INSECURE_SESSION_FILE_NAME);
+  return join19(userTierRoot(homeDir), INSECURE_SESSION_FILE_NAME);
 }
 function createSessionStorage(options = {}) {
   const keychain = new ChunkedSecretStore(options.keychainBackend ?? createKeychainBackend());
@@ -8425,15 +8643,15 @@ async function runWhoami(options, deps = defaultWhoamiDeps()) {
 
 // src/commands/report.ts
 import { access as access5 } from "fs/promises";
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 
 // src/modules/show-report/generate.ts
-import { mkdir as mkdir8, readdir as readdir11, readFile as readFile18, writeFile as writeFile12 } from "fs/promises";
-import { basename as basename3, dirname as dirname11, isAbsolute, join as join20, relative as relative3, resolve as resolve4 } from "path";
+import { mkdir as mkdir8, readdir as readdir11, readFile as readFile18, writeFile as writeFile11 } from "fs/promises";
+import { basename as basename4, dirname as dirname12, isAbsolute, join as join21, relative as relative3, resolve as resolve5 } from "path";
 
 // src/modules/show-report/model.ts
 import { readFile as readFile17 } from "fs/promises";
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 
 // src/modules/show-report/plan-parser.ts
 function parseFrontmatter(content) {
@@ -8802,11 +9020,11 @@ function buildCorrections(ledgerRows, programName) {
   };
 }
 async function buildShowReportModel(options) {
-  const planAbsPath = join19(options.rootDir, options.planRelPath);
-  const queueAbsPath = join19(options.rootDir, options.queueRelPath);
+  const planAbsPath = join20(options.rootDir, options.planRelPath);
+  const queueAbsPath = join20(options.rootDir, options.queueRelPath);
   const ledgerRelPath = "docs/verification-ledger.md";
-  const ledgerAbsPath = join19(options.rootDir, ledgerRelPath);
-  const decisionsAbsPath = join19(options.rootDir, "DECISIONS.md");
+  const ledgerAbsPath = join20(options.rootDir, ledgerRelPath);
+  const decisionsAbsPath = join20(options.rootDir, "DECISIONS.md");
   const [planContent, queueContent, ledgerContent, decisionsContent] = await Promise.all([
     readFile17(planAbsPath, "utf8"),
     readOptional(queueAbsPath),
@@ -9004,7 +9222,7 @@ function toPosix(path4) {
 async function programFromPlan(rootDir, slug, planRelPath) {
   let planContent;
   try {
-    planContent = await readFile18(join20(rootDir, planRelPath), "utf8");
+    planContent = await readFile18(join21(rootDir, planRelPath), "utf8");
   } catch {
     return { skipped: { slug, reason: `no PLAN.md at ${planRelPath}` } };
   }
@@ -9016,13 +9234,13 @@ async function programFromPlan(rootDir, slug, planRelPath) {
     program: {
       slug,
       planRelPath,
-      queueRelPath: toPosix(join20(dirname11(planRelPath), "OPERATOR-QUEUE.md")),
+      queueRelPath: toPosix(join21(dirname12(planRelPath), "OPERATOR-QUEUE.md")),
       ledgerProgramName: programNameFromTitle(frontmatter.title ?? slug)
     }
   };
 }
 async function discoverPrograms(rootDir) {
-  const plansDir = join20(rootDir, "docs", "plans");
+  const plansDir = join21(rootDir, "docs", "plans");
   let entries;
   try {
     entries = (await readdir11(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
@@ -9040,9 +9258,9 @@ async function discoverPrograms(rootDir) {
   return { programs, skipped };
 }
 async function programFromPlanPath(rootDir, planPath) {
-  const planAbs = isAbsolute(planPath) ? planPath : resolve4(rootDir, planPath);
+  const planAbs = isAbsolute(planPath) ? planPath : resolve5(rootDir, planPath);
   const planRelPath = toPosix(relative3(rootDir, planAbs));
-  return programFromPlan(rootDir, basename3(dirname11(planAbs)), planRelPath);
+  return programFromPlan(rootDir, basename4(dirname12(planAbs)), planRelPath);
 }
 function normalizeLineEndings2(content) {
   return content.replace(/\r\n?/g, "\n");
@@ -9056,7 +9274,7 @@ async function readOptionalFile(path4) {
   }
 }
 async function generateReport(rootDir, program2, templateHtml, theme = "auto") {
-  const planContent = await readFile18(join20(rootDir, program2.planRelPath), "utf8");
+  const planContent = await readFile18(join21(rootDir, program2.planRelPath), "utf8");
   const frontmatter = parseFrontmatter(planContent);
   const model = await buildShowReportModel({
     rootDir,
@@ -9087,19 +9305,19 @@ async function runReportGeneration(options) {
     if (!generated.themeApplied) themeSkipped.push(program2.slug);
     const missing = JSON.parse(generated.json).sections.flatMap((section) => section.rows).filter((row) => row.descriptionState === "unwritten").map((row) => row.id);
     if (missing.length > 0) unwritten.push({ slug: program2.slug, ids: missing });
-    const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve4(options.rootDir, options.outDir) : resolve4(options.rootDir, dirname11(program2.planRelPath));
+    const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve5(options.rootDir, options.outDir) : resolve5(options.rootDir, dirname12(program2.planRelPath));
     const outRel = toPosix(relative3(options.rootDir, outAbs));
     const outputs = [
       [`${outRel}/show-report.json`, generated.json],
       [`${outRel}/show-report.html`, generated.html]
     ];
     for (const [relPath, expected] of outputs) {
-      const actual = await readOptionalFile(join20(options.rootDir, relPath));
+      const actual = await readOptionalFile(join21(options.rootDir, relPath));
       if (actual === null || normalizeLineEndings2(actual) !== normalizeLineEndings2(expected)) {
         drifted.push(`${relPath} does not match a regeneration from its sources.`);
         if (options.mode === "write") {
           await mkdir8(outAbs, { recursive: true });
-          await writeFile12(join20(options.rootDir, relPath), expected, "utf8");
+          await writeFile11(join21(options.rootDir, relPath), expected, "utf8");
           repaired.push(relPath);
         }
       }
@@ -9110,7 +9328,7 @@ async function runReportGeneration(options) {
 
 // src/commands/report.ts
 async function runReport(targetDir, options = {}, assetsDir) {
-  const templatePath = join21(assetsDir, "report", "show-report.template.html");
+  const templatePath = join22(assetsDir, "report", "show-report.template.html");
   try {
     await access5(templatePath);
   } catch {
@@ -9184,10 +9402,10 @@ async function runReport(targetDir, options = {}, assetsDir) {
 }
 
 // src/index.ts
-import { realpathSync } from "fs";
+import { realpathSync as realpathSync2 } from "fs";
 var require3 = createRequire3(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join22(dirname12(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join23(dirname13(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 var USER_FLAG_DESCRIPTION = "Operate on the per-user tier at ~/.arcane \u2014 spells shared by every repository on this machine, fanned out to ~/.agents/skills (Codex, Copilot) and ~/.claude/commands (Claude Code)";
 var USER_TIER_AGENTS_DESCRIPTION = "Operate on the per-user tier at ~/.arcane \u2014 one agent roster shared by every repository on this machine, rendered to ~/.copilot/agents (VS Code agent modes)";
@@ -9397,7 +9615,7 @@ agentsCommand.command("list").description("Show the current agent roster with as
   const scope = opts.user ? "user" : "repo";
   await runAgentsList(agentsTargetDir(scope, process.cwd()), scope);
 });
-if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (realpathSync2(process.argv[1]) === fileURLToPath(import.meta.url)) {
   await program.parseAsync(process.argv);
 }
 export {