arcane-cli 1.17.0 → 1.17.2

package/dist/assets/.arcane/governance/universal-agent-rules.md

@@ -34,7 +34,7 @@ See also: [[README]], [[DECISIONS]], [[governance/git-conventions|Git Convention
 
 7. **Use wiki-links for cross-references. Enforcement: explicitly advisory prose (ARC-023) — no link-checker validates wiki-link usage or resolution across this repo's docs.** (e.g., `[[DECISIONS#ADR-NNN|Short Title]]`, `[[journal/YYYY-MM-DD-topic-slug|Session Label]]`). This enables knowledge graph visualization.
 
-8. **Use Mermaid for diagrams. Enforcement: explicitly advisory prose (ARC-023) — no lint validates diagram block type or the generated-state-diagrams determinism convention.** (` ```mermaid ` blocks) for all flow charts, architecture diagrams, and sequence diagrams. Directory trees stay as plain code blocks. Spell output describing state the spell already computed — not authored, freehand explanatory content — additionally follows the **generated state diagrams** convention ([ARC-036](https://github.com/codemagicianhq/arcane/blob/main/DECISIONS.md#arc-036--generated-state-diagrams-deterministic-mermaid-for-computed-spell-state)): a deterministic, data-derived Mermaid diagram built only from values already in scope, never modeled or invented. Skip it for one-line outputs, speed-rule spells, or any state with only a single reading — the diagram exists to make relationships between multiple already-computed values legible, not to decorate simple output.
+8. **Use Mermaid for diagrams. Enforcement: explicitly advisory prose (ARC-023) — no lint validates diagram block type or the generated-state-diagrams determinism convention.** (` ```mermaid ` blocks) for all flow charts, architecture diagrams, and sequence diagrams. Directory trees stay as plain code blocks. Spell output describing state the spell already computed — not authored, freehand explanatory content — additionally follows the **generated state diagrams** convention ([ARC-036](https://github.com/codemagicianhq/arcane/blob/main/DECISIONS.md#arc-036--generated-state-diagrams-deterministic-mermaid-for-computed-spell-state)): a deterministic, data-derived Mermaid diagram built only from values already in scope, never modeled or invented. Skip it for one-line outputs, speed-rule spells, or any state with only a single reading — the diagram exists to make relationships between multiple already-computed values legible, not to decorate simple output. A `gitGraph` that draws commits labels every commit `<short-sha> <summary>`: the short SHA, then two to five words taken from the commit subject already in scope, never the SHA alone, so the diagram reads without the log beside it.
 
 9. **Journal files use date-prefix naming. Enforcement: explicitly advisory prose (ARC-023) — `checkSessionContinuity` only verifies `journal/.gitkeep` exists, not that individual journal filenames follow the date-prefix pattern.** `journal/YYYY-MM-DD-topic-slug.md` for chronological sorting.
 

package/dist/assets/.arcane/spells/spell-close-session.md

@@ -266,11 +266,12 @@ Output format:
 
   ```mermaid
   gitGraph
-     commit id: "<short-sha 1> succeeded"
-     commit id: "<short-sha 2> pending"
+     commit id: "<short-sha 1> <summary 1> succeeded"
+     commit id: "<short-sha 2> <summary 2> pending"
   ```
 
-  One commit per session commit, in order, `id` carrying its short SHA and step 1b's classification —
+  One commit per session commit, in order, `id` carrying its short SHA, a two-to-five-word summary of its
+  subject (rule 8) and step 1b's classification —
   never claim `succeeded` for anything step 1b did not confirm as such.
 
 ## Journal Updates

package/dist/assets/.arcane/spells/spell-commit-work.md

@@ -5,7 +5,7 @@ tagline: Conventional commits, written for you
 claude_description: Use PROACTIVELY whenever committing work during a session, even if the user just says 'commit this'.
 argument-hint: Optional focus (e.g., security, prompts, agents, infrastructure)
 agent: agent
-last_updated: 2026-07-05
+last_updated: 2026-11-04
 ---
 
 ## Executive Summary
@@ -312,11 +312,13 @@ trunk) or no usable remote (nothing to compare against):
 gitGraph
    commit id: "<target HEAD short-sha>"
    branch <branch-name>
-   commit id: "<short-sha 1>"
-   commit id: "<short-sha 2>"
+   commit id: "<short-sha 1> <summary 1>"
+   commit id: "<short-sha 2> <summary 2>"
 ```
 
-One commit per entry in the gathered commit list, in the same order; omit the diagram (not just the
-commits) if that list is empty. Use `<target>`'s short SHA as the fork-point commit id.
+One commit per entry in the gathered commit list, in the same order, each `id` carrying the short SHA and
+then a two-to-five-word summary of that commit's subject (`<short-sha> <summary>`, rule 8): the SHA
+identifies the point, the words say what it is, so the diagram reads without the log beside it. Omit the
+diagram (not just the commits) if that list is empty. Use `<target>`'s short SHA as the fork-point commit id.
 
 **Next:** Continue work or run `spell-close-session` to finalize journal and session docs.

package/dist/assets/.arcane/spells/spell-create-pull-request.md

@@ -5,7 +5,7 @@ tagline: Open a PR with full context
 claude_description: Use PROACTIVELY whenever opening a pull request for the current branch, even if the user just says 'open a PR'.
 argument-hint: '[--draft] [--reviewers <name,...>] [--target <branch>] [--docs-only]'
 agent: agent
-last_updated: 2026-07-05
+last_updated: 2026-11-04
 ---
 
 ## Executive Summary
@@ -263,12 +263,13 @@ so they need no edit.
   gitGraph
      commit id: "<target HEAD short-sha>"
      branch <branch-name>
-     commit id: "<short-sha 1>"
-     commit id: "<short-sha 2>"
+     commit id: "<short-sha 1> <summary 1>"
+     commit id: "<short-sha 2> <summary 2>"
   ```
 
   Same shape `spell-commit-work` uses for the identical concept — reference it rather than re-deriving
-  the rule (D8): one commit per gathered log entry, target's short SHA as the fork point.
+  the rule (D8): one commit per gathered log entry labelled `<short-sha> <summary>` (rule 8), target's short SHA
+  as the fork point.
 
 ## Rules
 

package/dist/assets/.github/prompts/spell-commit-work.prompt.md

@@ -5,7 +5,7 @@ tagline: Conventional commits, written for you
 claude_description: Use PROACTIVELY whenever committing work during a session, even if the user just says 'commit this'.
 argument-hint: Optional focus (e.g., security, prompts, agents, infrastructure)
 agent: agent
-last_updated: 2026-07-05
+last_updated: 2026-11-04
 ---
 
 This prompt is the Arcane `spell-commit-work` spell. Read [`.arcane/spells/spell-commit-work.md`](../../.arcane/spells/spell-commit-work.md) and follow it as the complete workflow.

package/dist/assets/.github/prompts/spell-create-pull-request.prompt.md

@@ -5,7 +5,7 @@ tagline: Open a PR with full context
 claude_description: Use PROACTIVELY whenever opening a pull request for the current branch, even if the user just says 'open a PR'.
 argument-hint: '[--draft] [--reviewers <name,...>] [--target <branch>] [--docs-only]'
 agent: agent
-last_updated: 2026-07-05
+last_updated: 2026-11-04
 ---
 
 This prompt is the Arcane `spell-create-pull-request` spell. Read [`.arcane/spells/spell-create-pull-request.md`](../../.arcane/spells/spell-create-pull-request.md) and follow it as the complete workflow.

package/dist/index.js

@@ -14,7 +14,7 @@ import { dirname as dirname5, join as join8 } from "path";
 import chalk2 from "chalk";
 
 // src/modules/copier.ts
-import { lstatSync } from "fs";
+import { lstatSync, readlinkSync } from "fs";
 import {
   mkdir,
   access,
@@ -406,6 +406,44 @@ function validateRealTargetDirectory(targetDir, relativeDir) {
   const escape = findLinkedEscape(targetDir, relativeDir);
   if (escape !== null) throw new LinkedDirectoryError(relativeDir, escape, targetDir);
 }
+var LinkedFileError = class extends LinkedDirectoryError {
+  constructor(relativePath, escape, targetDir) {
+    super(relativePath, escape, targetDir);
+    this.message = `Linked file: "${relativePath}" is a link to "${escape.resolvesTo}" outside target directory "${targetDir}". Arcane writes managed files only inside the target directory: replace the link with a regular file, then run the command again.`;
+    this.name = "LinkedFileError";
+  }
+};
+var MAX_LINK_HOPS = 40;
+function resolveWriteDestination(absPath) {
+  let current = absPath;
+  for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+    let isLink;
+    try {
+      isLink = lstatSync(current).isSymbolicLink();
+    } catch {
+      return resolveRealPath(current);
+    }
+    if (!isLink) return resolveRealPath(current);
+    current = path.resolve(resolveRealPath(path.dirname(current)), readlinkSync(current));
+  }
+  return null;
+}
+function findLinkedFileEscape(targetDir, relativePath) {
+  const abs = path.resolve(targetDir, relativePath);
+  try {
+    if (!lstatSync(abs).isSymbolicLink()) return null;
+  } catch {
+    return null;
+  }
+  const destination = resolveWriteDestination(abs);
+  if (destination !== null && isWithin(resolveRealPath(path.resolve(targetDir)), destination)) return null;
+  return { link: relativePath.replace(/\\/g, "/"), resolvesTo: destination ?? "a loop of links" };
+}
+function validateRealTargetFile(targetDir, relativePath) {
+  validateRealTargetPath(targetDir, relativePath);
+  const escape = findLinkedFileEscape(targetDir, relativePath);
+  if (escape !== null) throw new LinkedFileError(relativePath, escape, targetDir);
+}
 function findLinkedEscapes(targetDir, files) {
   const byDirectory = /* @__PURE__ */ new Map();
   const byLink = /* @__PURE__ */ new Map();
@@ -709,8 +747,9 @@ async function resolveSecretsScanExcludePrefixes(targetDir) {
   }
   return [];
 }
-async function writeManifest(targetDir, manifest) {
+async function writeManifest(targetDir, manifest, opts = {}) {
   const filePath = manifestPath(targetDir);
+  if (!opts.followLinks) validateRealTargetFile(targetDir, path2.relative(path2.resolve(targetDir), filePath));
   let existing = "";
   try {
     existing = await readFile2(filePath, "utf-8");
@@ -2326,6 +2365,39 @@ function validateAgentDefinition(value, source) {
   if (issues.length > 0) throw new AgentConfigValidationError(source, issues);
   return definition;
 }
+function hasControlCharacter(value) {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code === 127) return true;
+  }
+  return false;
+}
+var OPENCLAW_HOME = "~/.openclaw";
+function requirePathSegment(value, field, issues) {
+  if (typeof value !== "string") {
+    requireString(value, field, issues);
+    return;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "..") {
+    issues.push(`${field} must name something other than "${value}"`);
+  } else if (hasControlCharacter(value)) {
+    issues.push(`${field} must not contain a control character such as a newline`);
+  } else if (/[\\/]/.test(value)) {
+    issues.push(`${field} must not contain "/" or "\\"; it becomes a file name`);
+  }
+}
+function requireOpenClawRoot(value, field, issues) {
+  if (typeof value !== "string") {
+    requireString(value, field, issues);
+    return;
+  }
+  const segments = value.split("/");
+  const insideHome = (value === OPENCLAW_HOME || value.startsWith(`${OPENCLAW_HOME}/`)) && !hasControlCharacter(value) && !value.includes("\\") && !segments.slice(2).some((s) => s === "." || s === "..");
+  if (!insideHome) {
+    issues.push(`${field} must be "${OPENCLAW_HOME}" or a folder inside it, not "${value}"`);
+  }
+}
 function validateAgentRoster(value, source) {
   const issues = [];
   const parsed = requireRecord(value, "roster", issues);
@@ -2352,7 +2424,7 @@ function validateAgentRoster(value, source) {
   const openclaw = requireRecord(roster.openclaw, "openclaw", issues);
   if (openclaw) {
     requireBoolean(openclaw.enabled, "openclaw.enabled", issues);
-    requireString(openclaw.workspace_root, "openclaw.workspace_root", issues);
+    requireOpenClawRoot(openclaw.workspace_root, "openclaw.workspace_root", issues);
   }
   if (!Array.isArray(roster.roster)) {
     issues.push("roster must be an array");
@@ -2361,9 +2433,14 @@ function validateAgentRoster(value, source) {
       const item = requireRecord(entry, `roster[${index}]`, issues);
       if (!item) return;
       requireString(item.definition, `roster[${index}].definition`, issues);
-      if (item.name !== null) requireString(item.name, `roster[${index}].name`, issues);
-      requireString(item.id, `roster[${index}].id`, issues);
-      if (item.epithet !== void 0) requireString(item.epithet, `roster[${index}].epithet`, issues);
+      if (item.name !== null) requirePathSegment(item.name, `roster[${index}].name`, issues);
+      requirePathSegment(item.id, `roster[${index}].id`, issues);
+      if (item.epithet !== void 0) {
+        requireString(item.epithet, `roster[${index}].epithet`, issues);
+        if (typeof item.epithet === "string" && hasControlCharacter(item.epithet)) {
+          issues.push(`roster[${index}].epithet must not contain a control character such as a newline`);
+        }
+      }
     });
   }
   if (issues.length > 0) throw new AgentConfigValidationError(source, issues);
@@ -2453,7 +2530,7 @@ var MalformedMarkersError = class extends Error {
   }
 };
 async function mergeIntoFile(targetDir, relativePath, content, opts = {}) {
-  validateRealTargetPath(targetDir, relativePath);
+  validateRealTargetFile(targetDir, relativePath);
   const destPath = path3.resolve(targetDir, relativePath);
   let existing;
   try {
@@ -2513,7 +2590,7 @@ ${MARKER_END}
   return true;
 }
 async function stripMarkerSection(targetDir, relativePath, opts = {}) {
-  validateRealTargetPath(targetDir, relativePath);
+  validateRealTargetFile(targetDir, relativePath);
   const destPath = path3.resolve(targetDir, relativePath);
   let existing;
   try {
@@ -2538,6 +2615,7 @@ async function stripMarkerSection(targetDir, relativePath, opts = {}) {
 }
 
 // src/modules/agent-generator.ts
+var OPENCLAW_WORKSPACE_FILES = ["IDENTITY.md", "SOUL.md", "TOOLS.md"];
 function renderIdentity(def, name) {
   const mottosLine = def.persona.catchphrases && def.persona.catchphrases.length > 0 ? `
 ## Mottos
@@ -2727,6 +2805,12 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       if (!def.clients.openclaw) continue;
       const workspaceName = entry.id === "main" ? "workspace" : `workspace-${entry.id}`;
       const workspaceDir = join4(openclawRoot, workspaceName);
+      if (!options.dryRun) {
+        validateRealTargetDirectory(openclawRoot, workspaceName);
+        for (const file of OPENCLAW_WORKSPACE_FILES) {
+          validateRealTargetFile(openclawRoot, `${workspaceName}/${file}`);
+        }
+      }
       try {
         if (!options.dryRun) {
           await mkdir3(workspaceDir, { recursive: true });
@@ -2769,6 +2853,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
     const generatedDir = join4(targetDir, ".arcane", "generated");
     if (!options.dryRun) {
       validateRealTargetDirectory(targetDir, ".arcane/generated");
+      validateRealTargetFile(targetDir, ".arcane/generated/openclaw-roster.json");
       await mkdir3(generatedDir, { recursive: true });
       await writeFile5(
         join4(generatedDir, "openclaw-roster.json"),
@@ -2801,7 +2886,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       }
       if (repoOptedOut) continue;
       if (!options.dryRun) {
-        validateRealTargetPath(targetDir, `.github/agents/${fileName}`);
+        validateRealTargetFile(targetDir, `.github/agents/${fileName}`);
         await writeFile5(join4(agentsDir, fileName), content, "utf8");
       } else {
         console.log(`  [dry-run] Would write: .github/agents/${fileName}`);
@@ -2919,7 +3004,7 @@ async function performAgentSync(targetDir, assetsDir, roster, options) {
       console.log(`  ${line}`);
     }
     if (!options.dryRun) {
-      await writeManifest(targetDir, { ...manifest, fanout: fanout.record });
+      await writeManifest(targetDir, { ...manifest, fanout: fanout.record }, { followLinks: true });
     }
   }
   if (result.unmanagedAgentFiles.length > 0) {
@@ -3041,7 +3126,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   if (!options.dryRun) {
     if (scope === "repo") {
       validateRealTargetDirectory(targetDir, ".arcane/agents");
-      validateRealTargetPath(targetDir, ".arcane/agents.yaml");
+      validateRealTargetFile(targetDir, ".arcane/agents.yaml");
     }
     await mkdir4(arcaneDir, { recursive: true });
     await writeFile6(join5(baseDir, "agents.yaml"), stringify(roster), "utf8");
@@ -3052,6 +3137,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     const src = join5(assetsDir, "agents", `${roleId}.yaml`);
     const dest = join5(arcaneDir, `${roleId}.yaml`);
     if (!options.dryRun) {
+      if (scope === "repo") validateRealTargetFile(targetDir, `.arcane/agents/${roleId}.yaml`);
       try {
         await copyFile2(src, dest);
       } catch {
@@ -3685,6 +3771,7 @@ async function installHook(cwd, hookName, body) {
     return { status: "already-ours" };
   }
   validateRealTargetDirectory(root, ARCANE_HOOKS_DIR);
+  validateRealTargetFile(root, `${ARCANE_HOOKS_DIR}/${hookName}`);
   await mkdir5(join7(root, ARCANE_HOOKS_DIR), { recursive: true });
   await writeFile8(hookPath, body, "utf-8");
   await chmod(hookPath, 493);
@@ -4665,7 +4752,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
     scope: "user",
     fanout: fanout.record
   };
-  await writeManifest(storeRoot, manifest);
+  await writeManifest(storeRoot, manifest, { followLinks: true });
   printStep(`\u2728 ${fileCount} Spells installed to ${storeRoot}/spells/`);
   for (const line of describeFanoutOutcomes(fanout.outcomes)) {
     if (line.startsWith("!")) printWarning(line.slice(2));
@@ -5656,7 +5743,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         for (const line of describeFanoutOutcomes(fanout.outcomes, options.dryRun)) console.log(`  ${line}`);
         const scopePatch = defaultScopePatch(options, manifest);
         if (!options.dryRun && (JSON.stringify(fanout.record) !== JSON.stringify(manifest.fanout ?? {}) || scopePatch !== void 0)) {
-          await writeManifest(targetDir, { ...manifest, ...scopePatch, fanout: fanout.record });
+          await writeManifest(targetDir, { ...manifest, ...scopePatch, fanout: fanout.record }, { followLinks: scope === "user" });
         }
       }
       return;
@@ -5994,7 +6081,7 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     ...fanoutRecord !== void 0 ? { fanout: fanoutRecord } : {},
     ...defaultScopePatch(options, manifest)
   };
-  await writeManifest(targetDir, updated);
+  await writeManifest(targetDir, updated, { followLinks: scope === "user" });
   console.log(
     `
 \u2713 Updated ${fileCount} files.`
@@ -8185,6 +8272,13 @@ async function fixSessionContinuity(targetDir, assetsDir) {
         );
         continue;
       }
+      const fileEscape = findLinkedFileEscape(targetDir, file);
+      if (fileEscape !== null) {
+        console.log(
+          `    ! Not created: ${file} \u2014 it is a link to "${fileEscape.resolvesTo}" outside "${resolve7(targetDir)}".`
+        );
+        continue;
+      }
       const srcPath = join22(assetsDir, file);
       await mkdir7(dirname11(destPath), { recursive: true });
       await fsCopyFile(srcPath, destPath);