@papi-ai/server 0.7.77 → 0.7.79

package/dist/index.js

@@ -561,11 +561,13 @@ function ensureTagAtHead(cwd, tag, message) {
     message: `tag "${tag}" already exists but points at ${target ? target.slice(0, 7) : "an unknown commit"}, not the current HEAD (${head ? head.slice(0, 7) : "unknown"}). If it is left over from an aborted release, delete it and re-run release: \`git tag -d ${tag}\` (and \`git push origin :refs/tags/${tag}\` if it was pushed). Otherwise use a different version.`
   };
 }
-function getLatestTag(cwd) {
+function getLatestTag(cwd, timeoutMs) {
   try {
     return execFileSync("git", ["describe", "--tags", "--abbrev=0"], {
       cwd,
-      encoding: "utf-8"
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...timeoutMs != null ? { timeout: timeoutMs } : {}
     }).trim() || null;
   } catch {
     return null;
@@ -807,20 +809,26 @@ function findTaskCommitsOnBase(cwd, preferredBase, displayIds) {
   try {
     raw = execFileSync(
       "git",
-      ["log", base, "--format=%h%x01%s", "-n", "1000"],
+      ["log", base, "--format=%h%x01%s%x01%b%x02", "-n", "1000"],
       { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
     );
   } catch {
     return out;
   }
-  const commits = raw.split("\n").map((line) => {
-    const idx = line.indexOf("
");
-    if (idx === -1) return null;
-    return { hash: line.slice(0, idx).trim(), subject: line.slice(idx + 1).trim() };
-  }).filter((c) => c !== null && c.hash !== "");
+  const commits = raw.split("").map((record) => {
+    const parts = record.split("
");
+    if (parts.length < 2) return null;
+    return {
+      hash: parts[0].trim(),
+      subject: parts[1].trim(),
+      body: (parts[2] ?? "").trim()
+    };
+  }).filter(
+    (c) => c !== null && c.hash !== ""
+  );
   for (const displayId of displayIds) {
     const re = new RegExp(`(^|[^\\w-])${escapeRegexLiteral(displayId)}([^\\w-]|$)`);
-    const hit = commits.find((c) => re.test(c.subject));
+    const hit = commits.find((c) => re.test(c.subject)) ?? commits.find((c) => re.test(c.body));
     if (!hit) continue;
     const prMatch = hit.subject.match(/#(\d+)/);
     out.set(displayId, {
@@ -1406,10 +1414,39 @@ var init_proxy_adapter = __esm({
       endpoint;
       apiKey;
       projectId;
+      onAuthRejected;
       constructor(config2) {
         this.endpoint = config2.endpoint.replace(/\/$/, "");
         this.apiKey = config2.apiKey;
         this.projectId = config2.projectId ?? "";
+        this.onAuthRejected = config2.onAuthRejected;
+      }
+      /**
+       * task-1773: bearer-only auth probe. Hits the USER-scoped `project-list` route
+       * (no projectId needed), so it answers exactly one question: does the proxy
+       * still accept this bearer?
+       *
+       * Returns the HTTP status, or 0 when the call could not be made at all
+       * (network error / timeout). Callers MUST treat 0 — and any status that is
+       * neither 2xx nor 401 — as "no signal", never as a rejection: a proxy outage
+       * must not masquerade as a revoked token and force every user to re-auth.
+       */
+      async probeBearerStatus() {
+        try {
+          const response = await fetch(`${this.endpoint}/project-list`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${this.apiKey}`
+            },
+            body: "{}",
+            signal: AbortSignal.timeout(5e3)
+          });
+          if (response.status === 401) this.onAuthRejected?.();
+          return response.status;
+        } catch {
+          return 0;
+        }
       }
       /** Resolved project ID — available after ensureProject() completes. */
       getProjectId() {
@@ -1426,7 +1463,8 @@ var init_proxy_adapter = __esm({
         return wrapWithForwarding(new _ProxyPapiAdapter({
           endpoint: this.endpoint,
           apiKey: this.apiKey,
-          projectId
+          projectId,
+          onAuthRejected: this.onAuthRejected
         }));
       }
       /**
@@ -1513,6 +1551,7 @@ var init_proxy_adapter = __esm({
             message = errorBody;
           }
           if (response.status === 401) {
+            this.onAuthRejected?.();
             throw new Error(
               `Auth: Invalid API key \u2014 PAPI_DATA_API_KEY was rejected by the proxy.
 This usually means the key was revoked or replaced. Mint a fresh key in the Connect panel on your PAPI dashboard (https://getpapi.ai/hub), then update PAPI_DATA_API_KEY in your .mcp.json.
@@ -2091,6 +2130,7 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
           } catch {
             message = errorBody;
           }
+          if (response.status === 401) this.onAuthRejected?.();
           throw new Error(`Proxy error (${response.status}) on ${route}: ${message}`);
         }
         const body = await response.json();
@@ -4412,7 +4452,7 @@ __export(doctor_exports, {
 });
 import { existsSync as existsSync12, readFileSync as readFileSync15 } from "fs";
 import { homedir as homedir4 } from "os";
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 function redact(name, value) {
   if (!value) return "(empty)";
   if (SECRET_VARS.has(name)) {
@@ -4423,9 +4463,9 @@ function redact(name, value) {
 }
 function findMcpJson() {
   const candidates = [
-    join21(process.cwd(), ".mcp.json"),
-    join21(homedir4(), ".claude", ".mcp.json"),
-    join21(homedir4(), ".mcp.json")
+    join22(process.cwd(), ".mcp.json"),
+    join22(homedir4(), ".claude", ".mcp.json"),
+    join22(homedir4(), ".mcp.json")
   ];
   for (const path7 of candidates) {
     if (!existsSync12(path7)) continue;
@@ -4708,9 +4748,9 @@ __export(reset_exports, {
   removePapiEntry: () => removePapiEntry,
   runReset: () => runReset
 });
-import { existsSync as existsSync13, readFileSync as readFileSync16, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync16, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 import { createInterface } from "readline/promises";
 function findResetTarget() {
   for (const path7 of CANDIDATE_PATHS()) {
@@ -4789,7 +4829,7 @@ async function runReset(args = []) {
     }
   }
   try {
-    writeFileSync8(target.path, removePapiEntry(target), "utf-8");
+    writeFileSync9(target.path, removePapiEntry(target), "utf-8");
     process.stdout.write(`
 \u2713 Removed papi entry from ${target.path}
 `);
@@ -4806,9 +4846,9 @@ var init_reset = __esm({
   "src/cli/reset.ts"() {
     "use strict";
     CANDIDATE_PATHS = () => [
-      join22(process.cwd(), ".mcp.json"),
-      join22(homedir5(), ".claude", ".mcp.json"),
-      join22(homedir5(), ".mcp.json")
+      join23(process.cwd(), ".mcp.json"),
+      join23(homedir5(), ".claude", ".mcp.json"),
+      join23(homedir5(), ".mcp.json")
     ];
   }
 });
@@ -4821,7 +4861,7 @@ __export(audit_exports, {
 });
 import { existsSync as existsSync14, readFileSync as readFileSync17, readdirSync as readdirSync7 } from "fs";
 import { homedir as homedir6 } from "os";
-import { join as join23 } from "path";
+import { join as join24 } from "path";
 function safeListDirs(dir) {
   try {
     return readdirSync7(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort((a, b2) => a.localeCompare(b2));
@@ -4837,7 +4877,7 @@ function safeListFiles(dir, ext) {
   }
 }
 function readMcp(projectPath) {
-  const path7 = join23(projectPath, ".mcp.json");
+  const path7 = join24(projectPath, ".mcp.json");
   if (!existsSync14(path7)) return { servers: [] };
   try {
     const parsed = JSON.parse(readFileSync17(path7, "utf-8"));
@@ -4872,18 +4912,18 @@ function auditProjectSync(projectPath, name) {
     path: projectPath,
     papiProjectId,
     mcpServers: servers,
-    skills: safeListDirs(join23(projectPath, ".claude", "skills")),
-    agentSkills: safeListDirs(join23(projectPath, ".agents", "skills")),
-    agents: safeListFiles(join23(projectPath, ".claude", "agents"), ".md"),
-    hooks: safeListFiles(join23(projectPath, ".claude", "hooks"), ".sh")
+    skills: safeListDirs(join24(projectPath, ".claude", "skills")),
+    agentSkills: safeListDirs(join24(projectPath, ".agents", "skills")),
+    agents: safeListFiles(join24(projectPath, ".claude", "agents"), ".md"),
+    hooks: safeListFiles(join24(projectPath, ".claude", "hooks"), ".sh")
   };
 }
 function discoverProjects() {
   const out = [];
   for (const root of PROJECT_ROOTS) {
     for (const name of safeListDirs(root)) {
-      const path7 = join23(root, name);
-      if (existsSync14(join23(path7, ".mcp.json")) || existsSync14(join23(path7, ".claude"))) {
+      const path7 = join24(root, name);
+      if (existsSync14(join24(path7, ".mcp.json")) || existsSync14(join24(path7, ".claude"))) {
         out.push({ name, path: path7 });
       }
     }
@@ -5048,9 +5088,9 @@ var PROJECT_ROOTS, GLOBAL_SKILLS_DIR, GLOBAL_CLAUDE_JSON, IDLE_WINDOW_DAYS, GLOB
 var init_audit = __esm({
   "src/cli/audit.ts"() {
     "use strict";
-    PROJECT_ROOTS = [join23(homedir6(), "Ai-App-Projects"), join23(homedir6(), "android-projects")];
-    GLOBAL_SKILLS_DIR = join23(homedir6(), ".claude", "skills");
-    GLOBAL_CLAUDE_JSON = join23(homedir6(), ".claude.json");
+    PROJECT_ROOTS = [join24(homedir6(), "Ai-App-Projects"), join24(homedir6(), "android-projects")];
+    GLOBAL_SKILLS_DIR = join24(homedir6(), ".claude", "skills");
+    GLOBAL_CLAUDE_JSON = join24(homedir6(), ".claude.json");
     IDLE_WINDOW_DAYS = 30;
     GLOBALIZE_THRESHOLD = 3;
     __testing2 = { readMcp, computeFlags, formatReport: formatReport2, discoverProjects, auditProjectSync };
@@ -5062,8 +5102,8 @@ var setup_exports = {};
 __export(setup_exports, {
   runSetup: () => runSetup
 });
-import { existsSync as existsSync15, readFileSync as readFileSync18, writeFileSync as writeFileSync9, chmodSync as chmodSync2, statSync as statSync9 } from "fs";
-import { join as join24 } from "path";
+import { existsSync as existsSync15, readFileSync as readFileSync18, writeFileSync as writeFileSync10, chmodSync as chmodSync2, statSync as statSync9 } from "fs";
+import { join as join25 } from "path";
 function baseUrl() {
   const fromEnv = process.env["PAPI_HOST"] ?? process.env["PAPI_BASE_URL"];
   if (fromEnv) return fromEnv.replace(/\/$/, "");
@@ -5095,7 +5135,7 @@ function sleep(ms) {
   return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 function writeMcpJson(opts) {
-  const path7 = join24(process.cwd(), ".mcp.json");
+  const path7 = join25(process.cwd(), ".mcp.json");
   let parsed = {};
   if (existsSync15(path7)) {
     try {
@@ -5120,7 +5160,7 @@ function writeMcpJson(opts) {
   }
   mcpServers.papi = papiEntry;
   parsed.mcpServers = mcpServers;
-  writeFileSync9(path7, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+  writeFileSync10(path7, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
   try {
     const mode = statSync9(path7).mode & 511;
     if (mode !== 384) chmodSync2(path7, 384);
@@ -5231,7 +5271,7 @@ var init_setup = __esm({
 
 // src/index.ts
 import { readFileSync as readFileSync19 } from "fs";
-import { dirname as dirname7, join as join25, basename as basename2 } from "path";
+import { dirname as dirname7, join as join26, basename as basename2 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
@@ -5647,9 +5687,12 @@ function parsePlanningLog(content, activeDecisionsContent, cycleLogContent) {
 var VALID_EFFORT_SIZES = /* @__PURE__ */ new Set(["XS", "S", "M", "L", "XL"]);
 var SECTION_HEADERS = [
   "SCOPE (DO THIS)",
+  "WHY NOT SIMPLER",
   "SCOPE BOUNDARY (DO NOT DO THIS)",
   "ACCEPTANCE CRITERIA",
+  "PRE-MORTEM",
   "SECURITY CONSIDERATIONS",
+  "DEPLOY VERIFICATION",
   "PRE-BUILD VERIFICATION",
   "FILES LIKELY TOUCHED",
   "EFFORT"
@@ -5688,7 +5731,7 @@ function parseBulletsOnly(text) {
   return text.split("\n").filter((l) => /^\s*-\s/.test(l)).map((l) => l.replace(/^\s*-\s*/, "").trim()).filter((l) => l.length > 0);
 }
 function parseChecklist(text) {
-  return text.split("\n").map((l) => l.replace(/^\s*\[[ x]]\s*/, "").trim()).filter((l) => l.length > 0);
+  return text.split("\n").map((l) => l.replace(/^\s*(?:[-*+]\s*)?(?:\[[ xX]\]\s*)?/, "").trim()).filter((l) => l.length > 0);
 }
 function parseBuildHandoff(markdown) {
   if (typeof markdown !== "string" || !markdown.trim()) return null;
@@ -6338,13 +6381,21 @@ var EFFORT_SCALE = {
   XL: 5
 };
 function effortOrdinal(effort) {
+  if (typeof effort !== "string") return void 0;
   const normalized = effort.trim().toUpperCase();
   return EFFORT_SCALE[normalized];
 }
+function isUnparsedEffort(effort) {
+  if (typeof effort !== "string" || effort.trim().length === 0) return false;
+  return effortOrdinal(effort) === void 0;
+}
 function calculateCycleMetrics(reports, currentCycle, window = 5) {
   const recentReports = reports.filter(
     (r) => r.cycle > currentCycle - window && r.cycle <= currentCycle
   );
+  const unparsedEffortCount = recentReports.filter(
+    (r) => isUnparsedEffort(r.actualEffort) || isUnparsedEffort(r.estimatedEffort)
+  ).length;
   const perCycle = /* @__PURE__ */ new Map();
   for (const r of recentReports) {
     const group = perCycle.get(r.cycle) ?? [];
@@ -6381,7 +6432,7 @@ function calculateCycleMetrics(reports, currentCycle, window = 5) {
       effortPoints: reps.reduce((s, r) => s + (effortOrdinal(r.actualEffort) ?? 0), 0)
     });
   }
-  return { accuracy, velocity };
+  return { accuracy, velocity, unparsedEffortCount };
 }
 function serializeAccuracyRow(a) {
   return `| ${a.cycle} | ${a.reports} | ${a.matchRate}% | ${a.mae} | ${a.bias >= 0 ? "+" : ""}${a.bias} |`;
@@ -8031,6 +8082,7 @@ async function createAdapter(optionsOrType, maybePapiDir) {
     case "pg": {
       const { PgAdapter, PgPapiAdapter, configFromEnv } = await import("@papi-ai/adapter-pg");
       let projectId = process.env["PAPI_PROJECT_ID"];
+      const projectIdWasPreSupplied = Boolean(projectId);
       const projectRoot = options.projectRoot ?? process.env["PAPI_PROJECT_DIR"] ?? process.cwd();
       let rootHash = null;
       let originUrl = null;
@@ -8094,6 +8146,26 @@ async function createAdapter(optionsOrType, maybePapiDir) {
       }
       const config2 = papiEndpoint ? { connectionString: papiEndpoint } : configFromEnv();
       validateDatabaseUrl(config2.connectionString);
+      if (projectIdWasPreSupplied) {
+        const ownershipProbe = new PgAdapter(config2);
+        try {
+          const owned = await ownershipProbe.findProjectById(projectId, resolveUserId);
+          if (!owned) {
+            throw new Error(
+              `PAPI_PROJECT_ID ${projectId} does not belong to you.
+
+The project exists under a different owner, or does not exist at all. PAPI refuses to attach to a project you do not own \u2014 writing to it would put your cycles, tasks and Active Decisions into somebody else's project.
+
+Fix the PAPI_PROJECT_ID in your .mcp.json (or unset it and let PAPI resolve the project from your git remote), then reconnect.`
+            );
+          }
+        } finally {
+          try {
+            await ownershipProbe.close();
+          } catch {
+          }
+        }
+      }
       const { ensureSchema } = await import("@papi-ai/adapter-pg");
       try {
         await ensureSchema(config2);
@@ -8328,7 +8400,7 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
 // src/server.ts
 import { readFileSync as readFileSync14 } from "fs";
 import { access as access4, readdir as readdir4, readFile as readFile9 } from "fs/promises";
-import { join as join20, dirname as dirname6 } from "path";
+import { join as join21, dirname as dirname6 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -8461,15 +8533,23 @@ function formatBuildReports(reports, opts) {
 _\u2026and ${reports.length - capped.length} older build report(s) omitted to bound context size._` : "";
   return body + omitted;
 }
-function extractReferencedTaskIds(report) {
-  const prose = [report.surprises, report.architectureNotes, report.deadEnds, report.discoveredIssues].filter((s) => typeof s === "string" && s.length > 0).join("\n");
+function extractTaskReferences(report) {
+  const raw = [report.surprises, report.architectureNotes, report.deadEnds, report.discoveredIssues].filter((s) => typeof s === "string" && s.length > 0).join("\n");
+  const prose = raw.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~/g, " ").replace(/`[^`\n]*`/g, " ");
   const own = report.taskId?.toLowerCase();
-  const found = /* @__PURE__ */ new Set();
+  const resolves = /* @__PURE__ */ new Set();
+  for (const m of prose.matchAll(/\bresolves:\s*((?:task-\d+\b\s*,?\s*)+)/gi)) {
+    for (const idMatch of m[1].matchAll(/\btask-\d+\b/gi)) {
+      const id = idMatch[0].toLowerCase();
+      if (id !== own) resolves.add(id);
+    }
+  }
+  const mentions = /* @__PURE__ */ new Set();
   for (const m of prose.matchAll(/\btask-\d+\b/gi)) {
     const id = m[0].toLowerCase();
-    if (id !== own) found.add(id);
+    if (id !== own && !resolves.has(id)) mentions.add(id);
   }
-  return [...found].sort();
+  return { resolves: [...resolves].sort(), mentions: [...mentions].sort() };
 }
 function formatRecentlyShippedCapabilities(reports) {
   const completed = reports.filter((r) => r.completed === "Yes" || r.completed === "Partial");
@@ -8485,16 +8565,26 @@ function formatRecentlyShippedCapabilities(reports) {
     }
     return parts.join("\n");
   });
+  const resolvedBy = /* @__PURE__ */ new Map();
   const namedBy = /* @__PURE__ */ new Map();
   const completedIds = new Set(completed.map((r) => r.taskId?.toLowerCase()).filter(Boolean));
+  const record = (into, ref, namer) => {
+    const namers = into.get(ref) ?? [];
+    namers.push(namer);
+    into.set(ref, namers);
+  };
   for (const r of completed) {
-    for (const ref of extractReferencedTaskIds(r)) {
+    const { resolves, mentions } = extractTaskReferences(r);
+    for (const ref of resolves) {
       if (completedIds.has(ref)) continue;
-      const namers = namedBy.get(ref) ?? [];
-      namers.push(r.taskId);
-      namedBy.set(ref, namers);
+      record(resolvedBy, ref, r.taskId);
+    }
+    for (const ref of mentions) {
+      if (completedIds.has(ref)) continue;
+      record(namedBy, ref, r.taskId);
     }
   }
+  for (const ref of resolvedBy.keys()) namedBy.delete(ref);
   const out = [
     `${completed.length} task(s) completed in recent cycles:`,
     "",
@@ -8502,17 +8592,31 @@ function formatRecentlyShippedCapabilities(reports) {
     "",
     "Cross-reference candidate tasks against this list. If >80% of a candidate task's scope appears here, recommend cancellation or scope reduction instead of scheduling."
   ];
+  if (resolvedBy.size > 0) {
+    out.push(
+      "",
+      "### \u26A0 Declared resolved by a shipped task \u2014 VERIFY, THEN CLOSE",
+      "",
+      "A shipped report explicitly claimed each of these with `resolves: <task-id>`, but",
+      "the task is not itself marked complete. That is a declaration of intent, not proof:",
+      "confirm against the live code, then close it with a boardCorrection rather than",
+      "spending a cycle slot on work that already shipped.",
+      "",
+      ...[...resolvedBy.entries()].sort(([a], [b2]) => a.localeCompare(b2)).map(([ref, namers]) => `- **${ref}** \u2014 declared resolved by ${namers.join(", ")}`)
+    );
+  }
   if (namedBy.size > 0) {
     out.push(
       "",
       "### \u26A0 Named by a shipped task \u2014 VERIFY BEFORE SCHEDULING",
       "",
-      "These task IDs are referenced in the build reports above but are NOT themselves",
-      "completed. A discovery is often fixed as a side effect of a sibling task's diff and",
-      "never marked done, so it survives into this plan carrying notes that are no longer",
-      "true (C357 gave task-3043 a P1 slot this way \u2014 task-2998 had already fixed it).",
-      "For each one below: check the naming report and the live code BEFORE scheduling it.",
-      "If it is already fixed, close it with a boardCorrection instead of spending a slot.",
+      "These task IDs merely APPEAR in the build reports above \u2014 no report claimed to have",
+      "resolved them, and they are not themselves completed. A discovery is often fixed as a",
+      "side effect of a sibling task's diff and never marked done, so it survives into this",
+      "plan carrying notes that are no longer true (C357 gave task-3043 a P1 slot this way \u2014",
+      "task-2998 had already fixed it). Weaker signal than the section above: a mention can",
+      'equally mean "related to" or "still blocked by". Read the naming report and the live',
+      "code BEFORE scheduling; never close on a mention alone.",
       "",
       ...[...namedBy.entries()].sort(([a], [b2]) => a.localeCompare(b2)).map(([ref, namers]) => `- **${ref}** \u2014 named by ${namers.join(", ")}`)
     );
@@ -9089,6 +9193,19 @@ If a candidate AD body could be invalidated by running a SQL query, refreshing a
 **Negative example (reject):** "External user feedback is now flowing. Stonebridge Systems is actively building." \u2014 this is a fact about the current state of the world. Capture as dogfood/signal observation; do not mint.
 
 This rule applies to: new ADs proposed during planning (Step 9), strategy review AD updates (section 5), and strategy_change AD updates. If you find an existing AD that violates this rule during housekeeping, propose deleting it (action: "delete") with a one-line rationale.`;
+var AD_CONFLICT_SURFACING_RULES = `**A contradiction is NOT a veto \u2014 surface it, never silently shelve it.**
+
+Active Decisions are *active*: they can be superseded, modified, or abandoned. You do NOT have authority to kill a piece of work simply because it cuts against one. That is the user's call, and they can only make it if you show it to them.
+
+**Never do any of these to a task solely because it contradicts, competes with, or duplicates the intent of an existing AD:** cancel it; drop it to P3; defer it silently; omit it from the cycle without comment; or reduce its scope down to the part that fits the AD.
+
+**Instead, emit a \`decisionConflicts\` entry** for it (see the structured-output schema) with: the task, the AD it collides with, one line on what the AD says versus what the task implies, 2-3 concrete options, and your recommendation. Also render a \`## Decisions Needed\` section in Part 1 listing the same, immediately before the BUILD HANDOFFs.
+
+Apply will park each conflicted task as **Blocked** with a \`decision-gate\` blocker pointing at that AD. It clears automatically the moment the AD is resolved, confirmed, validated, or superseded \u2014 so the work returns to the board on its own once the user has decided. The task is preserved, not killed.
+
+**Emit a conflict ONLY when the AD is the reason the work would not otherwise proceed.** If the task is fine to schedule, schedule it. If it is genuinely obsolete, duplicated, or already shipped, cancel it on THOSE grounds and say so \u2014 that is not an AD conflict. Do not manufacture conflicts to look thorough; a plan with zero real conflicts should emit an empty array.
+
+This applies equally to *competing* work: two tasks proposing rival approaches to the same problem is a decision for the user, not a coin-flip for you.`;
 var OUTPUT_QUALITY_RUBRIC = `Quality bar \u2014 before emitting, self-score the artifact 1-10 on five dimensions: (1) **Clarity** \u2014 could a third LLM act on it with no extra context? (2) **Scope tightness** \u2014 one focused unit of work, not three bundled together. (3) **Specificity** \u2014 it names concrete files/paths/tasks/ADs, not vague references like "the auth module". (4) **Dependency surfacing** \u2014 prerequisite or upstream items are called out explicitly. (5) **Success-criteria concreteness** \u2014 "done" is testable and observable, not "looks good". Sum to /50. If any single dimension scores \u22644, or the total is <35, revise the artifact and re-score before emitting \u2014 do not ship a below-threshold artifact. This is a self-check gate, not an output field: do NOT add the scores to the artifact or the structured JSON.`;
 var PLAN_SYSTEM = `You are the PAPI Cycle Planner \u2014 an autonomous planning engine for software projects.
 You receive project context and produce a planning cycle output with a BUILD HANDOFF.
@@ -9169,7 +9286,8 @@ After your natural language output, include this EXACT format on its own line:
   "newTasks": [],
   "boardCorrections": [],
   "productBrief": null,
-  "activeDecisions": []
+  "activeDecisions": [],
+  "decisionConflicts": [{"taskId": "string \u2014 an existing task ID or a newTasks tempId", "adId": "string \u2014 AD-N this collides with", "conflict": "string \u2014 one line: what the AD says vs what this task implies", "options": ["string \u2014 concrete option, e.g. 'Supersede AD-12 and schedule the task'"], "recommendation": "string \u2014 which option you would take and why, in one sentence"}]
 }
 \`\`\`
 
@@ -9206,6 +9324,7 @@ Everything in Part 1 (natural language) is **display-only**. Part 2 (structured
 - Updated or created Active Decisions in Part 1? \u2192 Put them in \`activeDecisions\` array (with id and full body including ### heading)
 - Found board corrections (wrong priority, missing fields, stale status) in Part 1? \u2192 Put them in \`boardCorrections\` array
 - Generated BUILD HANDOFFs in Part 1? \u2192 Put them in \`cycleHandoffs\` array
+- Wrote a \`## Decisions Needed\` section in Part 1? \u2192 Put every entry in \`decisionConflicts\`. Nothing in that array means the user is never asked, and the work is lost. Omit the array (or leave it empty) when there are genuinely no AD conflicts.
 - **\`complexity\` uses the LONG forms only** \u2014 "XS", "Small", "Medium", "Large", "XL". Do NOT reuse the handoff EFFORT short-forms (S/M/L) for task complexity.
 
 **Example with populated fields (DO NOT copy literally \u2014 adapt to your actual analysis):**
@@ -9393,7 +9512,7 @@ Standard planning cycle with full board review.
    **\u26A0\uFE0F PRIORITY RECALIBRATION \u2014 do NOT rubber-stamp the submitted priority.** The priority set at idea submission reflects the submitter's view at that time, which may be outdated by the time the planner runs. For EVERY unreviewed task, evaluate its priority FROM SCRATCH against: (a) current horizon/stage/phase goals, (b) recent Active Decision changes, (c) recently shipped functionality that makes this task more or less urgent. If your assessed priority differs from the submitted one, set the new priority in \`boardCorrections\` and include the change in a **Priority Recalibration** paragraph in your cycle log (Step 8): list each changed task by ID, old priority \u2192 new priority, and a 1-sentence rationale. This paragraph is how the user sees what the planner recalibrated and why. If no priorities changed during triage, omit the paragraph.
    Also set complexity using the full range \u2014 **XS, Small, Medium, Large, XL** \u2014 based on actual scope, not conservatively. XS = single-line or config change. Small = one file, < 50 lines. Medium = 2-5 files. Large = cross-module, multiple components. XL = architectural, multi-day.
    **Module classification for cross-cutting tasks:** When a task title contains "audit"/"unfiltered"/"scoping"/"leak" plus a database-entity name (e.g. "audit ... cycle_learnings reads", "unfiltered cycle_tasks queries"), classify the module by the actual code surface that reads/writes the entity \u2014 not by the tool names mentioned in the title. The reasoning surface (e.g. "health" or "strategy_review") is often unrelated to the data-access surface. Resolve this by treating the entity name as the routing signal: tasks touching dashboard read/write paths belong to the Dashboard module even if the title mentions an MCP tool. Misclassification routes the task to the wrong shared cycle branch and surfaces the wrong MODULE INSTRUCTIONS to the builder.
-   If a task is clearly obsolete, duplicated, or rejected, set its status to "Cancelled" with a \`closureReason\` explaining why.
+   If a task is clearly obsolete, duplicated, or rejected, set its status to "Cancelled" with a \`closureReason\` explaining why. **"It contradicts an Active Decision" is NOT one of those reasons** \u2014 route it to \`decisionConflicts\` instead (see the AD Conflict Surfacing rule below step 7).
    **\u2192 PERSIST:** For each task you set reviewed: true, corrected fields on, or marked "Cancelled", include it in \`boardCorrections\` in Part 2.
 
 3. **Board Integrity** \u2014 All tasks have complete fields? Priority still accurate? Duplicates? Stale In Progress tasks?
@@ -9436,6 +9555,10 @@ Standard planning cycle with full board review.
    **Epic-aware batching:** Epic is the primary grouping signal for theme coherence. When multiple candidate tasks share the same epic (e.g. "Onboarding Redesign", "Dashboard Polish"), prefer co-scheduling them \u2014 they solve connected problems and benefit from shared context during the build. Steps: (1) After filtering by priority, group eligible tasks by epic. (2) If an epic has 3+ eligible tasks, prefer scheduling 2-4 of them together over cherry-picking across epics. (3) Report the epic distribution in the cycle log (e.g. "4 tasks from Onboarding epic, 1 from Platform"). Priority still overrides: a P0 fix from a different epic always takes precedence.
    **Opportunity clustering:** If backlog tasks have an \`opportunity\` field populated, group them by opportunity before selecting. Tasks sharing the same opportunity solve the same user problem \u2014 co-scheduling them produces more coherent cycles. Report opportunity clusters in the cycle log when present (e.g. "3 tasks clustered under 'planner accuracy' opportunity").
 
+${AD_CONFLICT_SURFACING_RULES}
+
+   **Where this fires:** during Inbox Triage (step 2), the Priority Drift Check (step 3), and selection (step 7). A task whose notes already carry an \`AD-CONFLICT:\` line, or an "AD-N alignment/conflict candidate" note from the idea tool, is a mandatory candidate \u2014 read it, and either schedule it, cancel it on non-AD grounds, or emit the conflict. Do not leave it sitting silently in Backlog for a third cycle.
+
 8. **Cycle Log** \u2014 Write 5-10 line entry: what was triaged, what was recommended and why, observations, AD updates. Include a **Priority Recalibration** paragraph if any unreviewed task priorities were changed during triage (Step 2) \u2014 list each by ID with old \u2192 new priority and rationale. Include a **Priority Drift Suggestions** paragraph if reviewed task drift was detected (Step 3).
    **Cycle Notes** \u2014 Optionally include 1-3 lines of cycle-level observations in \`cycleLogNotes\`: estimation accuracy patterns, recurring blockers, velocity trends, or dependency signals. These notes persist across cycles so future planning runs can learn from them. Use null if there are no noteworthy observations this cycle.
 
@@ -9834,6 +9957,17 @@ function coerceToString(value) {
   if (value === null || value === void 0) return "";
   return JSON.stringify(value, null, 2);
 }
+function coerceCarryForward(value) {
+  if (value === null || value === void 0) return { value: null };
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return { value: trimmed.length > 0 ? trimmed : null };
+  }
+  const shape = Array.isArray(value) ? "array" : typeof value;
+  const warning = `cycleLogCarryForward was ${shape}, not a string \u2014 DROPPED rather than persisted. Carry-forward is prose that orient parses for the WHAT SHIPS FOR USERS / RELEASE MECHANICS labels; a non-string value cannot carry them. Re-run plan apply with cycleLogCarryForward as a single string (or null) to record one for this cycle.`;
+  console.error(`[plan] ${warning}`);
+  return { value: null, warning };
+}
 function coerceStructuredOutput(parsed) {
   const cycleHandoffs = Array.isArray(parsed.cycleHandoffs) ? parsed.cycleHandoffs.map((h) => {
     const { taskId: _t, buildHandoff: _b, ...rest } = h;
@@ -9873,10 +10007,19 @@ function coerceStructuredOutput(parsed) {
     body: coerceToString(ad.body)
   })) : [];
   const cycleTaskIds = Array.isArray(parsed.cycleTaskIds) ? parsed.cycleTaskIds.map((id) => coerceToString(id)) : void 0;
+  const carryForward = coerceCarryForward(parsed.cycleLogCarryForward);
+  const decisionConflicts = Array.isArray(parsed.decisionConflicts) ? parsed.decisionConflicts.map((c) => ({
+    taskId: coerceToString(c.taskId).trim(),
+    adId: coerceToString(c.adId).trim(),
+    conflict: coerceToString(c.conflict).trim(),
+    options: Array.isArray(c.options) ? c.options.map((o) => coerceToString(o)) : [],
+    recommendation: coerceToString(c.recommendation).trim()
+  })).filter((c) => c.taskId.length > 0 && c.adId.length > 0) : void 0;
   return {
     cycleLogTitle: coerceToString(parsed.cycleLogTitle),
     cycleLogContent: coerceToString(parsed.cycleLogContent),
-    cycleLogCarryForward: parsed.cycleLogCarryForward === null ? null : coerceToString(parsed.cycleLogCarryForward),
+    cycleLogCarryForward: carryForward.value,
+    ...carryForward.warning ? { coercionWarnings: [carryForward.warning] } : {},
     cycleLogNotes: parsed.cycleLogNotes === null ? null : coerceToString(parsed.cycleLogNotes),
     nextMode: "Full",
     boardHealth: coerceToString(parsed.boardHealth),
@@ -9887,7 +10030,8 @@ function coerceStructuredOutput(parsed) {
     newTasks,
     boardCorrections,
     productBrief: parsed.productBrief === null ? null : coerceToString(parsed.productBrief),
-    activeDecisions
+    activeDecisions,
+    decisionConflicts
   };
 }
 var REVIEW_SYSTEM_COMPRESSION_SECTION = `
@@ -9962,6 +10106,7 @@ You MUST cover these 5 sections. Each is mandatory.
    - Only flag ADs that represent a genuine strategic question requiring owner input
    - Note any hierarchy/phase issues worth correcting (1-2 bullets max)
    - Delete ADs that are legacy, process-level, or redundant without discussion
+   - **Blocked-on-decision tasks are evidence (task-3219).** If the board carries tasks Blocked behind a \`decision-gate\` on an AD, that AD is actively costing the project work. Resolve it here \u2014 supersede, modify, or explicitly reaffirm it with a one-line reason. Reaffirming is a legitimate answer; leaving it unaddressed is not, because the blocked work stays parked until someone rules.
 
 ${AD_REJECTION_RULES}
 
@@ -11575,6 +11720,52 @@ function applyContextTier(ctx, cycleCount) {
   }
   return { tier, label };
 }
+var PARKABLE_STATUSES = /* @__PURE__ */ new Set([
+  "Backlog",
+  "In Cycle",
+  "Ready",
+  "Deferred"
+]);
+async function parkDecisionConflicts(adapter2, conflicts, newTaskIdMap, blockedCycle, scheduledTaskIds = []) {
+  if (conflicts.length === 0) return [];
+  const scheduled = new Set(scheduledTaskIds.map((id) => id.toLowerCase()));
+  const results = [];
+  for (const conflict of conflicts) {
+    const resolvedTaskId = newTaskIdMap.get(conflict.taskId) ?? conflict.taskId;
+    const base = { ...conflict, resolvedTaskId, parked: false };
+    if (scheduled.has(resolvedTaskId.toLowerCase())) {
+      results.push({ ...base, skipReason: "scheduled in this cycle \u2014 left in the cycle, conflict still surfaced" });
+      continue;
+    }
+    try {
+      const [task] = await adapter2.getTasks([resolvedTaskId]);
+      if (!task) {
+        results.push({ ...base, skipReason: "task not found" });
+        continue;
+      }
+      if (!PARKABLE_STATUSES.has(task.status)) {
+        results.push({ ...base, skipReason: `status is ${task.status} \u2014 left as-is` });
+        continue;
+      }
+      if (task.status === "Deferred") {
+        await adapter2.updateTask(resolvedTaskId, { status: "Backlog" });
+      }
+      await adapter2.updateTask(resolvedTaskId, {
+        status: "Blocked",
+        blocker: {
+          type: "decision-gate",
+          ref: conflict.adId,
+          reason: conflict.conflict || `Contradicts ${conflict.adId} \u2014 awaiting the owner's decision.`,
+          blockedCycle
+        }
+      });
+      results.push({ ...base, parked: true });
+    } catch (err) {
+      results.push({ ...base, skipReason: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  return results;
+}
 function determineMode(totalCycles) {
   if (totalCycles === 0) return "bootstrap";
   return "full";
@@ -13086,6 +13277,7 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
   let writeBackWarnings;
   let writeSummary;
   let skippedCancellations;
+  let decisionConflicts;
   const persistenceFailed = !data;
   if (data) {
     try {
@@ -13097,8 +13289,9 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
         contextHashes,
         { confirmCancellations: planRunMeta?.confirmCancellations === true, ownerUserId: applyScope.callerUserId ?? void 0 }
       );
-      if (wbWarnings.length > 0) {
-        writeBackWarnings = wbWarnings;
+      const allWarnings = [...data.coercionWarnings ?? [], ...wbWarnings];
+      if (allWarnings.length > 0) {
+        writeBackWarnings = allWarnings;
       }
       if (skipped.length > 0) {
         skippedCancellations = skipped;
@@ -13111,6 +13304,19 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
       for (const [placeholder, realId] of newTaskIdMap) {
         resolvedDisplayText = resolvedDisplayText.replaceAll(placeholder, realId);
       }
+      if (data.decisionConflicts && data.decisionConflicts.length > 0) {
+        try {
+          const parked = await parkDecisionConflicts(
+            adapter2,
+            data.decisionConflicts,
+            newTaskIdMap,
+            cycleNumber + 1,
+            ws.taskIds
+          );
+          if (parked.length > 0) decisionConflicts = parked;
+        } catch {
+        }
+      }
       if (adapter2.insertPlanRun) {
         const durationMs = Date.now() - applyStartMs + (planRunMeta?.prepareStartMs !== void 0 ? Date.now() - planRunMeta.prepareStartMs : 0);
         adapter2.insertPlanRun({
@@ -13163,7 +13369,8 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
     writeBackFailed,
     writeBackWarnings,
     writeSummary,
-    skippedCancellations
+    skippedCancellations,
+    decisionConflicts
   };
 }
 async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density) {
@@ -13782,6 +13989,47 @@ async function resolveLlmResponse(inlineResponse, filePath) {
   return { ok: true, llmResponse: contents };
 }
 
+// src/lib/overflow.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+import { createHash as createHash2 } from "crypto";
+var DISPATCH_THRESHOLD_BYTES = 50 * 1024;
+var ELIDE_THRESHOLD_BYTES = 90 * 1024;
+var INLINE_CEILING_BYTES = 40 * 1024;
+function byteLength(s) {
+  return Buffer.byteLength(s, "utf-8");
+}
+function shouldDispatch(contextBytes, explicit) {
+  if (explicit === true) return true;
+  if (explicit === false) return false;
+  if (process.env.PAPI_AUTO_DISPATCH === "false") return false;
+  return contextBytes > DISPATCH_THRESHOLD_BYTES;
+}
+function canSpill(adapterType) {
+  return adapterType !== "proxy";
+}
+function spillPath(kind, projectId, callerKey) {
+  const id = createHash2("sha256").update(`${projectId ?? "no-project"}|${callerKey ?? "default"}`).digest("hex").slice(0, 16);
+  return join3(tmpdir(), `papi-${kind}-${id}.md`);
+}
+function spill(kind, content, projectId, callerKey) {
+  const path7 = spillPath(kind, projectId, callerKey);
+  writeFileSync2(path7, content, { mode: 384 });
+  return path7;
+}
+function planDelivery(input) {
+  const bytes = byteLength(input.payload);
+  if (bytes <= INLINE_CEILING_BYTES) return { mode: "inline", payload: input.payload };
+  if (!canSpill(input.adapterType)) return { mode: "undeliverable", bytes };
+  try {
+    const path7 = spill(input.kind, input.payload, input.projectId, input.callerKey);
+    return { mode: "spilled", path: path7, bytes };
+  } catch {
+    return { mode: "undeliverable", bytes };
+  }
+}
+
 // src/services/session-guidance.ts
 var DEFAULT_CALLER_KEY = "__default__";
 var sessionStates = /* @__PURE__ */ new Map();
@@ -13982,20 +14230,20 @@ var PerCallerCache = class {
 };
 
 // src/lib/plan-prepare-store.ts
-import { createHash as createHash2 } from "crypto";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync, existsSync, statSync } from "fs";
-import { tmpdir } from "os";
-import { join as join3 } from "path";
+import { createHash as createHash3 } from "crypto";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, unlinkSync, existsSync, statSync } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join4 } from "path";
 var SPILL_TTL_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_CALLER_KEY3 = "__default__";
-function spillPath(projectId, callerKey) {
-  const id = createHash2("sha256").update(`${projectId ?? "no-project"}|${callerKey ?? DEFAULT_CALLER_KEY3}`).digest("hex").slice(0, 16);
-  return join3(tmpdir(), `papi-plan-prepare-${id}.json`);
+function spillPath2(projectId, callerKey) {
+  const id = createHash3("sha256").update(`${projectId ?? "no-project"}|${callerKey ?? DEFAULT_CALLER_KEY3}`).digest("hex").slice(0, 16);
+  return join4(tmpdir2(), `papi-plan-prepare-${id}.json`);
 }
 function savePrepareSpill(projectId, callerKey, state) {
   try {
-    writeFileSync2(
-      spillPath(projectId, callerKey),
+    writeFileSync3(
+      spillPath2(projectId, callerKey),
       JSON.stringify({ savedAt: Date.now(), state }),
       { mode: 384 }
     );
@@ -14003,7 +14251,7 @@ function savePrepareSpill(projectId, callerKey, state) {
   }
 }
 function loadPrepareSpill(projectId, callerKey) {
-  const path7 = spillPath(projectId, callerKey);
+  const path7 = spillPath2(projectId, callerKey);
   try {
     if (!existsSync(path7)) return void 0;
     if (Date.now() - statSync(path7).mtimeMs > SPILL_TTL_MS) {
@@ -14018,18 +14266,18 @@ function loadPrepareSpill(projectId, callerKey) {
 }
 function clearPrepareSpill(projectId, callerKey) {
   try {
-    const path7 = spillPath(projectId, callerKey);
+    const path7 = spillPath2(projectId, callerKey);
     if (existsSync(path7)) unlinkSync(path7);
   } catch {
   }
 }
 function contextPath(projectId, callerKey) {
-  const id = createHash2("sha256").update(`${projectId ?? "no-project"}|${callerKey ?? DEFAULT_CALLER_KEY3}`).digest("hex").slice(0, 16);
-  return join3(tmpdir(), `papi-plan-context-${id}.md`);
+  const id = createHash3("sha256").update(`${projectId ?? "no-project"}|${callerKey ?? DEFAULT_CALLER_KEY3}`).digest("hex").slice(0, 16);
+  return join4(tmpdir2(), `papi-plan-context-${id}.md`);
 }
 function savePrepareContextFile(projectId, callerKey, content) {
   const path7 = contextPath(projectId, callerKey);
-  writeFileSync2(path7, content, { mode: 384 });
+  writeFileSync3(path7, content, { mode: 384 });
   return path7;
 }
 
@@ -14169,6 +14417,20 @@ function formatPlanResult(result) {
     lines.push('To apply these cancellations, re-run `plan` with `mode: "apply"` and `confirm_cancellations: true`.');
     lines.push("To keep these tasks, do nothing \u2014 they remain on the board.");
   }
+  const conflicts = result.decisionConflicts ?? [];
+  if (conflicts.length > 0) {
+    lines.push("");
+    lines.push(`\u{1F500} **${conflicts.length} decision(s) need your call \u2014 work was NOT dropped.**`);
+    lines.push("These tasks cut against a live Active Decision. An AD is *active* \u2014 it can be superseded, so the planner parked the work instead of shelving it:");
+    for (const c of conflicts) {
+      const state = c.parked ? `Blocked behind ${c.adId}` : `still ${c.skipReason ?? "unparked"}`;
+      lines.push(`- **${c.resolvedTaskId} vs ${c.adId}** \u2014 ${c.conflict} _(${state})_`);
+      if (c.options.length > 0) lines.push(`  Options: ${c.options.join(" | ")}`);
+      if (c.recommendation) lines.push(`  Planner recommends: ${c.recommendation}`);
+    }
+    lines.push("");
+    lines.push('Decide: `strategy_change` with `mode: "capture"` to supersede or modify the AD (parked tasks auto-unblock once it moves), or `board_edit` to cancel the task if the AD stands.');
+  }
   if (result.skipHandoffs) {
     const taskCount = result.writeSummary?.taskIds.length ?? 0;
     lines.push("", `Next: run \`handoff_generate\` to create BUILD HANDOFFs for your ${taskCount} cycle task(s), then \`build_list\` to start building.`);
@@ -14291,16 +14553,8 @@ async function handlePlan(adapter2, config2, args) {
       };
       planPrepareCache.set(callerKey, prepareState);
       savePrepareSpill(adapter2.getProjectId?.(), callerKey, prepareState);
-      const autoDispatchEnabled = process.env.PAPI_AUTO_DISPATCH !== "false";
-      const autoDispatchThreshold = 50 * 1024;
-      let dispatch;
-      if (args.dispatch === "inline" || args.dispatch === "subagent") {
-        dispatch = args.dispatch;
-      } else if (autoDispatchEnabled && result.contextBytes !== void 0 && result.contextBytes > autoDispatchThreshold) {
-        dispatch = "subagent";
-      } else {
-        dispatch = "inline";
-      }
+      const explicit = args.dispatch === "inline" ? false : args.dispatch === "subagent" ? true : void 0;
+      const dispatch = shouldDispatch(result.contextBytes ?? 0, explicit) ? "subagent" : "inline";
       const modeLabel = result.mode === "bootstrap" ? "Bootstrap" : "Full";
       const header = result.strategyReviewWarning ? `${result.strategyReviewWarning}
 ` : "";
@@ -14414,10 +14668,10 @@ ${result.userMessage}
 }
 
 // src/services/strategy.ts
-import { randomUUID as randomUUID10, createHash as createHash3 } from "crypto";
+import { randomUUID as randomUUID10, createHash as createHash4 } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
 import { existsSync as existsSync2, readdirSync, statSync as statSync2 } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { homedir as homedir2 } from "os";
 
 // src/services/idea.ts
@@ -14767,14 +15021,22 @@ ${lines.join("\n")}
     }
   }
   let notesWithAlignment = input.notes || "";
+  let detectedAdIds = [];
   try {
     const ads = await adapter2.getActiveDecisions();
     const ideaCombined = `${input.text} ${input.notes ?? ""}`;
     const alignmentMatches = findAdAlignmentMatches(ideaCombined, ads);
     if (alignmentMatches.length > 0) {
       notesWithAlignment = `${notesWithAlignment}${formatAdAlignmentNote(alignmentMatches)}`.trim();
+      detectedAdIds = alignmentMatches.map((m) => m.displayId);
     }
   } catch {
+  }
+  const conflictsWithAd = input.conflictsWithAd?.trim();
+  if (conflictsWithAd) {
+    notesWithAlignment = `${notesWithAlignment}
+
+AD-CONFLICT: ${conflictsWithAd} \u2014 submitter flagged this as cutting against that decision. Owner decides: supersede the AD or drop the task.`.trim();
   }
   const inherited = await resolveVisibilityFromDocs(adapter2, [input.docRef]);
   const task = await adapter2.createTask({
@@ -14843,17 +15105,52 @@ ${lines.join("\n")}
     } catch {
     }
   }
+  let gated = false;
+  if (conflictsWithAd) {
+    try {
+      await adapter2.updateTask(task.id, {
+        status: "Blocked",
+        blocker: {
+          type: "decision-gate",
+          ref: conflictsWithAd,
+          reason: `Submitted as cutting against ${conflictsWithAd}. Awaiting the owner's decision.`,
+          blockedCycle: health.totalCycles
+        }
+      });
+      gated = true;
+    } catch {
+    }
+  }
   const typeNote = typeInferred ? ` [type: ${taskType} \u2014 inferred from text]` : "";
   const visibilityNote = inherited.visibility !== "public" ? ` [visibility: ${inherited.visibility} \u2014 inherited from source doc]` : "";
   const mismatchNote = inherited.mismatchWarning ? `
 
 \u26A0\uFE0F ${inherited.mismatchWarning}` : "";
+  const adIds = conflictsWithAd ? [conflictsWithAd] : detectedAdIds;
+  const landing = gated ? "created and gated on the decision" : "added to backlog";
   return {
     routing: "task",
     task,
-    message: `${task.id}: "${task.title}" \u2014 added to backlog${typeNote}${visibilityNote}${mismatchNote}`
+    message: `${task.id}: "${task.title}" \u2014 ${landing}${typeNote}${visibilityNote}${mismatchNote}`,
+    ...adIds.length > 0 ? { adConflicts: { adIds, explicit: Boolean(conflictsWithAd), gated } } : {}
   };
 }
+function buildAdConflictNote(conflictsWithAd, detectedAdIds, gated) {
+  if (conflictsWithAd) {
+    const state = gated ? `Parked as **Blocked** behind a decision gate on ${conflictsWithAd} \u2014 it auto-unblocks once that AD is superseded, modified, or reaffirmed.` : `Recorded against ${conflictsWithAd} (gate could not be applied \u2014 the AD-CONFLICT note is on the task).`;
+    return `
+
+\u{1F500} **Conflicts with ${conflictsWithAd}.** ${state}
+**Tell the user now** \u2014 an AD is *active*, so this is their call to make, not yours. Offer both paths: supersede the AD via \`strategy_change\`, or leave the AD standing and drop the task.`;
+  }
+  if (detectedAdIds.length > 0) {
+    return `
+
+\u{1F500} **Possible conflict with ${detectedAdIds.join(", ")}** (keyword match \u2014 verify it is real).
+If it IS a real contradiction, **do not shelve the idea on those grounds**: surface it to the user and re-submit with \`conflicts_with_ad\` so the task is gated on the decision instead of quietly competing in the backlog.`;
+  }
+  return "";
+}
 var CANVAS_SECTION_LABELS = {
   landscape: "Landscape References",
   journeys: "User Journeys",
@@ -15424,7 +15721,7 @@ ${surpriseDigestText}` : buildReportsText;
   try {
     const fullCanvasText = formatDiscoveryCanvas(canvas);
     if (fullCanvasText) {
-      const canvasHash = createHash3("md5").update(fullCanvasText).digest("hex");
+      const canvasHash = createHash4("md5").update(fullCanvasText).digest("hex");
       const lastReview = previousStrategyReviews?.[0];
       const prevHash = lastReview?.structuredData?.canvasHash;
       if (prevHash && prevHash === canvasHash) {
@@ -15494,11 +15791,11 @@ ${lines.join("\n")}`;
   }
   let recentPlansText;
   try {
-    const plansDir = join4(homedir2(), ".claude", "plans");
+    const plansDir = join5(homedir2(), ".claude", "plans");
     if (existsSync2(plansDir)) {
       const lastReviewDate = previousStrategyReviews?.[0]?.createdAt ? new Date(previousStrategyReviews[0].createdAt) : /* @__PURE__ */ new Date(0);
       const planFiles = readdirSync(plansDir).filter((f) => f.endsWith(".md")).map((f) => {
-        const fullPath = join4(plansDir, f);
+        const fullPath = join5(plansDir, f);
         const stat4 = statSync2(fullPath);
         return { name: f, modified: stat4.mtime, size: stat4.size };
       }).filter((f) => f.modified > lastReviewDate).sort((a, b2) => b2.modified.getTime() - a.modified.getTime()).slice(0, 15);
@@ -15515,7 +15812,7 @@ ${lines.join("\n")}`;
   }
   let unregisteredDocsText;
   try {
-    const docsDir = join4(projectRoot, "docs");
+    const docsDir = join5(projectRoot, "docs");
     if (hasLocalWorkspace() && existsSync2(docsDir)) {
       const registeredPaths = new Set(
         (registeredDocs ?? []).map((d) => d.path).filter(Boolean)
@@ -15523,7 +15820,7 @@ ${lines.join("\n")}`;
       const allDocFiles = [];
       const scanDir = (dir, prefix) => {
         for (const entry of readdirSync(dir, { withFileTypes: true })) {
-          if (entry.isDirectory()) scanDir(join4(dir, entry.name), `${prefix}${entry.name}/`);
+          if (entry.isDirectory()) scanDir(join5(dir, entry.name), `${prefix}${entry.name}/`);
           else if (entry.name.endsWith(".md")) allDocFiles.push(`${prefix}${entry.name}`);
         }
       };
@@ -15780,6 +16077,65 @@ function extractDecisionEvidence(ad, eventType, warnings) {
   }
   return { evidenceRef, metricDelta };
 }
+function asDecisionBatchApplier(adapter2) {
+  const candidate = adapter2;
+  return typeof candidate.applyActiveDecisionUpdates === "function" ? candidate : void 0;
+}
+function routeDecisionUpdate(ad, adapter2, cycleNumber, warnings) {
+  const action = ad.action;
+  let route;
+  if (action === "delete" && adapter2.deleteActiveDecision) {
+    route = "delete";
+  } else if (action === "new" && adapter2.upsertActiveDecision) {
+    route = "upsert";
+  } else {
+    route = "update";
+  }
+  const titleMatch = ad.body.match(/^###\s+\S+:\s*([^\n[]+?)(?:\s*\[|$)/m);
+  const confidenceMatch = ad.body.match(/\[Confidence:\s*(HIGH|MEDIUM|LOW)\]/i);
+  const eventType = action === "delete" ? "invalidated" : action === "confidence_change" ? "confidence_changed" : action === "supersede" ? "superseded" : action === "new" ? "created" : "modified";
+  const evidence = extractDecisionEvidence(ad, eventType, warnings);
+  return {
+    id: ad.id,
+    body: ad.body,
+    route,
+    action,
+    title: titleMatch ? titleMatch[1].trim() : ad.id,
+    confidence: confidenceMatch ? confidenceMatch[1].toUpperCase() : "MEDIUM",
+    event: {
+      decisionId: ad.id,
+      eventType,
+      cycle: cycleNumber,
+      source: "strategy_review",
+      sourceRef: `cycle-${cycleNumber}-review`,
+      detail: `Action: ${action}`,
+      evidenceRef: evidence.evidenceRef,
+      metricDelta: evidence.metricDelta
+    }
+  };
+}
+async function applyDecisionUpdates(adapter2, updates, cycleNumber, warnings) {
+  if (updates.length === 0) return;
+  const applies = updates.map((ad) => routeDecisionUpdate(ad, adapter2, cycleNumber, warnings));
+  const batch = asDecisionBatchApplier(adapter2);
+  if (batch) {
+    await batch.applyActiveDecisionUpdates(applies, cycleNumber);
+    return;
+  }
+  for (const apply of applies) {
+    if (apply.route === "delete") {
+      await adapter2.deleteActiveDecision(apply.id);
+    } else if (apply.route === "upsert") {
+      await adapter2.upsertActiveDecision(apply.id, apply.body, apply.title, apply.confidence, cycleNumber);
+    } else {
+      await adapter2.updateActiveDecision(apply.id, apply.body, cycleNumber, apply.action);
+    }
+    try {
+      await adapter2.appendDecisionEvent(apply.event);
+    } catch {
+    }
+  }
+}
 async function writeBack2(adapter2, cycleNumber, data, fullAnalysis, warnings) {
   const cleanTitle = data.sessionLogTitle.replace(/^(?:Cycle|Session)\s+\d+\s*—\s*/i, "").trim();
   const cleanContent = data.sessionLogContent.replace(/^#{1,3}\s+(?:Cycle|Session)\s+\d+\s*—[^\n]*\n*/i, "").trim();
@@ -15804,7 +16160,7 @@ ${cleanContent}`;
         const currentCanvas = await adapter2.readDiscoveryCanvas();
         const canvasText = formatDiscoveryCanvas(currentCanvas);
         if (canvasText) {
-          return { ...sd, canvasHash: createHash3("md5").update(canvasText).digest("hex") };
+          return { ...sd, canvasHash: createHash4("md5").update(canvasText).digest("hex") };
         }
       } catch {
       }
@@ -15821,34 +16177,7 @@ ${cleanContent}`;
   } catch {
   }
   if (data.activeDecisionUpdates && data.activeDecisionUpdates.length > 0) {
-    await Promise.all(data.activeDecisionUpdates.map(async (ad) => {
-      if (ad.action === "delete" && adapter2.deleteActiveDecision) {
-        await adapter2.deleteActiveDecision(ad.id);
-      } else if (ad.action === "new" && adapter2.upsertActiveDecision) {
-        const titleMatch = ad.body.match(/^###\s+\S+:\s*([^\n[]+?)(?:\s*\[|$)/m);
-        const title = titleMatch ? titleMatch[1].trim() : ad.id;
-        const confidenceMatch = ad.body.match(/\[Confidence:\s*(HIGH|MEDIUM|LOW)\]/i);
-        const confidence = confidenceMatch ? confidenceMatch[1].toUpperCase() : "MEDIUM";
-        await adapter2.upsertActiveDecision(ad.id, ad.body, title, confidence, cycleNumber);
-      } else {
-        await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber, ad.action);
-      }
-      const eventType = ad.action === "delete" ? "invalidated" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
-      const evidence = extractDecisionEvidence(ad, eventType, warnings);
-      try {
-        await adapter2.appendDecisionEvent({
-          decisionId: ad.id,
-          eventType,
-          cycle: cycleNumber,
-          source: "strategy_review",
-          sourceRef: `cycle-${cycleNumber}-review`,
-          detail: `Action: ${ad.action}`,
-          evidenceRef: evidence.evidenceRef,
-          metricDelta: evidence.metricDelta
-        });
-      } catch {
-      }
-    }));
+    await applyDecisionUpdates(adapter2, data.activeDecisionUpdates, cycleNumber, warnings);
   }
   try {
     if (adapter2.confirmPendingActiveDecisions) {
@@ -16606,37 +16935,45 @@ async function prepareStrategyChange(adapter2, text, adapterType) {
 async function applyStrategyChangeOutput(adapter2, rawLlmOutput, cycleNumber) {
   return processStrategyChangeOutput(adapter2, rawLlmOutput, cycleNumber);
 }
+function asDecisionIdAllocator(adapter2) {
+  const candidate = adapter2;
+  return typeof candidate.allocateActiveDecision === "function" ? candidate : void 0;
+}
+var AD_ID_PLACEHOLDER = "{{AD_ID}}";
+function toAdBodyTemplate(body) {
+  return body.replace(/^(\s*#{1,6}\s+)AD-\d+\b/m, `$1${AD_ID_PLACEHOLDER}`);
+}
 async function captureDecision(adapter2, input) {
   const health = await adapter2.getCycleHealth();
   const cycleNumber = health.totalCycles;
-  let adId;
-  let adAction;
-  if (input.adId) {
-    adId = input.adId;
-    adAction = "updated";
-  } else {
-    const existingAds = await adapter2.getActiveDecisions({ includeRetired: true });
-    const maxNum = existingAds.reduce((max, ad) => {
-      const match = ad.id.match(/^AD-(\d+)$/);
-      return match ? Math.max(max, parseInt(match[1], 10)) : max;
-    }, 0);
-    adId = `AD-${maxNum + 1}`;
-    adAction = "created";
+  const supersedesId = input.supersedes?.trim() || void 0;
+  if (supersedesId && input.confidenceOnly) {
+    throw new Error("supersedes cannot be combined with confidence_only \u2014 a confidence bump does not replace a decision.");
+  }
+  if (supersedesId) {
+    const all = await adapter2.getActiveDecisions({ includeRetired: true });
+    if (!all.some((d) => d.id === supersedesId)) {
+      throw new Error(`supersedes: ${supersedesId} does not exist on this project. Check the AD id (e.g. "AD-42").`);
+    }
+    if (supersedesId === input.adId) {
+      throw new Error("An AD cannot supersede itself.");
+    }
   }
   if (input.confidenceOnly) {
     if (!input.adId) {
       throw new Error('confidence_only requires adId \u2014 provide the AD to update (e.g. "AD-12")');
     }
+    const adId2 = input.adId;
     if (adapter2.upsertActiveDecision) {
       const existing = await adapter2.getActiveDecisions({ includeRetired: false });
-      const current = existing.find((d) => d.id === adId);
+      const current = existing.find((d) => d.id === adId2);
       const preservedBody = current?.body ?? `- **Decision:** ${input.text}`;
       const preservedTitle = current?.title ?? input.text.slice(0, 80);
-      await adapter2.upsertActiveDecision(adId, preservedBody, preservedTitle, input.confidence, cycleNumber);
+      await adapter2.upsertActiveDecision(adId2, preservedBody, preservedTitle, input.confidence, cycleNumber);
     }
     try {
       await adapter2.appendDecisionEvent({
-        decisionId: adId,
+        decisionId: adId2,
         eventType: "modified",
         cycle: cycleNumber,
         source: "strategy_change",
@@ -16645,18 +16982,66 @@ async function captureDecision(adapter2, input) {
       });
     } catch {
     }
-    return { cycleNumber, adId, adAction: "updated" };
+    return { cycleNumber, adId: adId2, adAction: "updated" };
   }
   const title = input.text.length > 80 ? input.text.slice(0, 77) + "..." : input.text;
-  const adBody = input.adBody ?? `### ${adId}: ${title} [Confidence: ${input.confidence}]
+  const supersedesLine = supersedesId ? `
+- **Supersedes:** ${supersedesId}` : "";
+  const bodyTemplate = input.adBody ? toAdBodyTemplate(input.adBody) : `### ${AD_ID_PLACEHOLDER}: ${title} [Confidence: ${input.confidence}]
 
-- **Decision:** ${input.text}
+- **Decision:** ${input.text}${supersedesLine}
 - **Evidence:** Captured from conversation, Cycle ${cycleNumber}.
 - **Status:** Active`;
-  if (adapter2.upsertActiveDecision) {
-    await adapter2.upsertActiveDecision(adId, adBody, title, input.confidence, cycleNumber);
+  let adId;
+  let adAction;
+  if (input.adId) {
+    adId = input.adId;
+    adAction = "updated";
+    const adBody = bodyTemplate.split(AD_ID_PLACEHOLDER).join(adId);
+    if (adapter2.upsertActiveDecision) {
+      await adapter2.upsertActiveDecision(adId, adBody, title, input.confidence, cycleNumber);
+    } else {
+      await adapter2.updateActiveDecision(adId, adBody, cycleNumber);
+    }
   } else {
-    await adapter2.updateActiveDecision(adId, adBody, cycleNumber);
+    adAction = "created";
+    const allocator = asDecisionIdAllocator(adapter2);
+    if (allocator) {
+      adId = await allocator.allocateActiveDecision(bodyTemplate, title, input.confidence, cycleNumber);
+    } else {
+      const existingAds = await adapter2.getActiveDecisions({ includeRetired: true });
+      const maxNum = existingAds.reduce((max, ad) => {
+        const match = ad.id.match(/^AD-(\d+)$/);
+        return match ? Math.max(max, parseInt(match[1], 10)) : max;
+      }, 0);
+      adId = `AD-${maxNum + 1}`;
+      const adBody = bodyTemplate.split(AD_ID_PLACEHOLDER).join(adId);
+      if (adapter2.upsertActiveDecision) {
+        await adapter2.upsertActiveDecision(adId, adBody, title, input.confidence, cycleNumber);
+      } else {
+        await adapter2.updateActiveDecision(adId, adBody, cycleNumber);
+      }
+    }
+  }
+  if (supersedesId) {
+    const all = await adapter2.getActiveDecisions({ includeRetired: true });
+    const prior = all.find((d) => d.id === supersedesId);
+    const priorBody = prior?.body ?? "";
+    const note = `
+
+- **Superseded by:** ${adId} (Cycle ${cycleNumber}) \u2014 ${input.text}`;
+    await adapter2.updateActiveDecision(supersedesId, `${priorBody}${note}`, cycleNumber, "supersede");
+    try {
+      await adapter2.appendDecisionEvent({
+        decisionId: supersedesId,
+        eventType: "superseded",
+        cycle: cycleNumber,
+        source: "strategy_change",
+        sourceRef: `cycle-${cycleNumber}-capture`,
+        detail: `Superseded by ${adId}: ${input.text.slice(0, 180)}`
+      });
+    } catch {
+    }
   }
   try {
     await adapter2.appendDecisionEvent({
@@ -16677,11 +17062,13 @@ async function captureDecision(adapter2, input) {
       title: `Decision captured: ${adId}`,
       content: `**${adAction === "created" ? "New" : "Updated"} Active Decision** \u2014 ${adId}: ${input.text}
 
-Confidence: ${input.confidence}. Captured mid-conversation via strategy_change capture mode (Cycle ${cycleNumber}).`
+Confidence: ${input.confidence}. Captured mid-conversation via strategy_change capture mode (Cycle ${cycleNumber}).` + (supersedesId ? `
+
+Supersedes ${supersedesId} (retired, kept as history).` : "")
     });
   } catch {
   }
-  return { cycleNumber, adId, adAction };
+  return { cycleNumber, adId, adAction, supersededId: supersedesId };
 }
 
 // src/tools/strategy.ts
@@ -16797,6 +17184,10 @@ var strategyChangeTool = {
         type: "boolean",
         description: `When true (mode "capture" + ad_id required), only update the confidence level \u2014 leave the AD body unchanged. Use when evidence strength changes but the decision itself hasn't shifted.`
       },
+      supersedes: {
+        type: "string",
+        description: 'Existing AD ID this new decision replaces, e.g. "AD-42" (mode "capture" only). The named AD is marked superseded and kept as history \u2014 never overwritten. Use this instead of passing ad_id when the decision has CHANGED rather than been refined.'
+      },
       north_star: {
         type: "string",
         description: 'mode "capture" only \u2014 set/update the project North Star statement directly. orient and the project foundation read it. No decision text required when this is provided.'
@@ -16893,16 +17284,8 @@ ${recLines.join("\n")}
         userMessage: result.userMessage,
         contextBytes: reviewContextBytes
       });
-      const autoDispatchEnabled = process.env.PAPI_AUTO_DISPATCH !== "false";
-      const autoDispatchThreshold = 50 * 1024;
-      let dispatch;
-      if (args.dispatch === "inline" || args.dispatch === "subagent") {
-        dispatch = args.dispatch;
-      } else if (autoDispatchEnabled && reviewContextBytes > autoDispatchThreshold) {
-        dispatch = "subagent";
-      } else {
-        dispatch = "inline";
-      }
+      const explicit = args.dispatch === "inline" ? false : args.dispatch === "subagent" ? true : void 0;
+      const dispatch = shouldDispatch(reviewContextBytes, explicit) ? "subagent" : "inline";
       if (dispatch === "subagent") {
         const dispatchPrompt = buildSubagentDispatchPrompt({
           tool: "strategy_review",
@@ -17030,19 +17413,24 @@ orient and the project foundation will read this value.`
       const confidence = args.confidence ?? "MEDIUM";
       const adBody = args.ad_body;
       const confidenceOnly = args.confidence_only === true;
+      const supersedes = args.supersedes?.trim();
       const result = await captureDecision(adapter2, {
         text: text2.trim(),
         adId: adId?.trim(),
         confidence,
         adBody: adBody?.trim(),
-        confidenceOnly
+        confidenceOnly,
+        supersedes
       });
       const captureLabel = confidenceOnly ? `Updated confidence on **${result.adId}** to ${confidence} (body preserved)` : `${result.adAction === "created" ? "Created" : "Updated"} **${result.adId}**: ${text2.trim()}
 Confidence: ${confidence}`;
+      const supersedeLine = result.supersededId ? `
+
+**${result.supersededId}** marked superseded by ${result.adId} \u2014 retained as history, not overwritten.` : "";
       return textResponse(
         `**Decision Captured \u2014 Cycle ${result.cycleNumber}**
 
-${captureLabel}
+${captureLabel}${supersedeLine}
 
 Decision event logged.`
       );
@@ -17153,8 +17541,8 @@ async function viewBoard(adapter2, phaseFilter, options) {
     const bi = PRIORITY_ORDER.indexOf(b2.priority);
     const priorityDiff = (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi);
     if (priorityDiff !== 0) return priorityDiff;
-    const aDate = a.createdAt ? String(a.createdAt) : "";
-    const bDate = b2.createdAt ? String(b2.createdAt) : "";
+    const aDate = a.createdAt ?? "";
+    const bDate = b2.createdAt ?? "";
     return bDate.localeCompare(aDate);
   });
   const total = filtered.length;
@@ -17508,6 +17896,10 @@ var boardEditTool = {
       actual_effort: {
         $ref: "#/$defs/effortSize",
         description: "task-2182: correct the actual effort on this task's LATEST build report (fixes a mis-recorded actual)."
+      },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug whose board this task lives on, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: ["task_id"]
@@ -17761,6 +18153,14 @@ async function handleBoardEdit(adapter2, args) {
   if (!taskId) {
     return errorResponse("task_id is required.");
   }
+  let target = adapter2;
+  let overrideNote = "";
+  try {
+    ({ adapter: target, overrideNote } = await resolvePerCallProjectAdapter(adapter2, args));
+  } catch (err) {
+    if (err instanceof ProjectResolutionError) return errorResponse(err.message);
+    throw err;
+  }
   const updates = {};
   const changes = [];
   for (const field of EDITABLE_FIELDS) {
@@ -17788,7 +18188,7 @@ async function handleBoardEdit(adapter2, args) {
       updates.cycle = null;
       changes.push("cycle");
     } else if (typeof rawCycle === "number" && Number.isInteger(rawCycle) && rawCycle > 0) {
-      const health = await adapter2.getCycleHealth().catch(() => null);
+      const health = await target.getCycleHealth().catch(() => null);
       const activeCycle = health?.totalCycles ?? 0;
       if (rawCycle > activeCycle + 1) {
         return errorResponse(
@@ -17807,7 +18207,7 @@ async function handleBoardEdit(adapter2, args) {
     return errorResponse("No fields to update. Pass at least one field (title, priority, complexity, module, epic, phase, notes, status, maturity, cycle).");
   }
   try {
-    const task = await adapter2.getTask(taskId);
+    const task = await target.getTask(taskId);
     if (!task) {
       return errorResponse(`Task ${taskId} not found.`);
     }
@@ -17826,7 +18226,7 @@ async function handleBoardEdit(adapter2, args) {
           const idx = changes.indexOf("notes");
           if (idx >= 0) changes.splice(idx, 1);
         } else {
-          const health = await adapter2.getCycleHealth().catch(() => null);
+          const health = await target.getCycleHealth().catch(() => null);
           const activeCycle = health?.totalCycles ?? null;
           const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
           const stamp = activeCycle != null ? `[C${activeCycle} ${date}]` : `[${date}]`;
@@ -17851,7 +18251,7 @@ ${existing}` : entry;
     }
     let autoAssignedCycle = null;
     if (updates.status === "In Cycle") {
-      const health = await adapter2.getCycleHealth().catch(() => null);
+      const health = await target.getCycleHealth().catch(() => null);
       const activeCycle = health?.totalCycles ?? null;
       if (activeCycle != null && activeCycle > 0) {
         updates.cycle = activeCycle;
@@ -17863,25 +18263,25 @@ ${existing}` : entry;
       updates.cancelledBy = "user";
     }
     if (effortCorrection.estimatedEffort || effortCorrection.actualEffort) {
-      if (!adapter2.correctLatestBuildReportEffort) {
+      if (!target.correctLatestBuildReportEffort) {
         return errorResponse("Correcting build-report effort requires a database adapter (pg). The md adapter does not support it.");
       }
-      await adapter2.correctLatestBuildReportEffort(taskId, effortCorrection);
+      await target.correctLatestBuildReportEffort(taskId, effortCorrection);
     }
     if (Object.keys(updates).length > 0) {
-      await adapter2.updateTask(taskId, updates);
+      await target.updateTask(taskId, updates);
     }
-    if ((updates.status === "Done" || updates.status === "Cancelled") && adapter2.updateDogfoodEntryStatus) {
+    if ((updates.status === "Done" || updates.status === "Cancelled") && target.updateDogfoodEntryStatus) {
       try {
-        const dogfoodLog = await adapter2.getDogfoodLog?.(50) ?? [];
+        const dogfoodLog = await target.getDogfoodLog?.(50) ?? [];
         const linked = dogfoodLog.filter((e) => e.linkedTaskId === taskId || e.linkedTaskId === task.id);
         const newStatus = "resolved";
-        await Promise.all(linked.map((e) => adapter2.updateDogfoodEntryStatus(e.id, newStatus)));
+        await Promise.all(linked.map((e) => target.updateDogfoodEntryStatus(e.id, newStatus)));
       } catch {
       }
     }
     const lines = [
-      `Updated **${taskId}** (${updates.title ?? task.title})`,
+      `Updated **${taskId}**${overrideNote} (${updates.title ?? task.title})`,
       "",
       `**Changes:** ${changes.map((f) => `${f} \u2192 ${String(updates[f])}`).join(", ")}`
     ];
@@ -17896,15 +18296,15 @@ ${existing}` : entry;
 
 // src/services/setup.ts
 import { mkdir, writeFile as writeFile2, readFile as readFile4, readdir, access as access2, stat as stat2, chmod } from "fs/promises";
-import { join as join9, basename, extname, dirname as dirname3 } from "path";
+import { join as join10, basename, extname, dirname as dirname3, relative } from "path";
 import { execFileSync as execFileSync3 } from "child_process";
 
 // src/lib/detect-codebase.ts
 import { existsSync as existsSync3 } from "fs";
 import { readdirSync as readdirSync2, statSync as statSync3 } from "fs";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 function detectCodebaseType(projectRoot) {
-  if (existsSync3(join5(projectRoot, ".git"))) {
+  if (existsSync3(join6(projectRoot, ".git"))) {
     return "existing_codebase";
   }
   const manifests = [
@@ -17918,7 +18318,7 @@ function detectCodebaseType(projectRoot) {
     "CMakeLists.txt"
   ];
   for (const manifest of manifests) {
-    if (existsSync3(join5(projectRoot, manifest))) {
+    if (existsSync3(join6(projectRoot, manifest))) {
       return "existing_codebase";
     }
   }
@@ -17926,7 +18326,7 @@ function detectCodebaseType(projectRoot) {
     const entries = readdirSync2(projectRoot).filter((f) => !f.startsWith("."));
     const fileCount = entries.filter((f) => {
       try {
-        return statSync3(join5(projectRoot, f)).isFile();
+        return statSync3(join6(projectRoot, f)).isFile();
       } catch {
         return false;
       }
@@ -17939,20 +18339,20 @@ function detectCodebaseType(projectRoot) {
 
 // src/lib/agents-bundle.ts
 import { readFileSync as readFileSync3, existsSync as existsSync4, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
-import { dirname, join as join6, resolve } from "path";
+import { dirname, join as join7, resolve } from "path";
 import { fileURLToPath } from "url";
-var PROJECT_BUNDLE_REL = join6(".agents", "skills", "papi-cycle");
+var PROJECT_BUNDLE_REL = join7(".agents", "skills", "papi-cycle");
 function bundleDestRel(rel) {
-  return rel === "AGENTS.md" ? "AGENTS.md" : join6(PROJECT_BUNDLE_REL, rel);
+  return rel === "AGENTS.md" ? "AGENTS.md" : join7(PROJECT_BUNDLE_REL, rel);
 }
 function claudeSkillDestRel(rel) {
-  return rel === "AGENTS.md" ? void 0 : join6(".claude", "skills", rel);
+  return rel === "AGENTS.md" ? void 0 : join7(".claude", "skills", rel);
 }
 function resolveBundleDir() {
   let dir = dirname(fileURLToPath(import.meta.url));
   for (let i = 0; i < 5; i++) {
-    const candidate = join6(dir, "skills", "papi-cycle");
-    if (existsSync4(join6(candidate, "AGENTS.md"))) return candidate;
+    const candidate = join7(dir, "skills", "papi-cycle");
+    if (existsSync4(join7(candidate, "AGENTS.md"))) return candidate;
     const parent = resolve(dir, "..");
     if (parent === dir) break;
     dir = parent;
@@ -17964,8 +18364,8 @@ function readBundleFiles(bundleDir = resolveBundleDir()) {
   const files = [];
   const walk = (abs, rel) => {
     for (const entry of readdirSync3(abs, { withFileTypes: true })) {
-      const childAbs = join6(abs, entry.name);
-      const childRel = rel ? join6(rel, entry.name) : entry.name;
+      const childAbs = join7(abs, entry.name);
+      const childRel = rel ? join7(rel, entry.name) : entry.name;
       if (entry.isDirectory()) walk(childAbs, childRel);
       else if (entry.isFile()) files.push({ rel: childRel, content: readFileSync3(childAbs, "utf8") });
     }
@@ -17974,13 +18374,14 @@ function readBundleFiles(bundleDir = resolveBundleDir()) {
   return files;
 }
 function planBundleInstall(projectRoot, projectName, opts = {}) {
+  const canProbe = opts.skipExisting === true && projectRoot !== "";
   const out = {};
   for (const f of readBundleFiles()) {
     const content = f.rel === "AGENTS.md" ? f.content.replace(/\{\{project_name\}\}/g, projectName) : f.content;
     for (const rel of [bundleDestRel(f.rel), claudeSkillDestRel(f.rel)]) {
       if (!rel) continue;
-      const dest = join6(projectRoot, rel);
-      if (opts.skipExisting && existsSync4(dest) && statSync4(dest).isFile()) continue;
+      const dest = join7(projectRoot, rel);
+      if (canProbe && existsSync4(dest) && statSync4(dest).isFile()) continue;
       out[dest] = content;
     }
   }
@@ -17989,19 +18390,19 @@ function planBundleInstall(projectRoot, projectName, opts = {}) {
 
 // src/lib/design-bundle.ts
 import { readFileSync as readFileSync4, existsSync as existsSync5, statSync as statSync5 } from "fs";
-import { dirname as dirname2, join as join7, resolve as resolve2 } from "path";
+import { dirname as dirname2, join as join8, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var DESIGN_ASSETS = [
-  { srcRel: join7("agents", "frontend-design-engineer.md"), destRel: join7(".claude", "agents", "frontend-design-engineer.md"), executable: false },
-  { srcRel: join7("skills", "design-critique", "SKILL.md"), destRel: join7(".claude", "skills", "design-critique", "SKILL.md"), executable: false },
-  { srcRel: join7("hooks", "frontend-design-guard.sh"), destRel: join7(".claude", "hooks", "frontend-design-guard.sh"), executable: true }
+  { srcRel: join8("agents", "frontend-design-engineer.md"), destRel: join8(".claude", "agents", "frontend-design-engineer.md"), executable: false },
+  { srcRel: join8("skills", "design-critique", "SKILL.md"), destRel: join8(".claude", "skills", "design-critique", "SKILL.md"), executable: false },
+  { srcRel: join8("hooks", "frontend-design-guard.sh"), destRel: join8(".claude", "hooks", "frontend-design-guard.sh"), executable: true }
 ];
 var DESIGN_HOOK_COMMAND = ".claude/hooks/frontend-design-guard.sh";
 function resolveDesignAssetsDir() {
   let dir = dirname2(fileURLToPath2(import.meta.url));
   for (let i = 0; i < 5; i++) {
-    const candidate = join7(dir, "design-assets");
-    if (existsSync5(join7(candidate, "agents", "frontend-design-engineer.md"))) return candidate;
+    const candidate = join8(dir, "design-assets");
+    if (existsSync5(join8(candidate, "agents", "frontend-design-engineer.md"))) return candidate;
     const parent = resolve2(dir, "..");
     if (parent === dir) break;
     dir = parent;
@@ -18013,9 +18414,9 @@ function planDesignInstall(projectRoot, opts = {}) {
   if (!assetsDir) return [];
   const out = [];
   for (const asset of DESIGN_ASSETS) {
-    const srcAbs = join7(assetsDir, asset.srcRel);
+    const srcAbs = join8(assetsDir, asset.srcRel);
     if (!existsSync5(srcAbs)) continue;
-    const dest = projectRoot ? join7(projectRoot, asset.destRel) : asset.destRel;
+    const dest = projectRoot ? join8(projectRoot, asset.destRel) : asset.destRel;
     if (opts.skipExisting && projectRoot && existsSync5(dest) && statSync5(dest).isFile()) continue;
     out.push({ dest, content: readFileSync4(srcAbs, "utf8"), executable: asset.executable });
   }
@@ -18024,9 +18425,9 @@ function planDesignInstall(projectRoot, opts = {}) {
 
 // src/lib/skill-detection.ts
 import { existsSync as existsSync6, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync6 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 function readPackageJson(projectRoot) {
-  const path7 = join8(projectRoot, "package.json");
+  const path7 = join9(projectRoot, "package.json");
   if (!existsSync6(path7)) return null;
   try {
     const raw = readFileSync5(path7, "utf-8");
@@ -18050,7 +18451,7 @@ function detectsFrontendStack(projectRoot) {
   return hasDependencyMatching(allDeps(readPackageJson(projectRoot)), FRONTEND_DEP_PATTERN);
 }
 function hasGitHubWorkflows(projectRoot) {
-  const dir = join8(projectRoot, ".github", "workflows");
+  const dir = join9(projectRoot, ".github", "workflows");
   if (!existsSync6(dir)) return false;
   try {
     const entries = readdirSync4(dir);
@@ -18060,7 +18461,7 @@ function hasGitHubWorkflows(projectRoot) {
   }
 }
 function envExampleMentionsStaging(projectRoot) {
-  const path7 = join8(projectRoot, ".env.example");
+  const path7 = join9(projectRoot, ".env.example");
   if (!existsSync6(path7)) return false;
   try {
     const raw = readFileSync5(path7, "utf-8");
@@ -18070,8 +18471,8 @@ function envExampleMentionsStaging(projectRoot) {
   }
 }
 function hasVercelConfig(projectRoot) {
-  if (existsSync6(join8(projectRoot, "vercel.json"))) return true;
-  const vercelDir = join8(projectRoot, ".vercel");
+  if (existsSync6(join9(projectRoot, "vercel.json"))) return true;
+  const vercelDir = join9(projectRoot, ".vercel");
   if (!existsSync6(vercelDir)) return false;
   try {
     return statSync6(vercelDir).isDirectory();
@@ -18318,6 +18719,7 @@ Active Decisions (ADs) track architectural and product choices with confidence l
 - ADs are for product/architecture choices only, not process preferences.
 - When new evidence appears, update AD confidence via \`strategy_change\`.
 - Supersede rather than overwrite \u2014 old decisions stay as history.
+- **A contradiction is not a veto.** If an idea or task cuts against a live AD, that is a decision for the user \u2014 never your reason to drop it. Submit it with \`idea\` + \`conflicts_with_ad: "AD-N"\`: the task is created and parked behind a decision gate, surfaces in \`orient\` as waiting on the owner, and returns to the board on its own once the AD is superseded, modified, or reaffirmed. Shelving the work instead means the AD never gets tested by the evidence that would have challenged it.
 - New ADs should include a \`### Reversal Trigger\` section: specify the signal that would invalidate the stance, the action to take (modify/supersede/abandon), and why writing it now prevents sunk-cost drift later.
 `;
 var CLAUDE_MD_TIER_2 = `
@@ -18515,6 +18917,13 @@ function formatFilesToWriteSection(collector) {
     '- `mode: "create"` \u2014 create the file with `content`. If `skip_if_exists: true`, skip when the file already exists.',
     '- `mode: "overwrite"` \u2014 replace the file fully with `content`.',
     '- `mode: "append"` \u2014 append `content` to the existing file (create it first if missing).',
+    '- `mode: "merge-json"` \u2014 the file is JSON. If it does not exist, create it with `content`.',
+    "  If it DOES exist, parse both, merge `content` INTO the existing object, and write the",
+    "  result back. Merge rules: objects merge key-by-key (recursing into nested objects);",
+    "  arrays UNION, keeping the existing order and appending only values not already present;",
+    "  scalars in `content` do not overwrite an existing value. NEVER remove, reorder or rewrite",
+    "  anything already in the file \u2014 this mode only ADDS. If the existing file is malformed",
+    "  JSON, leave it untouched and tell the user rather than replacing their file.",
     ""
   ].join("\n");
 }
@@ -18546,6 +18955,7 @@ function shouldWriteClaudeMd(clientName) {
   return !clientName || /claude/i.test(clientName);
 }
 async function scaffoldPapiDir(adapter2, config2, input, collector) {
+  const preparedFiles = [];
   const isPg = config2.adapterType === "pg" || config2.adapterType === "proxy";
   const vars = {
     project_name: input.projectName,
@@ -18555,12 +18965,12 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
   if (!isPg) {
     try {
       await access2(config2.papiDir);
-      return false;
+      return { createdProject: false, preparedFiles };
     } catch {
       await mkdir(config2.papiDir, { recursive: true });
       for (const [filename, template] of Object.entries(FILE_TEMPLATES)) {
         const content = substitute(template, vars);
-        await writeFile2(join9(config2.papiDir, filename), content, "utf-8");
+        await writeFile2(join10(config2.papiDir, filename), content, "utf-8");
       }
     }
   } else {
@@ -18570,7 +18980,7 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
         const templateContent = substitute(PRODUCT_BRIEF_TEMPLATE, vars);
         await adapter2.updateProductBrief(templateContent);
       } else {
-        return false;
+        return { createdProject: false, preparedFiles };
       }
     } catch {
     }
@@ -18578,13 +18988,13 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
   const useCollector = config2.adapterType === "proxy";
   const docsRel = "docs";
   const commandsRel = ".claude/commands";
-  const commandsDir = useCollector ? commandsRel : join9(config2.projectRoot, ".claude", "commands");
-  const docsDir = useCollector ? docsRel : join9(config2.projectRoot, "docs");
+  const commandsDir = useCollector ? commandsRel : join10(config2.projectRoot, ".claude", "commands");
+  const docsDir = useCollector ? docsRel : join10(config2.projectRoot, "docs");
   if (!useCollector) {
     await mkdir(commandsDir, { recursive: true });
     await mkdir(docsDir, { recursive: true });
   }
-  const claudeMdPath = useCollector ? "CLAUDE.md" : join9(config2.projectRoot, "CLAUDE.md");
+  const claudeMdPath = useCollector ? "CLAUDE.md" : join10(config2.projectRoot, "CLAUDE.md");
   let claudeMdExists = false;
   if (!useCollector) {
     try {
@@ -18593,7 +19003,7 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
     } catch {
     }
   }
-  const docsIndexPath = useCollector ? `${docsRel}/INDEX.md` : join9(docsDir, "INDEX.md");
+  const docsIndexPath = useCollector ? `${docsRel}/INDEX.md` : join10(docsDir, "INDEX.md");
   let docsIndexExists = false;
   if (!useCollector) {
     try {
@@ -18603,9 +19013,9 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
     }
   }
   const scaffoldFiles = {
-    [useCollector ? `${commandsRel}/papi-audit.md` : join9(commandsDir, "papi-audit.md")]: PAPI_AUDIT_COMMAND_TEMPLATE,
-    [useCollector ? `${commandsRel}/test.md` : join9(commandsDir, "test.md")]: TEST_COMMAND_TEMPLATE,
-    [useCollector ? `${docsRel}/README.md` : join9(docsDir, "README.md")]: substitute(DOCS_README_TEMPLATE, vars)
+    [useCollector ? `${commandsRel}/papi-audit.md` : join10(commandsDir, "papi-audit.md")]: PAPI_AUDIT_COMMAND_TEMPLATE,
+    [useCollector ? `${commandsRel}/test.md` : join10(commandsDir, "test.md")]: TEST_COMMAND_TEMPLATE,
+    [useCollector ? `${docsRel}/README.md` : join10(docsDir, "README.md")]: substitute(DOCS_README_TEMPLATE, vars)
   };
   if (!docsIndexExists) {
     scaffoldFiles[docsIndexPath] = substitute(DOCS_INDEX_TEMPLATE, vars);
@@ -18632,7 +19042,7 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
   if (useCollector) {
     scaffoldFiles[".cursor/rules/papi.mdc"] = substitute(CURSOR_RULES_TEMPLATE, vars);
   } else {
-    const cursorDir = join9(config2.projectRoot, ".cursor");
+    const cursorDir = join10(config2.projectRoot, ".cursor");
     let cursorDetected = false;
     try {
       await access2(cursorDir);
@@ -18640,8 +19050,8 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
     } catch {
     }
     if (cursorDetected) {
-      const cursorRulesDir = join9(cursorDir, "rules");
-      const cursorRulesPath = join9(cursorRulesDir, "papi.mdc");
+      const cursorRulesDir = join10(cursorDir, "rules");
+      const cursorRulesPath = join10(cursorRulesDir, "papi.mdc");
       await mkdir(cursorRulesDir, { recursive: true });
       try {
         await access2(cursorRulesPath);
@@ -18659,6 +19069,9 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
       await writeFile2(filepath, content, "utf-8");
     }
   }
+  for (const p of Object.keys(scaffoldFiles)) {
+    preparedFiles.push(useCollector ? p : relative(config2.projectRoot, p));
+  }
   if (!useCollector && detectsFrontendStack(config2.projectRoot)) {
     for (const entry of planDesignInstall(config2.projectRoot, { skipExisting: true })) {
       await mkdir(dirname3(entry.dest), { recursive: true });
@@ -18683,20 +19096,38 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
     }]);
   }
   if (useCollector) {
-    collector.add({
-      path: ".claude/settings.json",
-      content: JSON.stringify({ permissions: { allow: [PAPI_PERMISSION] } }, null, 2) + "\n",
-      mode: "create",
-      skip_if_exists: true
-    });
+    collector.add(papiSettingsCollectorEntry());
   } else {
     await ensurePapiPermission(config2.projectRoot);
   }
-  return true;
+  return { createdProject: true, preparedFiles };
+}
+var PAPI_PERMISSIONS = ["mcp__papi__*", "mcp__plugin_papi_papi__*"];
+function papiSettingsCollectorEntry() {
+  return {
+    path: ".claude/settings.json",
+    content: JSON.stringify(mergePapiPermissions({}), null, 2) + "\n",
+    mode: "merge-json"
+  };
+}
+function mergePapiPermissions(settings) {
+  if (!settings.permissions || typeof settings.permissions !== "object") {
+    settings.permissions = {};
+  }
+  const perms = settings.permissions;
+  if (!Array.isArray(perms.allow)) {
+    perms.allow = [];
+  }
+  const allow = perms.allow;
+  for (const permission of PAPI_PERMISSIONS) {
+    if (!allow.includes(permission)) {
+      allow.push(permission);
+    }
+  }
+  return settings;
 }
-var PAPI_PERMISSION = "mcp__papi__*";
 async function ensurePapiPermission(projectRoot) {
-  const settingsPath = join9(projectRoot, ".claude", "settings.json");
+  const settingsPath = join10(projectRoot, ".claude", "settings.json");
   try {
     let settings = {};
     try {
@@ -18704,24 +19135,14 @@ async function ensurePapiPermission(projectRoot) {
       settings = JSON.parse(existing);
     } catch {
     }
-    if (!settings.permissions || typeof settings.permissions !== "object") {
-      settings.permissions = {};
-    }
-    const perms = settings.permissions;
-    if (!Array.isArray(perms.allow)) {
-      perms.allow = [];
-    }
-    const allow = perms.allow;
-    if (!allow.includes(PAPI_PERMISSION)) {
-      allow.push(PAPI_PERMISSION);
-    }
-    await mkdir(join9(projectRoot, ".claude"), { recursive: true });
+    mergePapiPermissions(settings);
+    await mkdir(join10(projectRoot, ".claude"), { recursive: true });
     await writeFile2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
   } catch {
   }
 }
 async function ensureDesignHookRegistered(projectRoot) {
-  const settingsPath = join9(projectRoot, ".claude", "settings.json");
+  const settingsPath = join10(projectRoot, ".claude", "settings.json");
   try {
     let settings = {};
     try {
@@ -18751,7 +19172,7 @@ async function ensureDesignHookRegistered(projectRoot) {
         chain.push({ type: "command", command: DESIGN_HOOK_COMMAND });
       }
     }
-    await mkdir(join9(projectRoot, ".claude"), { recursive: true });
+    await mkdir(join10(projectRoot, ".claude"), { recursive: true });
     await writeFile2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
   } catch {
   }
@@ -18857,7 +19278,7 @@ ${conventionsText.trim()}
       );
     } else {
       try {
-        const claudeMdPath = join9(config2.projectRoot, "CLAUDE.md");
+        const claudeMdPath = join10(config2.projectRoot, "CLAUDE.md");
         const existing = await readFile4(claudeMdPath, "utf-8");
         if (existing.includes(CONVENTIONS_SENTINEL) || existing.includes(CONVENTIONS_HEADING)) {
           warnings.push(
@@ -18944,13 +19365,13 @@ async function scanCodebase(projectRoot) {
   }
   let packageJson;
   try {
-    const content = await readFile4(join9(projectRoot, "package.json"), "utf-8");
+    const content = await readFile4(join10(projectRoot, "package.json"), "utf-8");
     packageJson = JSON.parse(content);
   } catch {
   }
   let readme;
   for (const name of ["README.md", "readme.md", "README.txt", "README"]) {
-    const content = await safeReadFile(join9(projectRoot, name), 5e3);
+    const content = await safeReadFile(join10(projectRoot, name), 5e3);
     if (content) {
       readme = content;
       break;
@@ -18960,7 +19381,7 @@ async function scanCodebase(projectRoot) {
   let totalFiles = topLevelFiles.length;
   for (const dir of topLevelDirs) {
     try {
-      const entries = await readdir(join9(projectRoot, dir), { withFileTypes: true });
+      const entries = await readdir(join10(projectRoot, dir), { withFileTypes: true });
       const files = entries.filter((e) => e.isFile());
       const extensions = [...new Set(files.map((f) => extname(f.name).toLowerCase()).filter(Boolean))];
       totalFiles += files.length;
@@ -19043,7 +19464,7 @@ function formatCodebaseSummary(scan, sourceContents) {
 }
 async function prepareSetup(adapter2, config2, input) {
   const prepareCollector = new FileWriteCollector();
-  const createdProject = await scaffoldPapiDir(adapter2, config2, input, prepareCollector);
+  const { createdProject, preparedFiles } = await scaffoldPapiDir(adapter2, config2, input, prepareCollector);
   let existingBrief;
   try {
     existingBrief = await adapter2.readProductBrief();
@@ -19212,12 +19633,13 @@ async function prepareSetup(adapter2, config2, input) {
     preScanInstruction,
     newProjectInstruction,
     warnings: warnings.length > 0 ? warnings : void 0,
-    filesToWrite: prepareCollector.isEmpty() ? void 0 : prepareCollector
+    filesToWrite: prepareCollector.isEmpty() ? void 0 : prepareCollector,
+    preparedFiles
   };
 }
 async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText, northStarText) {
   const collector = new FileWriteCollector();
-  const createdProject = await scaffoldPapiDir(adapter2, config2, input, collector);
+  const { createdProject, preparedFiles } = await scaffoldPapiDir(adapter2, config2, input, collector);
   let effectiveBriefText = briefText;
   let briefRegenerated = false;
   if (!effectiveBriefText.trim()) {
@@ -19346,7 +19768,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
       collector.add({ path: "CLAUDE.md", content: dogfoodSection, mode: "append" });
     } else {
       try {
-        const claudeMdPath = join9(config2.projectRoot, "CLAUDE.md");
+        const claudeMdPath = join10(config2.projectRoot, "CLAUDE.md");
         const existing = await readFile4(claudeMdPath, "utf-8");
         if (!existing.includes("Dogfood Logging")) {
           await writeFile2(claudeMdPath, existing + dogfoodSection, "utf-8");
@@ -19391,7 +19813,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     cursorScaffolded = true;
   } else {
     try {
-      await access2(join9(config2.projectRoot, ".cursor", "rules", "papi.mdc"));
+      await access2(join10(config2.projectRoot, ".cursor", "rules", "papi.mdc"));
       cursorScaffolded = true;
     } catch {
     }
@@ -19407,16 +19829,17 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     cursorScaffolded,
     gitignoreNote,
     warnings: warnings.length > 0 ? warnings : void 0,
-    filesToWrite: collector.isEmpty() ? void 0 : collector
+    filesToWrite: collector.isEmpty() ? void 0 : collector,
+    preparedFiles
   };
 }
 async function ensureMcpJsonGitignored(projectRoot) {
   try {
-    await access2(join9(projectRoot, ".git"));
+    await access2(join10(projectRoot, ".git"));
   } catch {
     return void 0;
   }
-  const gitignorePath = join9(projectRoot, ".gitignore");
+  const gitignorePath = join10(projectRoot, ".gitignore");
   let existing = "";
   try {
     existing = await readFile4(gitignorePath, "utf-8");
@@ -19565,8 +19988,14 @@ function extractInput(args) {
     codebaseScan: args.codebase_scan && typeof args.codebase_scan === "object" ? args.codebase_scan : void 0
   };
 }
+function harnessFilesLabel(prepared, writesClaudeMd) {
+  const HARNESS_FILES = ["AGENTS.md", "CLAUDE.md"];
+  const emitted = HARNESS_FILES.filter((f) => prepared?.includes(f));
+  if (emitted.length > 0) return emitted.join(", ");
+  return writesClaudeMd ? "AGENTS.md, CLAUDE.md" : "AGENTS.md";
+}
 function formatSuccessResponse(result, constraints, writesClaudeMd = true) {
-  const harnessFiles = writesClaudeMd ? "AGENTS.md, CLAUDE.md" : "AGENTS.md";
+  const harnessFiles = harnessFilesLabel(result.preparedFiles, writesClaudeMd);
   const prefix = result.createdProject ? `PAPI project "${result.projectName}" initialised and ` : "";
   const briefRegenNote = result.briefRegenerated ? `
 
@@ -19982,8 +20411,8 @@ function buildPapiMetaFramingDirective(caps, inner) {
 
 // src/services/build.ts
 import { randomUUID as randomUUID11 } from "crypto";
-import { readdirSync as readdirSync5, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, mkdirSync as mkdirSync3 } from "fs";
-import { join as join12 } from "path";
+import { readdirSync as readdirSync5, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync5, unlinkSync as unlinkSync3, mkdirSync as mkdirSync3 } from "fs";
+import { join as join13 } from "path";
 import { splitFindings, findingKey } from "@papi-ai/shared";
 
 // src/lib/db-only-notices.ts
@@ -20150,7 +20579,7 @@ init_git();
 // src/services/release.ts
 init_telemetry();
 import { writeFile as writeFile3, readFile as readFile5 } from "fs/promises";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 import { execFileSync as execFileSync4 } from "child_process";
 import { isSensitiveChangelogLine } from "@papi-ai/shared";
 init_git();
@@ -20624,7 +21053,7 @@ async function createRelease(config2, branch, version, adapter2, cycleNum, optio
     }
   }
   const latestTag = getLatestTag(config2.projectRoot);
-  const changelogPath = join10(config2.projectRoot, "CHANGELOG.md");
+  const changelogPath = join11(config2.projectRoot, "CHANGELOG.md");
   if (!latestTag) {
     const initialContent = INITIAL_RELEASE_NOTES.replace("v0.1.0-alpha", version);
     if (config2.adapterType === "proxy") {
@@ -20780,33 +21209,12 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var REGISTRY_TIMEOUT_MS = 12e4;
-async function updateOfficialMCPRegistry(version) {
-  const token = process.env["MCP_REGISTRY_GITHUB_TOKEN"]?.trim();
-  if (!token) {
-    return {
-      registry: "Official MCP Registry",
-      updated: false,
-      message: `Listing not updated \u2014 set MCP_REGISTRY_GITHUB_TOKEN to automate, or run manually: npx mcp-publisher publish`
-    };
-  }
-  try {
-    await execFileAsync("npx", ["mcp-publisher", "publish", "--yes"], {
-      env: { ...process.env, GITHUB_TOKEN: token },
-      timeout: REGISTRY_TIMEOUT_MS
-    });
-    return {
-      registry: "Official MCP Registry",
-      updated: true,
-      message: `Listing updated to ${version}.`
-    };
-  } catch (err) {
-    const detail = err instanceof Error ? err.message.slice(0, 300) : String(err).slice(0, 300);
-    return {
-      registry: "Official MCP Registry",
-      updated: false,
-      message: `Update failed \u2014 run manually: npx mcp-publisher publish. (${detail})`
-    };
-  }
+function officialMCPRegistryGuidance(version) {
+  return {
+    registry: "Official MCP Registry",
+    updated: false,
+    message: `Listing not updated (manual step). From a checkout of getpapi/papi: \`mcp-publisher login github\` (once), then \`mcp-publisher publish\` \u2014 bump server.json to ${version} first. Requires the Go CLI (brew install mcp-publisher), NOT the npm package of the same name.`
+  };
 }
 async function updateSmithery(version) {
   const key = process.env["SMITHERY_API_KEY"]?.trim();
@@ -20837,11 +21245,8 @@ async function updateSmithery(version) {
   }
 }
 async function updateRegistryListings(version) {
-  const [official, smithery] = await Promise.all([
-    updateOfficialMCPRegistry(version),
-    updateSmithery(version)
-  ]);
-  return [official, smithery];
+  const [smithery] = await Promise.all([updateSmithery(version)]);
+  return [officialMCPRegistryGuidance(version), smithery];
 }
 async function updateCursorDirectory(version) {
   const token = process.env["CURSOR_DIRECTORY_GITHUB_TOKEN"]?.trim();
@@ -21459,21 +21864,21 @@ function detectWorktreeCollision(input) {
 init_git();
 
 // src/lib/build-checkpoint.ts
-import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
-import { join as join11 } from "path";
+import { createHash as createHash5 } from "crypto";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "fs";
+import { join as join12 } from "path";
 var BUILD_CHECKPOINT_VERSION = 1;
 function cwdHash(cwd) {
-  return createHash4("sha256").update(realpathOrSelf(cwd)).digest("hex").slice(0, 12);
+  return createHash5("sha256").update(realpathOrSelf(cwd)).digest("hex").slice(0, 12);
 }
 function safeTaskId(taskId) {
   return taskId.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
 function checkpointDir(cwd) {
-  return join11(cwd, ".papi", "state");
+  return join12(cwd, ".papi", "state");
 }
 function checkpointPath(cwd, taskId) {
-  return join11(checkpointDir(cwd), `build-${safeTaskId(taskId)}.${cwdHash(cwd)}.json`);
+  return join12(checkpointDir(cwd), `build-${safeTaskId(taskId)}.${cwdHash(cwd)}.json`);
 }
 function writeBuildCheckpoint(input) {
   try {
@@ -21491,7 +21896,7 @@ function writeBuildCheckpoint(input) {
       cwd: realpathOrSelf(input.cwd),
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    writeFileSync3(checkpointPath(input.cwd, input.taskId), JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
+    writeFileSync4(checkpointPath(input.cwd, input.taskId), JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
   } catch {
   }
 }
@@ -21750,7 +22155,7 @@ function pathBasename(p) {
   const parts = p.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
   return parts[parts.length - 1] ?? p;
 }
-function isPathInPredictedScope(changedPath, predicted) {
+function matchedPredictedEntry(changedPath, predicted) {
   const changed = changedPath.replace(/\\/g, "/");
   const changedLower = changed.toLowerCase();
   const changedBase = pathBasename(changedPath);
@@ -21758,17 +22163,20 @@ function isPathInPredictedScope(changedPath, predicted) {
     const entry = raw.replace(/\\/g, "/").replace(/\/+$/, "").trim();
     if (!entry) continue;
     if (entry.includes("*")) {
-      if (globToRegExp(entry).test(changed)) return true;
-      if (!entry.includes("/") && globToRegExp(entry).test(changedBase)) return true;
+      if (globToRegExp(entry).test(changed)) return entry;
+      if (!entry.includes("/") && globToRegExp(entry).test(changedBase)) return entry;
       continue;
     }
-    if (pathBasename(entry) === changedBase) return true;
+    if (pathBasename(entry) === changedBase) return entry;
     const entryLower = entry.toLowerCase();
     if (changedLower === entryLower || changedLower.startsWith(`${entryLower}/`)) {
-      return true;
+      return entry;
     }
   }
-  return false;
+  return null;
+}
+function isPathInPredictedScope(changedPath, predicted) {
+  return matchedPredictedEntry(changedPath, predicted) !== null;
 }
 function autoCommit(config2, taskId, taskTitle, predictedFiles) {
   const cwd = config2.projectRoot;
@@ -21794,6 +22202,17 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
   if (staged.length > 0) {
     return safeRun(() => commitStagedOnly(cwd, message)) + ` (selective staging respected: ${staged.length} file(s)).`;
   }
+  const checkpoint = readBuildCheckpointIfLocal({ cwd, taskId });
+  const headSha = getHeadCommitSha(cwd);
+  if (checkpoint?.lastCommitSha && headSha && checkpoint.lastCommitSha !== headSha) {
+    const leftover = getModifiedFiles(cwd);
+    if (leftover.length === 0) {
+      return "Auto-commit: skipped (builder already committed; working tree clean).";
+    }
+    const sample = leftover.slice(0, 10).join(", ");
+    const more = leftover.length > 10 ? ` (+${leftover.length - 10} more)` : "";
+    return `Auto-commit: skipped \u2014 you already committed during this build, and ${leftover.length} file(s) are still modified. They were NOT committed, because at this point PAPI cannot tell your deliberately-excluded work from a concurrent session's files (task-3054). Left uncommitted: ${sample}${more}. If any belong to ${taskId}, \`git add\` them and re-run build_execute complete.`;
+  }
   const modified = getModifiedFiles(cwd);
   if (modified.length === 0) {
     return "Auto-commit: skipped (no working-tree changes).";
@@ -21807,7 +22226,9 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
       const more = outOfScope.length > 10 ? ` (+${outOfScope.length - 10} more)` : "";
       return `${commitResult} (staged all ${modified.length} changed file(s)). \u2139\uFE0F Scope drift: ${outOfScope.length} committed file(s) were outside the handoff's FILES LIKELY TOUCHED \u2014 handoff under-predicted: ${sample}${more}.`;
     }
-    return `${commitResult} (staged all ${modified.length} changed file(s), all within FILES LIKELY TOUCHED).`;
+    const matches = modified.slice(0, 5).map((p) => `${p} \u2190 ${matchedPredictedEntry(p, cleanedPredicted) ?? "?"}`).join(", ");
+    const extra = modified.length > 5 ? ` (+${modified.length - 5} more)` : "";
+    return `${commitResult} (staged all ${modified.length} changed file(s), each matched to FILES LIKELY TOUCHED: ${matches}${extra}).`;
   }
   return `${commitResult} (staged all ${modified.length} changed file(s)).`;
 }
@@ -22369,15 +22790,15 @@ function writeActiveTaskScope(projectRoot, taskId, filesLikelyTouched, adapterTy
     collector.add({ path: ".papi/active-task-scope.txt", content, mode: "overwrite" });
     return;
   }
-  const papiDir = join12(projectRoot, ".papi");
+  const papiDir = join13(projectRoot, ".papi");
   if (!existsSync8(papiDir)) {
     mkdirSync3(papiDir, { recursive: true });
   }
-  const scopePath = join12(papiDir, "active-task-scope.txt");
-  writeFileSync4(scopePath, content, "utf-8");
+  const scopePath = join13(papiDir, "active-task-scope.txt");
+  writeFileSync5(scopePath, content, "utf-8");
 }
 function clearActiveTaskScope(projectRoot) {
-  const scopePath = join12(projectRoot, ".papi", "active-task-scope.txt");
+  const scopePath = join13(projectRoot, ".papi", "active-task-scope.txt");
   if (existsSync8(scopePath)) {
     unlinkSync3(scopePath);
   }
@@ -22837,29 +23258,39 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
   let docWarning;
   try {
     if (adapter2.searchDocs && hasLocalWorkspace() && await ownsLocalWorkspace(adapter2, config2.projectRoot)) {
-      const docsDir = join12(config2.projectRoot, "docs");
+      const docsDir = join13(config2.projectRoot, "docs");
       if (existsSync8(docsDir)) {
         const scanDir = (dir, depth = 0) => {
           if (depth > 8) return [];
           const entries = readdirSync5(dir, { withFileTypes: true });
           const files = [];
           for (const e of entries) {
-            const full = join12(dir, e.name);
+            const full = join13(dir, e.name);
             if (e.isDirectory() && !e.isSymbolicLink()) files.push(...scanDir(full, depth + 1));
             else if (e.name.endsWith(".md")) files.push(full.replace(config2.projectRoot + "/", ""));
           }
           return files;
         };
         const mdFiles = scanDir(docsDir);
+        let branchDocs;
+        try {
+          branchDocs = new Set(
+            getFilesChangedFromBase(config2.projectRoot, "origin/main").filter((f) => f.startsWith("docs/") && f.endsWith(".md"))
+          );
+        } catch {
+          branchDocs = /* @__PURE__ */ new Set();
+        }
         const registered = await adapter2.searchDocs({ status: "all", limit: 500 });
         const registeredPaths = new Set(registered.map((d) => d.path));
-        const unregistered = mdFiles.filter((f) => !registeredPaths.has(f));
+        const unregistered = mdFiles.filter(
+          (f) => !registeredPaths.has(f) && branchDocs.has(f)
+        );
         if (unregistered.length > 0 && adapter2.registerDoc) {
           const autoRegistered = [];
           const failed = [];
           for (const docPath of unregistered) {
             try {
-              const meta = extractDocMeta(join12(config2.projectRoot, docPath), docPath, cycleNumber);
+              const meta = extractDocMeta(join13(config2.projectRoot, docPath), docPath, cycleNumber);
               await adapter2.registerDoc({
                 title: meta.title,
                 type: meta.type,
@@ -23029,15 +23460,15 @@ ${instructions}`;
 }
 
 // src/tools/doc-registry.ts
-import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync4 } from "fs";
-import { join as join13, relative, isAbsolute as isAbsolute2, dirname as dirname4, resolve as resolve3, sep } from "path";
+import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4 } from "fs";
+import { join as join14, relative as relative2, isAbsolute as isAbsolute2, dirname as dirname4, resolve as resolve3, sep } from "path";
 import { homedir as homedir3 } from "os";
 import { randomUUID as randomUUID12 } from "crypto";
 import { docDeletionBlockMessage } from "@papi-ai/shared";
 init_git();
 
 // src/services/entitlements.ts
-import { evaluateContributorGate } from "@papi-ai/shared";
+import { evaluateContributorGate, isSelfHostedDeployment } from "@papi-ai/shared";
 var FREE_PROJECT_CAP = 3;
 var DOC_STORAGE_CEILING_BY_TIER = {
   free: { bytes: 25 * 1024 * 1024, docs: 200 },
@@ -23060,6 +23491,7 @@ function isPaidTier(tier) {
   return tier !== null && PAID_TIERS.has(tier);
 }
 async function enforceProjectCap(adapter2, target) {
+  if (isSelfHostedDeployment(process.env.PAPI_SELF_HOST)) return null;
   const tier = await resolveTier(adapter2);
   if (tier === null || isPaidTier(tier)) return null;
   if (typeof adapter2.listUserProjects !== "function") return null;
@@ -23170,7 +23602,11 @@ var docRegisterTool = {
         },
         description: "Actionable findings from the document."
       },
-      superseded_by_path: { type: "string", description: "Path of the doc that supersedes this one (sets status to superseded)." }
+      superseded_by_path: { type: "string", description: "Path of the doc that supersedes this one (sets status to superseded)." },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to register this doc under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
+      }
     },
     required: ["path", "title", "type", "summary", "cycle"]
   }
@@ -23265,7 +23701,7 @@ function ensureDocDurable(path7, projectRoot) {
 \u26A0\uFE0F **Registered, but NOT durable.** ${reason}
 The registry stores metadata and a summary \u2014 not the body. This doc has one copy, on disk, and a branch switch or stash can take it.
 **Fix:** ${fix}`;
-  if (!existsSync9(join13(projectRoot, path7))) {
+  if (!existsSync9(join14(projectRoot, path7))) {
     return warn(
       `No file exists at \`${path7}\`.`,
       `write the doc body to that path, then re-run doc_register.`
@@ -23327,6 +23763,22 @@ async function handleDocRegister(adapter2, args, config2) {
       continueHint
     );
   }
+  let target = adapter2;
+  let overrideNote = "";
+  try {
+    ({ adapter: target, overrideNote } = await resolvePerCallProjectAdapter(adapter2, args));
+  } catch (err) {
+    if (err instanceof ProjectResolutionError) return errorResponse(err.message);
+    throw err;
+  }
+  if (!target.registerDoc) {
+    return docRegisterSoftFail(
+      adapterType,
+      "adapter-capability-check",
+      "Doc registry not available on the resolved project adapter \u2014 requires the pg/proxy adapter.",
+      "Continue without it \u2014 nothing is blocked."
+    );
+  }
   if (!path7.toLowerCase().endsWith(".md")) {
     return docRegisterSoftFail(
       adapterType,
@@ -23338,13 +23790,13 @@ async function handleDocRegister(adapter2, args, config2) {
   try {
     let supersededBy;
     if (supersededByPath) {
-      const existing = await adapter2.getDoc?.(supersededByPath);
+      const existing = await target.getDoc?.(supersededByPath);
       if (existing) {
         supersededBy = existing.id;
-        await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
+        await target.updateDocStatus?.(existing.id, "superseded", void 0);
       }
     }
-    const entry = await adapter2.registerDoc({
+    const entry = await target.registerDoc({
       title,
       type,
       path: path7,
@@ -23363,23 +23815,23 @@ async function handleDocRegister(adapter2, args, config2) {
       let body = supplied;
       if (body === void 0 && hasLocalWorkspace()) {
         try {
-          const abs = isAbsolute2(entry.path) ? entry.path : join13(config2?.projectRoot ?? process.cwd(), entry.path);
+          const abs = isAbsolute2(entry.path) ? entry.path : join14(config2?.projectRoot ?? process.cwd(), entry.path);
           if (existsSync9(abs)) body = readFileSync8(abs, "utf8");
         } catch {
         }
       }
       if (body === void 0) {
         bodyNote = hasLocalWorkspace() ? "\n\n_Body not stored \u2014 the file could not be read from disk. Pass `body` to store it._" : "\n\n_Body not stored \u2014 no local workspace on this session. Pass `body` to store it._";
-      } else if (typeof adapter2.storeDocBody !== "function") {
+      } else if (typeof target.storeDocBody !== "function") {
         bodyNote = "\n\n_Body not stored \u2014 this adapter does not support body storage._";
       } else {
-        const decision = await checkDocStorageCap(adapter2, Buffer.byteLength(body, "utf8"));
+        const decision = await checkDocStorageCap(target, Buffer.byteLength(body, "utf8"));
         if (!decision.storeBody) {
           bodyNote = `
 
 ${decision.message}`;
         } else {
-          const result = await adapter2.storeDocBody({
+          const result = await target.storeDocBody({
             docId: entry.id,
             body,
             // Resolved by resolveDocVisibility above — the SAME resolution the
@@ -23403,7 +23855,7 @@ ${decision.message}`;
       durability = "";
     }
     return textResponse(
-      `**Registered:** ${entry.title}
+      `**Registered:** ${entry.title}${overrideNote}
 - **Path:** ${entry.path}
 - **Type:** ${entry.type} | **Status:** ${entry.status}
 - **Visibility:** ${visibilityLabel}
@@ -23437,7 +23889,7 @@ async function handleDocSearch(adapter2, args, config2) {
   const lines = docs.map((d) => {
     const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
     const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
-    const missingNote = root && d.path && !existsSync9(join13(root, d.path)) ? `
+    const missingNote = root && d.path && !existsSync9(join14(root, d.path)) ? `
 > \u26A0\uFE0F **File missing on disk** \u2014 the registry points at \`${d.path}\` but nothing is there. Recover it with \`doc_read\` (\`id_or_path: "${d.path}", write_to_disk: true\`) if its body was stored, or check \`git stash list\` for a papi-autostash entry.` : "";
     return `### ${d.title}
 **Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
@@ -23531,7 +23983,7 @@ function restoreBodyToDisk(projectRoot, docPath, body) {
 `;
     }
     mkdirSync4(dirname4(target.abs), { recursive: true });
-    writeFileSync5(target.abs, body, "utf8");
+    writeFileSync6(target.abs, body, "utf8");
     return `- **Restored:** wrote ${Buffer.byteLength(body, "utf8").toLocaleString()} bytes to \`${docPath}\`
 `;
   } catch (err) {
@@ -23546,11 +23998,11 @@ function scanMdFiles(dir, rootDir) {
   try {
     const entries = readdirSync6(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = join13(dir, entry.name);
+      const full = join14(dir, entry.name);
       if (entry.isDirectory()) {
         files.push(...scanMdFiles(full, rootDir));
       } else if (entry.name.endsWith(".md")) {
-        files.push(relative(rootDir, full).replace(/\\/g, "/"));
+        files.push(relative2(rootDir, full).replace(/\\/g, "/"));
       }
     }
   } catch {
@@ -23571,7 +24023,7 @@ function extractTitle(filePath) {
 async function detectUnregisteredDocsNote(adapter2, config2) {
   try {
     if (!adapter2.searchDocs || !hasLocalWorkspace()) return "";
-    const docsDir = join13(config2.projectRoot, "docs");
+    const docsDir = join14(config2.projectRoot, "docs");
     const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
     if (docsFiles.length === 0) return "";
     const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -23597,17 +24049,17 @@ async function handleDocScan(adapter2, config2, args) {
   const includePlans = args.include_plans ?? false;
   const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
   const registeredPaths = new Set(registered.map((d) => d.path));
-  const docsDir = join13(config2.projectRoot, "docs");
+  const docsDir = join14(config2.projectRoot, "docs");
   const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
   const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
   let unregisteredPlans = [];
   if (includePlans) {
-    const plansDir = join13(homedir3(), ".claude", "plans");
+    const plansDir = join14(homedir3(), ".claude", "plans");
     if (existsSync9(plansDir)) {
       const planFiles = scanMdFiles(plansDir, plansDir);
       unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
         path: f,
-        title: extractTitle(join13(plansDir, f.replace("plans/", "")))
+        title: extractTitle(join14(plansDir, f.replace("plans/", "")))
       }));
     }
   }
@@ -23618,7 +24070,7 @@ async function handleDocScan(adapter2, config2, args) {
   if (unregisteredDocs.length > 0) {
     lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
     for (const f of unregisteredDocs) {
-      const title = extractTitle(join13(config2.projectRoot, f));
+      const title = extractTitle(join14(config2.projectRoot, f));
       lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
     }
   }
@@ -23967,7 +24419,7 @@ var buildExecuteTool = {
       },
       fixed_issues: {
         type: "array",
-        description: `cycle_learnings UUIDs of discovered issues this build FIXED. Stamps resolved_at (via the existing discovered_issue_resolve path) so the hub's "What PAPI caught" surface counts them as fixed on the caught\u2192fixed ledger \u2014 triage-and-fix at build time, no separate tool call. Distinct from resolves_learnings, which only LINKS a learning to this task without closing it. Best-effort and idempotent.`,
+        description: `cycle_learnings UUIDs of discovered issues this build FIXED. SEND THIS whenever your work closed an issue listed under "OPEN DISCOVERED ISSUES" in the BUILD HANDOFF \u2014 that block prints the exact UUIDs to copy. Nothing else stamps a fix, so an unreported one is indistinguishable from an unfixed issue: the hub's "What PAPI caught" caught\u2192fixed ledger reads zero until this is passed. Stamps resolved_at via the existing discovered_issue_resolve path \u2014 triage-and-fix at build time, no separate tool call. Distinct from resolves_learnings, which only LINKS a learning to this task without closing it. Do not pass UUIDs for issues you did not actually fix. Best-effort and idempotent.`,
         items: { type: "string" }
       },
       production_verification: {
@@ -24325,7 +24777,7 @@ ${entries}`;
 
 **OPEN DISCOVERED ISSUES** (${top.length} shown):
 ${rows}
-If this build fixes any of these, pass their UUIDs in \`fixed_issues\` on complete \u2014 that stamps them FIXED on the caught\u2192fixed ledger. Do not fix out-of-scope issues just to clear the list.`;
+CONTRACT \u2014 on complete, pass \`fixed_issues\` with the UUID of any issue above that this build closed, and say so even if the answer is none. Closing an issue without stamping it leaves the caught\u2192fixed ledger reading zero, which is what it reads today. Do NOT fix out-of-scope issues just to clear the list \u2014 the ask is to REPORT what you closed, not to close more.`;
         }
       }
     } catch {
@@ -24572,8 +25024,25 @@ Your report was NOT discarded and the task is NOT yet Done \u2014 re-send with \
       fixedNote = `
 
 \u2705 Marked ${fixedResolvedCount} discovered issue(s) FIXED \u2014 resolved_at stamped, now counted as fixed on the hub's caught\u2192fixed ledger.`;
-    } else if (discoveredIssues && discoveredIssues.trim() !== "" && !/^none\b/i.test(discoveredIssues.trim())) {
-      fixedNote = "\n\n\u2139\uFE0F This build filed discovered issues but passed no `fixed_issues`. When a future build fixes one, pass its UUID in `fixed_issues` so it counts as FIXED (not just auto-cleared) on the hub ledger.";
+    } else {
+      let candidates = [];
+      try {
+        if (adapter2.getCycleLearnings) {
+          const open = (await adapter2.getCycleLearnings({ category: "issue", limit: 20 })).filter((l) => !l.resolvedAt && l.id);
+          const moduleTag = result.task?.module?.trim().toLowerCase();
+          candidates = open.filter((l) => !moduleTag || l.tags.some((t) => t.toLowerCase() === moduleTag)).slice(0, 5).map((l) => `  - \`${l.id}\` \xB7 ${l.severity ?? "P3"} \xB7 ${l.summary.slice(0, 120)}`);
+        }
+      } catch {
+      }
+      if (candidates.length > 0) {
+        fixedNote = `
+
+\u2139\uFE0F No \`fixed_issues\` passed. Open issues in this module that this build could have closed:
+${candidates.join("\n")}
+If any are now fixed, re-run complete with their UUIDs in \`fixed_issues\` \u2014 nothing else stamps them, so an unreported fix is indistinguishable from an unfixed issue on the hub ledger.`;
+      } else if (discoveredIssues && discoveredIssues.trim() !== "" && !/^none\b/i.test(discoveredIssues.trim())) {
+        fixedNote = "\n\n\u2139\uFE0F This build filed discovered issues but passed no `fixed_issues`. When a future build fixes one, pass its UUID in `fixed_issues` so it counts as FIXED (not just auto-cleared) on the hub ledger.";
+      }
     }
     return textResponse(formatCompleteResult(result) + fixedNote + docsNote + batchRollupNote);
   } catch (err) {
@@ -24787,6 +25256,10 @@ var ideaTool = {
         type: "string",
         description: "What user problem does this solve? Auto-fill from problem context in notes when submitting ideas that describe a user pain point. The planner uses this to cluster backlog tasks by opportunity."
       },
+      conflicts_with_ad: {
+        type: "string",
+        description: 'The Active Decision this idea cuts against, e.g. "AD-12". USE THIS INSTEAD OF DROPPING THE IDEA. An AD is *active* \u2014 it can be superseded \u2014 so a contradiction is a decision for the user, never a reason for you to shelve work during research or scoping. The task is created and parked Blocked behind a decision-gate on that AD: it shows in `orient` as a decision waiting on the owner, and returns to the board automatically once the AD is superseded, modified, or reaffirmed.'
+      },
       project: {
         type: "string",
         description: "Project id (UUID) or slug to write this idea to, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
@@ -24819,7 +25292,8 @@ async function handleIdea(adapter2, config2, args) {
     force: args.force === true,
     docRef: args.doc_ref?.trim(),
     type: args.type,
-    opportunity: args.opportunity?.trim()
+    opportunity: args.opportunity?.trim(),
+    conflictsWithAd: args.conflicts_with_ad?.trim()
   };
   let target = adapter2;
   let overrideNote = "";
@@ -24864,7 +25338,12 @@ Re-submit with \`notes: "... Reference: <path>"\` to link one, or ignore if none
       } catch {
       }
     }
-    return textResponse(`${result.message}${overrideNote}${branchNote}${truncateWarning}${refNudge}`);
+    const conflictNote = result.adConflicts ? buildAdConflictNote(
+      result.adConflicts.explicit ? result.adConflicts.adIds[0] : void 0,
+      result.adConflicts.explicit ? [] : result.adConflicts.adIds,
+      result.adConflicts.gated
+    ) : "";
+    return textResponse(`${result.message}${overrideNote}${branchNote}${truncateWarning}${refNudge}${conflictNote}`);
   }
   return textResponse(`${result.message}${overrideNote}`);
 }
@@ -25603,6 +26082,13 @@ init_git();
 
 // src/services/ad-hoc.ts
 import { randomUUID as randomUUID15 } from "crypto";
+function resolveAdHocBranch(input) {
+  if (input.held) return `feat/${input.taskId}`;
+  const current = input.currentBranch?.trim();
+  if (!current) return void 0;
+  if (input.baseBranch && current === input.baseBranch.trim()) return void 0;
+  return current;
+}
 function resolveAdHocCycle(cycle, latest, latestComplete) {
   if (cycle === void 0) return null;
   if (typeof cycle === "number") return cycle;
@@ -25657,8 +26143,32 @@ async function recordAdHoc(adapter2, input) {
       ...targetCycle !== null ? { cycle: targetCycle } : {},
       notes: input.notes ? `[ad-hoc] ${input.notes}` : "[ad-hoc]",
       taskType: input.taskType || "task",
-      source: "ad_hoc"
+      source: "ad_hoc",
+      // task-2597: record the branch at creation for unheld work — the branch is
+      // already known. Held work needs the allocated display id first (below).
+      ...held ? {} : (() => {
+        const branch = resolveAdHocBranch({
+          held: false,
+          taskId: "",
+          currentBranch: input.currentBranch,
+          baseBranch: input.baseBranch
+        });
+        return branch ? { branchName: branch } : {};
+      })()
     });
+    if (held) {
+      const branch = resolveAdHocBranch({ held: true, taskId: task.id });
+      if (branch) {
+        try {
+          await adapter2.updateTask(task.id, { branchName: branch });
+          task = { ...task, branchName: branch };
+        } catch (err) {
+          console.error(
+            `[ad-hoc] branch_name persist skipped for ${task.id} (non-fatal): ` + (err instanceof Error ? err.message : String(err))
+          );
+        }
+      }
+    }
   }
   const report = {
     uuid: randomUUID15(),
@@ -25748,6 +26258,10 @@ var adHocTool = {
       hold: {
         type: "boolean",
         description: "task-2477: held-adhoc. When true, do NOT force-complete or commit to main \u2014 record the task In Review pinned to the NEXT cycle (current + 1) so the planner won't re-plan it, and return a branch/PR directive (commit on feat/<task-id>, never main, leave unmerged) so it rides the next cycle's review \u2192 release bundled with planned work. One-call replacement for the two-call ad_hoc + board_edit stopgap. Takes precedence over `cycle`/`stage`."
+      },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to record this work under, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise. Use project_switch to change the session default. PASS THIS WHENEVER YOU KNOW WHICH REPO THE SESSION IS IN: on a multi-project account a connection with no project bound cannot be resolved, and PAPI will stop and ask rather than guess."
       }
     },
     required: []
@@ -25784,7 +26298,18 @@ async function handleAdHoc(adapter2, config2, args) {
   else if (rawCycle === "current" || rawCycle === "next-if-plan-not-run") cycleArg = rawCycle;
   const stageArg = args.stage === "release" ? "release" : void 0;
   const holdArg = args.hold === true;
-  const result = await recordAdHoc(adapter2, {
+  let target = adapter2;
+  let overrideNote = "";
+  try {
+    ({ adapter: target, overrideNote } = await resolvePerCallProjectAdapter(adapter2, args));
+  } catch (err) {
+    if (err instanceof ProjectResolutionError) return errorResponse(err.message);
+    throw err;
+  }
+  const gitUsable = !overrideNote && isGitAvailable() && isGitRepo(config2.projectRoot);
+  const currentBranch = gitUsable ? getCurrentBranch(config2.projectRoot) : null;
+  const baseBranch = gitUsable ? resolveBaseBranch(config2.projectRoot, config2.baseBranch) : null;
+  const result = await recordAdHoc(target, {
     title: title || "",
     taskId,
     notes: rawNotes,
@@ -25797,9 +26322,11 @@ async function handleAdHoc(adapter2, config2, args) {
     owner: config2.projectOwner,
     cycle: cycleArg,
     stage: stageArg,
-    hold: holdArg
+    hold: holdArg,
+    currentBranch,
+    baseBranch
   });
-  if (!holdArg && isGitAvailable() && isGitRepo(config2.projectRoot)) {
+  if (!holdArg && gitUsable) {
     try {
       stageDirAndCommit(
         config2.projectRoot,
@@ -25817,7 +26344,7 @@ async function handleAdHoc(adapter2, config2, args) {
     const branch = `feat/${result.task.id}`;
     let collisionBlock = "";
     try {
-      const board = await adapter2.queryBoard({ status: ["In Progress"] });
+      const board = await target.queryBoard({ status: ["In Progress"] });
       const otherInProgress = board.filter((t) => t.id !== result.task.id && t.displayId !== result.task.id).map((t) => ({ taskId: t.displayId || t.id, branch: (t.branchName ?? "").trim() })).filter((t) => t.branch.length > 0);
       const collision = detectWorktreeCollision({
         taskId: result.task.id,
@@ -25841,7 +26368,7 @@ async function handleAdHoc(adapter2, config2, args) {
     } catch {
     }
     return textResponse(
-      `**${result.task.id}:** "${result.task.title}" held for review (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning}${promoNote} Build report attached.
+      `**${result.task.id}:** "${result.task.title}" held for review (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.
 
 ## Held for the next cycle \u2014 branch + commit, do NOT merge
 The task is recorded **In Review** and pinned to **Cycle ${result.task.cycle}**, so the planner won't re-plan it and it rides that cycle's review \u2192 release bundled with planned work.
@@ -25859,7 +26386,7 @@ _To correct: board_edit ${result.task.id} with updated fields._`
     );
   }
   return textResponse(
-    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning}${promoNote} Build report attached.
+    `**${result.task.id}:** "${result.task.title}" recorded (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule})${overrideNote}.${truncateWarning}${promoNote} Build report attached.
 _To correct: board_edit ${result.task.id} with updated fields._`
   );
 }
@@ -25869,11 +26396,11 @@ init_git();
 
 // src/services/reconcile.ts
 import { readFileSync as readFileSync9 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 function loadDocsIndex(projectRoot) {
   if (!hasLocalWorkspace()) return "";
   try {
-    const indexPath = join14(projectRoot, "docs", "INDEX.md");
+    const indexPath = join15(projectRoot, "docs", "INDEX.md");
     const raw = readFileSync9(indexPath, "utf8");
     const rows = raw.split("\n").filter((l) => l.startsWith("| ["));
     if (rows.length === 0) return "";
@@ -26450,7 +26977,7 @@ Produce your analysis and structured output above. Present Part 1 to the user an
 
 // src/tools/review.ts
 import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 init_git();
 
 // src/services/review.ts
@@ -26648,8 +27175,6 @@ Re-run build_execute complete with a production_verification field, then re-subm
 }
 
 // src/tools/review.ts
-var REVIEW_DISPATCH_THRESHOLD = 50 * 1024;
-var REVIEW_DISPATCH_CEILING = 40 * 1024;
 var REVIEW_ECHO_CAP = 4e3;
 function trimForEcho(text) {
   if (text.length <= REVIEW_ECHO_CAP) return text;
@@ -26679,7 +27204,7 @@ ${task.buildReport}` : "### Build Report\n(none recorded)";
 ${diff}
 \`\`\`` : "### Branch diff vs base\n(no diff resolved \u2014 not a git repo, no base ref, or no committed changes)";
   let projectContext = "";
-  const ctxPath = join15(config2.projectRoot, ".agents", "papi-context.md");
+  const ctxPath = join16(config2.projectRoot, ".agents", "papi-context.md");
   if (existsSync10(ctxPath)) {
     try {
       projectContext = `### Project context (.agents/papi-context.md)
@@ -26858,7 +27383,7 @@ function mergeAfterAccept(config2, taskId) {
     };
   }
   const details = [];
-  const papiDir = join15(config2.projectRoot, ".papi");
+  const papiDir = join16(config2.projectRoot, ".papi");
   if (existsSync10(papiDir)) {
     try {
       const commitResult = stageDirAndCommit(
@@ -26997,7 +27522,7 @@ async function handleReviewSubmit(adapter2, config2, args) {
   if (typeof rawPreset === "string" && rawPreset.length > 0 && !reviewPreset) {
     return errorResponse(`review_preset "${rawPreset}" is not valid. Use "gate", "full", or "security-focused".`);
   }
-  const autoDispatchOptIn = args.dispatch !== "inline" && process.env.PAPI_AUTO_DISPATCH !== "false" && isCapabilityEnabled(caps, "prReviewer");
+  const autoDispatchOptIn = args.dispatch !== "inline" && isCapabilityEnabled(caps, "prReviewer");
   const autoDispatchEligible = !verdict && autoDispatchOptIn;
   const capabilityAutoReviewEligible = verdict === "accept" && !autoReview && autoDispatchOptIn;
   let capabilityReviewSkippedNote = "";
@@ -27010,16 +27535,27 @@ async function handleReviewSubmit(adapter2, config2, args) {
     );
     if (!dispatch.ok) {
       if (explicitDispatch) return errorResponse(dispatch.error);
-    } else if (explicitDispatch || autoDispatchEligible && dispatch.contextBytes > REVIEW_DISPATCH_THRESHOLD) {
+    } else if (explicitDispatch || autoDispatchEligible && shouldDispatch(dispatch.contextBytes)) {
       return textResponse(dispatch.prompt);
     } else if (capabilityAutoReviewEligible) {
-      if (dispatch.contextBytes <= REVIEW_DISPATCH_CEILING) {
-        return textResponse(dispatch.prompt);
+      const delivery = planDelivery({
+        payload: dispatch.prompt,
+        kind: "review-context",
+        hasPendingWrite: true,
+        adapterType: config2.adapterType,
+        projectId: config2.projectId,
+        callerKey: taskId
+      });
+      if (delivery.mode === "inline") {
+        return textResponse(delivery.payload);
       }
       const kb = (dispatch.contextBytes / 1024).toFixed(0);
-      capabilityReviewSkippedNote = `
+      capabilityReviewSkippedNote = delivery.mode === "spilled" ? `
+
+> \u{1F4C4} pr-reviewer auto-review was too large to return inline (~${kb} KB), so it was written to a file instead of being dropped (task-3030). Verdict recorded. To run the review, read:
+> \`${delivery.path}\`` : `
 
-> \u26A0\uFE0F pr-reviewer auto-review skipped \u2014 the diff/build-report (~${kb} KB) exceeds the ${REVIEW_DISPATCH_CEILING / 1024} KB inline-dispatch ceiling, which would overflow the response and drop the accept (task-2854). Verdict recorded directly. To review the diff explicitly, run \`review_submit ${taskId} build-acceptance accept dispatch:"subagent"\`.`;
+> \u26A0\uFE0F pr-reviewer auto-review could not be delivered \u2014 the diff/build-report (~${kb} KB) exceeds the inline ceiling and this connection has no shared filesystem to spill to. Verdict recorded. To review the diff explicitly, run \`review_submit ${taskId} build-acceptance accept dispatch:"subagent"\`.`;
     }
   }
   if (explicitDispatch && stage !== "build-acceptance") {
@@ -28491,7 +29027,7 @@ function formatDeferredGateSection(sweep) {
 
 // src/tools/agent-list.ts
 import { readdir as readdir2, readFile as readFile7 } from "fs/promises";
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 var NO_AGENTS_HINT = "No project sub-agents found in `.claude/agents/`. Add a `*.md` file with `name` + `description` frontmatter \u2014 see the 1926-Census marketing sub-agent for a reference implementation.";
 function parseAgentFrontmatter(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -28503,7 +29039,7 @@ function parseAgentFrontmatter(content) {
   return { name: nameMatch?.[1].trim(), description };
 }
 async function listAgents(projectRoot) {
-  const agentsDir = join16(projectRoot, ".claude", "agents");
+  const agentsDir = join17(projectRoot, ".claude", "agents");
   let files;
   try {
     files = await readdir2(agentsDir);
@@ -28514,7 +29050,7 @@ async function listAgents(projectRoot) {
   for (const file of files.filter((f) => f.endsWith(".md"))) {
     let content;
     try {
-      content = await readFile7(join16(agentsDir, file), "utf-8");
+      content = await readFile7(join17(agentsDir, file), "utf-8");
     } catch {
       continue;
     }
@@ -28522,7 +29058,7 @@ async function listAgents(projectRoot) {
     agents.push({
       name: meta?.name ?? file.replace(/\.md$/, ""),
       description: meta?.description ?? "",
-      path: join16(".claude", "agents", file)
+      path: join17(".claude", "agents", file)
     });
   }
   agents.sort((a, b2) => a.name.localeCompare(b2.name));
@@ -28663,8 +29199,8 @@ async function verifyProject(adapter2) {
 // src/tools/orient.ts
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync6, existsSync as existsSync11 } from "fs";
-import { join as join17 } from "path";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync7, existsSync as existsSync11 } from "fs";
+import { join as join18 } from "path";
 
 // src/lib/exit-criteria-evaluators.ts
 var TEST_ACCOUNT_PATTERN = "ftue-%@test.papi.dev";
@@ -28720,6 +29256,7 @@ var UNEVALUATABLE = {
   "c596a082-9ad3-4089-b497-46cd189e892b": "threshold is provisional pending an owner ruling \u2014 no settled bar to evaluate against"
 };
 async function evaluateExitCriteria(adapter2, projectId, criteria) {
+  const hasProject = typeof projectId === "string" && projectId.trim() !== "";
   return Promise.all(criteria.map(async (c) => {
     const evaluator = EVALUATORS[c.id];
     if (!evaluator) {
@@ -28727,6 +29264,14 @@ async function evaluateExitCriteria(adapter2, projectId, criteria) {
       if (!reason) return { ...c, met: c.met, autoEvaluated: false };
       return c.met ? { ...c, met: true, autoEvaluated: false } : { ...c, met: null, unevaluatedReason: reason, autoEvaluated: false };
     }
+    if (!hasProject) {
+      return {
+        ...c,
+        met: c.met ? true : null,
+        unevaluatedReason: "project id unavailable \u2014 this criterion is measured against a specific project and orient could not resolve one",
+        autoEvaluated: false
+      };
+    }
     try {
       const result = await evaluator(adapter2, projectId);
       return {
@@ -28737,10 +29282,11 @@ async function evaluateExitCriteria(adapter2, projectId, criteria) {
         autoEvaluated: result.met !== null
       };
     } catch (err) {
+      console.error(`[exit-criteria] evaluator for criterion ${c.id} threw:`, err);
       return {
         ...c,
         met: c.met ? true : null,
-        unevaluatedReason: `evaluator failed: ${err instanceof Error ? err.message : String(err)}`,
+        unevaluatedReason: "evaluator failed \u2014 see server logs. The stored value is shown and is unverified.",
         autoEvaluated: false
       };
     }
@@ -29119,9 +29665,13 @@ async function getHierarchyPosition(adapter2, projectId) {
       // task-3008: EVALUATE rather than read the hand-ticked boolean. Best-effort —
       // a failing evaluator degrades that criterion to unevaluated and leaves the
       // rest intact, because orient is the first call of every session.
+      // task-3226: pass the id THROUGH, undefined and all. This used to coerce to
+      // `''`, which is not a uuid and blew up every SQL-backed evaluator — the
+      // coercion looked like a safe default and was the bug. evaluateExitCriteria
+      // now reports "project id unavailable" for that case, which is the truth.
       stageExitCriteria: await evaluateExitCriteria(
         adapter2,
-        projectId ?? "",
+        projectId,
         activeStage.exitCriteria ?? []
       ).catch(() => (activeStage.exitCriteria ?? []).map((c) => ({ ...c, autoEvaluated: false })))
     };
@@ -29129,21 +29679,10 @@ async function getHierarchyPosition(adapter2, projectId) {
     return void 0;
   }
 }
-async function getLatestGitTag(projectRoot) {
-  try {
-    const { stdout } = await execFileAsync2("git", ["describe", "--tags", "--abbrev=0"], {
-      encoding: "utf-8",
-      cwd: projectRoot,
-      timeout: 2e3
-    });
-    return stdout.trim() || null;
-  } catch {
-    return null;
-  }
-}
+var GIT_TAG_TIMEOUT_MS = 2e3;
 async function checkNpmVersionDrift() {
   try {
-    const pkgPath = join17(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
+    const pkgPath = join18(new URL(".", import.meta.url).pathname, "..", "..", "package.json");
     const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
     const localVersion = pkg.version;
     const packageName = pkg.name;
@@ -29486,7 +30025,7 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       // Latest git tag + npm version drift (both exec calls with own timeouts).
       // task-2172: git-tag stays (the latest tag is part of the core summary);
       // version-drift is enrichment, gated behind `full`/deep_housekeeping.
-      tracked("git-tag", () => getLatestGitTag(config2.projectRoot)),
+      tracked("git-tag", async () => getLatestTag(config2.projectRoot, GIT_TAG_TIMEOUT_MS)),
       tracked("npm-version-drift", async () => fullEnrichment ? checkNpmVersionDrift() : void 0),
       // Research Signals — research docs with pending actions since last strategy review.
       // task-2172: heavy (doc search + AD cross-reference) and rarely actioned
@@ -29844,7 +30383,7 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
 
 \u{1F4DD} **CLAUDE.md enriched** \u2014 added ${tierNames2.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
   }
-  const claudeMdPath = join17(projectRoot, "CLAUDE.md");
+  const claudeMdPath = join18(projectRoot, "CLAUDE.md");
   if (!existsSync11(claudeMdPath)) return "";
   const content = readFileSync11(claudeMdPath, "utf-8");
   const additions = [];
@@ -29855,7 +30394,7 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
     additions.push(dedupeEnrichmentBlob(content, CLAUDE_MD_TIER_2));
   }
   if (additions.length === 0) return "";
-  writeFileSync6(claudeMdPath, content + additions.join(""), "utf-8");
+  writeFileSync7(claudeMdPath, content + additions.join(""), "utf-8");
   const tierNames = [];
   if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1))) tierNames.push("Established (batch building, strategy reviews, AD lifecycle)");
   if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T2))) tierNames.push("Mature (idea pipeline, doc registry, advanced patterns)");
@@ -30377,6 +30916,10 @@ var zoomOutTool = {
         enum: ["prepare", "apply"],
         description: '"prepare" returns the retrospective prompt. "apply" accepts your output. Defaults to "prepare" when omitted.'
       },
+      llm_response_file: {
+        type: "string",
+        description: 'Absolute path to a file containing the zoom-out output (mode "apply" only). LOCAL stdio servers only \u2014 on the hosted connection the server cannot read files on your machine. Use when the response is too large to pass inline (some hosts cap tool inputs around 50KB). Mutually exclusive with llm_response.'
+      },
       llm_response: {
         type: "string",
         description: 'Your raw output from executing the retrospective prompt (mode "apply" only).'
@@ -30398,10 +30941,12 @@ async function handleZoomOut(adapter2, config2, args) {
   const toolMode = args.mode;
   try {
     if (toolMode === "apply") {
-      const llmResponse = args.llm_response;
-      if (!llmResponse || !llmResponse.trim()) {
-        return errorResponse('llm_response is required for mode "apply".');
-      }
+      const resolved = await resolveLlmResponse(
+        args.llm_response,
+        args.llm_response_file
+      );
+      if (!resolved.ok) return errorResponse(resolved.error);
+      const llmResponse = resolved.llmResponse;
       const cycleNumber = typeof args.cycle_number === "number" ? args.cycle_number : 0;
       const result = await applyZoomOut(adapter2, llmResponse, cycleNumber);
       return textResponse(
@@ -30416,16 +30961,8 @@ Retrospective saved. Use insights to inform your next \`strategy_review\` or \`p
     }
     {
       const result = await prepareZoomOut(adapter2, config2.projectRoot);
-      const autoDispatchEnabled = process.env.PAPI_AUTO_DISPATCH !== "false";
-      const autoDispatchThreshold = 50 * 1024;
-      let dispatch;
-      if (args.dispatch === "inline" || args.dispatch === "subagent") {
-        dispatch = args.dispatch;
-      } else if (autoDispatchEnabled && result.contextBytes > autoDispatchThreshold) {
-        dispatch = "subagent";
-      } else {
-        dispatch = "inline";
-      }
+      const explicit = args.dispatch === "inline" ? false : args.dispatch === "subagent" ? true : void 0;
+      const dispatch = shouldDispatch(result.contextBytes, explicit) ? "subagent" : "inline";
       if (dispatch === "subagent") {
         const dispatchPrompt = buildSubagentDispatchPrompt({
           tool: "zoom_out",
@@ -30670,8 +31207,8 @@ ${result.userMessage}
 import { readFileSync as readFileSync12, statSync as statSync7 } from "fs";
 
 // src/services/scope-brief.ts
-import { writeFileSync as writeFileSync7, mkdirSync as mkdirSync5 } from "fs";
-import { join as join18, dirname as dirname5 } from "path";
+import { writeFileSync as writeFileSync8, mkdirSync as mkdirSync5 } from "fs";
+import { join as join19, dirname as dirname5 } from "path";
 var SCOPE_BRIEF_SYSTEM = `You are a technical scoping tool. You receive a brief-class task (too large to build directly) and decompose it into a structured scope document.
 
 A scope document must:
@@ -30728,14 +31265,14 @@ async function applyScopeBrief(adapter2, input) {
   }
   const slug = input.taskId.replace(/[^a-z0-9-]/g, "-").toLowerCase();
   const relPath = `docs/scopes/${slug}.md`;
-  const absPath = join18(input.projectRoot, relPath);
+  const absPath = join19(input.projectRoot, relPath);
   const docBody = addFrontmatter(docContent, task, input.cycleNumber);
   const collector = new FileWriteCollector();
   if (input.adapterType === "proxy") {
     collector.add({ path: relPath, content: docBody, mode: "overwrite" });
   } else {
     mkdirSync5(dirname5(absPath), { recursive: true });
-    writeFileSync7(absPath, docBody, "utf-8");
+    writeFileSync8(absPath, docBody, "utf-8");
   }
   const taskCount = countSubTasks(docContent);
   const summary = buildSummary(task, taskCount);
@@ -31022,7 +31559,7 @@ ${formatted}`, meta));
 
 // src/lib/dist-staleness.ts
 import { readFileSync as readFileSync13, statSync as statSync8 } from "fs";
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var BOOT_MS = Date.now();
 var DEFAULT_SKEW_MS = 2e3;
@@ -31036,7 +31573,7 @@ var SELF_PATH = (() => {
 })();
 function hashFile(path7) {
   try {
-    return createHash5("sha256").update(readFileSync13(path7)).digest("hex");
+    return createHash6("sha256").update(readFileSync13(path7)).digest("hex");
   } catch {
     return null;
   }
@@ -31686,19 +32223,19 @@ Its build reports, comments, and history moved with it; the cycle assignment was
 
 // src/services/harness-inventory.ts
 import { readdir as readdir3, readFile as readFile8, stat as stat3 } from "fs/promises";
-import { join as join19 } from "path";
-import { createHash as createHash6 } from "crypto";
+import { join as join20 } from "path";
+import { createHash as createHash7 } from "crypto";
 var RECOMMENDED_HOOKS = ["stop-release-check.sh", "claude-md-size-guard.sh"];
 async function computeFingerprint(root) {
   const parts = [];
   for (const sub of [".claude/skills", ".claude/agents", ".claude/hooks"]) {
-    const dir = join19(root, sub);
+    const dir = join20(root, sub);
     try {
       const names = (await readdir3(dir)).sort((a, b2) => a.localeCompare(b2));
       for (const name of names) {
         let mtime = "";
         try {
-          mtime = String(Math.floor((await stat3(join19(dir, name))).mtimeMs));
+          mtime = String(Math.floor((await stat3(join20(dir, name))).mtimeMs));
         } catch {
         }
         parts.push(`${sub}/${name}:${mtime}`);
@@ -31713,11 +32250,11 @@ async function computeFingerprint(root) {
   } catch {
     parts.push("manifest:none");
   }
-  return createHash6("sha256").update(parts.join("|")).digest("hex").slice(0, 16);
+  return createHash7("sha256").update(parts.join("|")).digest("hex").slice(0, 16);
 }
 async function readSkillDescription(skillDir) {
   try {
-    const content = await readFile8(join19(skillDir, "SKILL.md"), "utf-8");
+    const content = await readFile8(join20(skillDir, "SKILL.md"), "utf-8");
     const fm = content.match(/^---\n([\s\S]*?)\n---/);
     if (!fm) return void 0;
     const desc = fm[1].match(/^description:\s*[>|]?\s*\n?([\s\S]*?)(?=\n\w+:|\n---|$)/m);
@@ -31737,17 +32274,17 @@ async function scanInventory(root, toolDefs) {
     version = loadManifest().packageVersion;
   } catch {
   }
-  const skillsDir = join19(root, ".claude", "skills");
+  const skillsDir = join20(root, ".claude", "skills");
   try {
     const dirents = await readdir3(skillsDir, { withFileTypes: true });
     for (const d of dirents.filter((e) => e.isDirectory())) {
       entries.push({
         kind: "skill",
         name: d.name,
-        description: await readSkillDescription(join19(skillsDir, d.name)),
+        description: await readSkillDescription(join20(skillsDir, d.name)),
         version,
         status: stale.has(d.name) ? "stale_fork" : "ok",
-        path: join19(".claude", "skills", d.name)
+        path: join20(".claude", "skills", d.name)
       });
     }
   } catch {
@@ -31763,9 +32300,9 @@ async function scanInventory(root, toolDefs) {
   }
   const present = /* @__PURE__ */ new Set();
   try {
-    for (const f of (await readdir3(join19(root, ".claude", "hooks"))).filter((n) => n.endsWith(".sh"))) {
+    for (const f of (await readdir3(join20(root, ".claude", "hooks"))).filter((n) => n.endsWith(".sh"))) {
       present.add(f);
-      entries.push({ kind: "hook", name: f, status: "ok", path: join19(".claude", "hooks", f) });
+      entries.push({ kind: "hook", name: f, status: "ok", path: join20(".claude", "hooks", f) });
     }
   } catch {
   }
@@ -32045,6 +32582,7 @@ If this is legitimate, reach out at https://getpapi.ai and we'll lift it \u2014
 }
 
 // src/server.ts
+var mdModeWarned = false;
 var DEFAULT_TOOL_TIMEOUT_MS = parseInt(process.env.PAPI_TOOL_TIMEOUT_MS ?? "30000", 10);
 var LONG_TOOL_TIMEOUT_MS = parseInt(process.env.PAPI_LONG_TOOL_TIMEOUT_MS ?? "180000", 10);
 var WEDGE_PENDING_FRACTION = Math.min(1, Math.max(0, parseFloat(process.env.PAPI_WEDGE_PENDING_FRACTION ?? "0.6")));
@@ -32210,7 +32748,7 @@ function createServer(adapter2, config2) {
   const __pkgDir = dirname6(__pkgFilename);
   let serverVersion = "unknown";
   try {
-    const pkg = JSON.parse(readFileSync14(join20(__pkgDir, "..", "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync14(join21(__pkgDir, "..", "package.json"), "utf-8"));
     serverVersion = pkg.version ?? "unknown";
   } catch {
   }
@@ -32221,14 +32759,15 @@ function createServer(adapter2, config2) {
     // task-1801: `resources` capability for the PAPI read surface exposed as MCP resources.
     { capabilities: { tools: {}, prompts: {}, resources: {} }, instructions: UNIVERSAL_FRAME }
   );
-  if (config2.adapterType === "md") {
+  if (config2.adapterType === "md" && !mdModeWarned) {
+    mdModeWarned = true;
     process.stderr.write(
       "\n\u26A0 PAPI is running in md mode \u2014 your cycles are not visible on the hosted dashboard.\n  Configure DATABASE_URL or sign up at https://getpapi.ai/setup to enable observability.\n\n"
     );
   }
   const __filename = fileURLToPath4(import.meta.url);
   const __dirname2 = dirname6(__filename);
-  const skillsDir = join20(__dirname2, "..", "skills");
+  const skillsDir = join21(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match) return null;
@@ -32246,7 +32785,7 @@ function createServer(adapter2, config2) {
       const mdFiles = files.filter((f) => f.endsWith(".md"));
       const prompts = [];
       for (const file of mdFiles) {
-        const content = await readFile9(join20(skillsDir, file), "utf-8");
+        const content = await readFile9(join21(skillsDir, file), "utf-8");
         const meta = parseSkillFrontmatter(content);
         if (meta) {
           prompts.push({ name: meta.name, description: meta.description });
@@ -32262,7 +32801,7 @@ function createServer(adapter2, config2) {
     try {
       const files = await readdir4(skillsDir);
       for (const file of files.filter((f) => f.endsWith(".md"))) {
-        const content = await readFile9(join20(skillsDir, file), "utf-8");
+        const content = await readFile9(join21(skillsDir, file), "utf-8");
         const meta = parseSkillFrontmatter(content);
         if (meta?.name === name) {
           const body = content.replace(/^---\n[\s\S]*?\n---\n*/, "");
@@ -32548,6 +33087,7 @@ ${usageLine(decision.usage)}`;
 // src/transport-http.ts
 init_proxy_adapter();
 import { createServer as createHttpServer } from "http";
+import { createHash as createHash8 } from "crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 var BEARER_PREFIX = "papi_";
 var BEARER_REGEX = /^(papi_|papi_oauth_)[a-f0-9]{64}$/;
@@ -32577,6 +33117,7 @@ var FRIENDLY_GET_HTML = `<!doctype html>
      <code>https://mcp.getpapi.ai/mcp</code>.</p>
   <a class="btn" href="https://getpapi.ai/docs/install">See the install guide \u2192</a>
 </div></body></html>`;
+var KNOWN_INSTALL_CLIENTS = /* @__PURE__ */ new Set(["claude-code-plugin"]);
 var MAX_BODY_BYTES = 1 * 1024 * 1024;
 var IP_RATE_WINDOW_MS = 6e4;
 var IP_RATE_MAX = 60;
@@ -32615,7 +33156,7 @@ function corsHeaders(origin) {
   return {
     "Access-Control-Allow-Origin": origin,
     "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Authorization, Content-Type, x-papi-project-id",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type, x-papi-project-id, x-papi-client",
     "Vary": "Origin"
   };
 }
@@ -32657,6 +33198,48 @@ function sendError(res, err, extraHeaders = {}) {
   });
   res.end(JSON.stringify(err.body));
 }
+function sendUnauthorized(res, reason, extraHeaders = {}) {
+  const challenge = reason === "invalid_token" ? `Bearer realm="papi", error="invalid_token", error_description="The access token was rejected: it has been revoked or has expired.", resource_metadata="${RESOURCE_METADATA_URL}"` : `Bearer realm="papi", resource_metadata="${RESOURCE_METADATA_URL}"`;
+  sendError(
+    res,
+    { status: 401, body: { error: "Unauthorized", reason } },
+    { ...extraHeaders, "WWW-Authenticate": challenge }
+  );
+}
+var AUTH_VALID_TTL_MS = 5 * 6e4;
+var AUTH_REJECTED_TTL_MS = 6e4;
+var AUTH_CACHE_MAX = 5e3;
+var authVerdicts = /* @__PURE__ */ new Map();
+function bearerKey(bearer) {
+  return createHash8("sha256").update(bearer).digest("hex");
+}
+function readAuthVerdict(bearer, now = Date.now()) {
+  const hit = authVerdicts.get(bearerKey(bearer));
+  if (!hit) return void 0;
+  if (hit.expires <= now) {
+    authVerdicts.delete(bearerKey(bearer));
+    return void 0;
+  }
+  return hit.verdict;
+}
+function recordAuthVerdict(bearer, verdict, now = Date.now()) {
+  if (authVerdicts.size >= AUTH_CACHE_MAX) {
+    for (const [k, v] of authVerdicts) {
+      if (v.expires <= now) authVerdicts.delete(k);
+    }
+    if (authVerdicts.size >= AUTH_CACHE_MAX) {
+      const oldest = authVerdicts.keys().next();
+      if (!oldest.done) authVerdicts.delete(oldest.value);
+    }
+  }
+  const ttl = verdict === "valid" ? AUTH_VALID_TTL_MS : AUTH_REJECTED_TTL_MS;
+  authVerdicts.set(bearerKey(bearer), { verdict, expires: now + ttl });
+}
+function classifyAuthProbeStatus(status) {
+  if (status === 401) return "rejected";
+  if (status >= 200 && status < 300) return "valid";
+  return void 0;
+}
 function startHttpTransport(opts) {
   const { port, host, baseConfig, pkgVersion: pkgVersion2, dataEndpoint } = opts;
   const httpServer = createHttpServer((req, res) => {
@@ -32758,21 +33341,11 @@ function startHttpTransport(opts) {
         ip,
         status: 401
       });
-      sendError(
-        res,
-        {
-          status: 401,
-          body: {
-            error: "Unauthorized",
-            reason: hasHeader ? "malformed_bearer" : "missing_bearer"
-          }
-        },
-        {
-          "WWW-Authenticate": `Bearer realm="papi", resource_metadata="${RESOURCE_METADATA_URL}"`
-        }
-      );
+      sendUnauthorized(res, hasHeader ? "malformed_bearer" : "missing_bearer");
       return;
     }
+    const clientHeader = req.headers["x-papi-client"];
+    const installClient = typeof clientHeader === "string" && KNOWN_INSTALL_CLIENTS.has(clientHeader) ? clientHeader : "direct";
     const projectIdHeader = req.headers["x-papi-project-id"];
     const projectId = typeof projectIdHeader === "string" && projectIdHeader.length > 0 ? projectIdHeader : void 0;
     if (req.method !== "POST" && req.method !== "GET") {
@@ -32815,6 +33388,13 @@ function startHttpTransport(opts) {
           return;
         }
       }
+      logEvent({
+        level: "info",
+        msg: "mcp_request",
+        ip,
+        bearer_prefix: bearerPrefix(bearer),
+        install_client: installClient
+      });
       void dispatchRequest({
         req,
         res,
@@ -32895,6 +33475,18 @@ Example: add \`project="${projects[0].slug}"\` to the tool arguments.`;
   res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders(origin) });
   res.end(JSON.stringify(payload));
 }
+function sendProjectUnverifiable(res, origin, body) {
+  if (res.headersSent) return;
+  const id = (body && typeof body === "object" ? body.id : null) ?? null;
+  const text = 'PAPI couldn\'t verify which project this call belongs to \u2014 the project lookup failed, so it is stopping rather than guessing and writing to the wrong project.\n\nRetry in a moment. If it keeps happening, name the project explicitly with `project="<slug>"` in the tool arguments, or set the x-papi-project-id header.';
+  const payload = {
+    jsonrpc: "2.0",
+    id,
+    result: { content: [{ type: "text", text }], isError: true }
+  };
+  res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders(origin) });
+  res.end(JSON.stringify(payload));
+}
 function resolveEffectiveProjectId(body, headerProjectId) {
   const explicitProject = extractProjectOverride(body);
   try {
@@ -32904,17 +33496,59 @@ function resolveEffectiveProjectId(body, headerProjectId) {
     throw err;
   }
 }
+async function resolveAuthVerdict(bearer, dataEndpoint) {
+  const cached2 = readAuthVerdict(bearer);
+  if (cached2) return cached2;
+  const probe = new ProxyPapiAdapter({ endpoint: dataEndpoint, apiKey: bearer });
+  const verdict = classifyAuthProbeStatus(await probe.probeBearerStatus());
+  if (verdict) recordAuthVerdict(bearer, verdict);
+  return verdict;
+}
 async function dispatchRequest(args) {
   const { req, res, body, bearer, projectId, ip, baseConfig, dataEndpoint } = args;
+  const calledTool = extractToolName(body);
+  if (calledTool !== void 0) {
+    const authVerdict = await resolveAuthVerdict(bearer, dataEndpoint);
+    if (authVerdict === "rejected") {
+      logEvent({
+        level: "warn",
+        msg: "auth_revoked",
+        ip,
+        bearer_prefix: bearerPrefix(bearer),
+        status: 401,
+        reason: "proxy_rejected_bearer"
+      });
+      if (!res.headersSent) {
+        sendUnauthorized(res, "invalid_token", corsHeaders(req.headers.origin));
+      }
+      return;
+    }
+  }
   let effectiveProjectId = resolveEffectiveProjectId(body, projectId);
   if (effectiveProjectId === void 0) {
-    const toolName = extractToolName(body);
+    const toolName = calledTool;
     if (toolName && !PROJECT_OPTIONAL_TOOLS.has(toolName)) {
       let projects = [];
+      let probeFailed = false;
       try {
-        const probe = new ProxyPapiAdapter({ endpoint: dataEndpoint, apiKey: bearer });
+        const probe = new ProxyPapiAdapter({
+          endpoint: dataEndpoint,
+          apiKey: bearer,
+          onAuthRejected: () => recordAuthVerdict(bearer, "rejected")
+        });
         projects = await probe.listUserProjects();
       } catch {
+        probeFailed = true;
+      }
+      if (probeFailed) {
+        logEvent({
+          level: "warn",
+          msg: "project_probe_failed",
+          ip,
+          bearer_prefix: bearerPrefix(bearer)
+        });
+        sendProjectUnverifiable(res, req.headers.origin, body);
+        return;
       }
       if (projects.length === 1) {
         effectiveProjectId = projects[0].id;
@@ -32937,10 +33571,14 @@ async function dispatchRequest(args) {
       }
     }
   }
-  const adapter2 = new ProxyPapiAdapter({
+  const adapter2 = createProxyAdapter({
     endpoint: dataEndpoint,
     apiKey: bearer,
-    projectId: effectiveProjectId
+    projectId: effectiveProjectId,
+    // task-1773: a 401 raised mid-tool-call cannot change THIS response — the MCP
+    // transport already owns it — but it marks the bearer so the very next request
+    // short-circuits to a 401 + WWW-Authenticate and the client re-authenticates.
+    onAuthRejected: () => recordAuthVerdict(bearer, "rejected")
   });
   const requestConfig = {
     ...baseConfig,
@@ -32988,7 +33626,7 @@ async function dispatchRequest(args) {
 var __dirname = dirname7(fileURLToPath5(import.meta.url));
 var pkgVersion = "unknown";
 try {
-  const pkg = JSON.parse(readFileSync19(join25(__dirname, "..", "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync19(join26(__dirname, "..", "package.json"), "utf-8"));
   pkgVersion = pkg.version;
 } catch {
 }