arcane-cli 0.26.0 → 0.26.1

package/dist/assets/.arcane/governance/git-conventions.md

@@ -478,6 +478,17 @@ git branch -d <branch>                    # delete local branch (skip if branch
 git push origin --delete <branch>         # delete remote branch (safety net — --delete-source-branch true usually handles this; ignore 'does not exist' errors)
 ```
 
+**MCP fail-fast / fallback rule:** one abnormal MCP tool failure — a hang, an idle-timeout abort, a
+transport error, or an empty response where data is clearly expected — marks that MCP server **down
+for the rest of the session**. Do not retry it blindly. All subsequent operations that would have used
+it fall back to the documented CLI (`az repos pr` / `gh` / a direct REST call), and the downgrade is
+reported in output so a human sees it happened. The known-issues rows below (`MCP vote_pull_request`,
+`MCP create_pull_request`) are concrete instances of this general rule, not special cases of their own.
+**Consumer hardening:** set a per-server `"timeout"` (milliseconds) in `.mcp.json` so a hang aborts on a
+predictable schedule instead of running to the client's own default idle limit (as long as 30 minutes).
+Origin: a real ops session lost roughly an hour to two consecutive 30-minute MCP hangs before the
+documented `az` fallback was used (2026-08-14).
+
 **Known issues:**
 
 | Issue                                                                          | Symptom                               | Fix                                                                             |

package/dist/assets/.github/instructions/agent-output.instructions.md

@@ -81,6 +81,13 @@ When completing a PR via `az repos pr update`, do **not** pass `--squash true`.
 az repos pr update --id <PR_ID> --org https://dev.azure.com/<org> --status completed --delete-source-branch true
 ```
 
+## MCP Fail-Fast / Fallback
+
+One abnormal MCP tool failure (hang, idle-timeout abort, transport error, empty response where data is
+expected) marks that server down for the rest of the session — fall back to the documented CLI (`az
+repos pr` / `gh` / REST), no blind retries, and report the downgrade in output. Full rule and origin
+incident: `.arcane/governance/git-conventions.md` → Known issues.
+
 ## Branch Naming (Interactive Sessions)
 
 Interactive tool session branches use:

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

@@ -152,6 +152,8 @@ Workflow:
 
    a. Run `git push origin <branch>`.
 
+   a1. **MCP fail-fast / fallback.** If an MCP tool used anywhere in this step (e.g. `create_pull_request`) fails abnormally once — a hang, an idle-timeout abort, a transport error, or an empty response where data is clearly expected — treat that server as down for the rest of this session. Do not retry it blindly; fall back to the raw CLI paths below (`gh pr create` / `az repos pr create`) and report the downgrade. Full rule: `.arcane/governance/git-conventions.md` → Known issues.
+
    b. **🛑 Mandatory pre-PR rebase (governance guard, applies to every path below).** Before invoking any PR-creation command — whether via `spell-create-pull-request`, raw `gh pr create`, raw `az repos pr create`, or an MCP `create_pull_request` tool — you MUST:
 
    ```bash

package/dist/assets/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "Example MCP server config. Replace or remove the example server below with your own. Set a per-server \"timeout\" (milliseconds) so a hung server aborts on a predictable schedule instead of running to the client's own default idle limit (as long as 30 minutes) -- see .arcane/governance/git-conventions.md's MCP fail-fast / fallback rule.",
+  "mcpServers": {
+    "example-server": {
+      "command": "npx",
+      "args": ["-y", "@example/mcp-server"],
+      "timeout": 30000
+    }
+  }
+}

package/dist/index.js

@@ -428,6 +428,15 @@ var COMPONENTS = [
     skipExisting: true,
     initOnly: true
   },
+  // Optional MCP config scaffold (BC-22/I12). skipExisting: a repo's own
+  // .mcp.json is user-owned server config Arcane must never overwrite.
+  // Not initOnly -- useful to retrofit via `spell add` on an existing repo too.
+  {
+    name: "mcp-config-template",
+    description: "Example .mcp.json with a per-server timeout, companion to the MCP fail-fast rule",
+    files: [".mcp.json"],
+    skipExisting: true
+  },
   {
     name: "records-conventions",
     description: "Supersession, tombstone, and retention conventions for records repositories",
@@ -4067,6 +4076,47 @@ async function checkPushPolicy(targetDir) {
     message: `declared "blocked" but not enforced \u2014 ${missing.join("; ")}. The manifest claims a protection this repository does not have.`
   };
 }
+async function checkMcpConfig(targetDir) {
+  const name = "MCP config (per-server timeout, I12)";
+  const filePath = join11(targetDir, ".mcp.json");
+  let raw;
+  try {
+    raw = await readFile6(filePath, "utf8");
+  } catch {
+    return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: ".mcp.json exists but contains invalid JSON"
+    };
+  }
+  const servers = parsed.mcpServers ?? {};
+  const serverNames = Object.keys(servers);
+  if (serverNames.length === 0) {
+    return { name, passed: true, blocking: false, message: "no MCP servers configured" };
+  }
+  const missingTimeout = serverNames.filter((n) => typeof servers[n]?.timeout !== "number");
+  if (missingTimeout.length > 0) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `server(s) missing a "timeout": ${missingTimeout.join(", ")} \u2014 a hang runs to the client's own default idle limit (up to 30 min) instead of a predictable one`
+    };
+  }
+  return {
+    name,
+    passed: true,
+    blocking: false,
+    message: `${serverNames.length} server(s) configured, all with a timeout set`
+  };
+}
 async function checkDelegations(targetDir) {
   const name = "Standing delegations (T13)";
   const filePath = join11(targetDir, ".arcane", "delegations.json");
@@ -4152,7 +4202,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkPullRebase(targetDir),
     checkPushPolicy(targetDir),
     checkPlatformBranchPolicy(targetDir),
-    checkDelegations(targetDir)
+    checkDelegations(targetDir),
+    checkMcpConfig(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);