@papi-ai/server 0.7.76 → 0.7.78

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, {
@@ -1353,6 +1361,14 @@ var init_proxy_adapter = __esm({
       // (1) local-only
       "close",
       "initRls",
+      // task-3207 (C357): commitBuildComplete, commitReviewSubmit, commitRelease have no
+      // edge case handler and no ALLOWED_METHODS entry — forwarding them 403s at the edge
+      // with no try/catch at the call site, crashing build_execute/review_submit/release
+      // completion for every hosted user. Restores the intended graceful degradation
+      // (separate appendBuildReport + updateTaskStatus calls) until they're atomically wired.
+      "commitBuildComplete",
+      "commitReviewSubmit",
+      "commitRelease",
       // (2) not-yet-wired hosted gaps — shrink as data-proxy handlers land (task-2390).
       // getToolCallCount + updatePhaseStatus are ABSENT: they now have edge handlers and
       // are served through the forwarder (getToolCallCount = SUP-2026-026 handler #1).
@@ -1398,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() {
@@ -1418,7 +1463,8 @@ var init_proxy_adapter = __esm({
         return wrapWithForwarding(new _ProxyPapiAdapter({
           endpoint: this.endpoint,
           apiKey: this.apiKey,
-          projectId
+          projectId,
+          onAuthRejected: this.onAuthRejected
         }));
       }
       /**
@@ -1505,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.
@@ -2083,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();
@@ -2200,7 +2248,7 @@ var init_reap_orphans = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/query.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/query.js
 function cachedError(xs) {
   if (originCache.has(xs))
     return originCache.get(xs);
@@ -2212,7 +2260,7 @@ function cachedError(xs) {
 }
 var originCache, originStackCache, originError, CLOSE, Query;
 var init_query = __esm({
-  "../../node_modules/postgres/src/query.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/query.js"() {
     "use strict";
     originCache = /* @__PURE__ */ new Map();
     originStackCache = /* @__PURE__ */ new Map();
@@ -2343,7 +2391,7 @@ var init_query = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/errors.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/errors.js
 function connection(x, options, socket) {
   const { host, port } = socket || options;
   const error = Object.assign(
@@ -2381,7 +2429,7 @@ function notSupported(x) {
 }
 var PostgresError, Errors;
 var init_errors = __esm({
-  "../../node_modules/postgres/src/errors.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/errors.js"() {
     "use strict";
     PostgresError = class extends Error {
       constructor(x) {
@@ -2399,7 +2447,7 @@ var init_errors = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/types.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/types.js
 function handleValue(x, parameters, types2, options) {
   let value = x instanceof Parameter ? x.value : x;
   if (value === void 0) {
@@ -2514,7 +2562,7 @@ function createJsonTransform(fn) {
 }
 var types, NotTagged, Identifier, Parameter, Builder, defaultHandlers, builders, serializers, parsers, mergeUserTypes, escapeIdentifier, inferType, escapeBackslash, escapeQuote, arraySerializer, arrayParserState, arrayParser, toCamel, toPascal, toKebab, fromCamel, fromPascal, fromKebab, camel, pascal, kebab;
 var init_types = __esm({
-  "../../node_modules/postgres/src/types.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/types.js"() {
     "use strict";
     init_query();
     init_errors();
@@ -2693,10 +2741,10 @@ var init_types = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/result.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/result.js
 var Result;
 var init_result = __esm({
-  "../../node_modules/postgres/src/result.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/result.js"() {
     "use strict";
     Result = class extends Array {
       constructor() {
@@ -2716,7 +2764,7 @@ var init_result = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/queue.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/queue.js
 function Queue(initial = []) {
   let xs = initial.slice();
   let index = 0;
@@ -2743,13 +2791,13 @@ function Queue(initial = []) {
 }
 var queue_default;
 var init_queue = __esm({
-  "../../node_modules/postgres/src/queue.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/queue.js"() {
     "use strict";
     queue_default = Queue;
   }
 });
 
-// ../../node_modules/postgres/src/bytes.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/bytes.js
 function fit(x) {
   if (buffer.length - b.i < x) {
     const prev = buffer, length = prev.length;
@@ -2763,7 +2811,7 @@ function reset() {
 }
 var size, buffer, messages, b, bytes_default;
 var init_bytes = __esm({
-  "../../node_modules/postgres/src/bytes.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/bytes.js"() {
     "use strict";
     size = 256;
     buffer = Buffer.allocUnsafe(size);
@@ -2828,7 +2876,7 @@ var init_bytes = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/connection.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/connection.js
 import net from "net";
 import tls from "tls";
 import crypto2 from "crypto";
@@ -3622,7 +3670,7 @@ function timer(fn, seconds) {
 }
 var connection_default, uid, Sync, Flush, SSLRequest, ExecuteUnnamed, DescribeUnnamed, noop, retryRoutines, errorFields;
 var init_connection = __esm({
-  "../../node_modules/postgres/src/connection.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/connection.js"() {
     "use strict";
     init_types();
     init_errors();
@@ -3685,7 +3733,7 @@ var init_connection = __esm({
   }
 });
 
-// ../../node_modules/postgres/src/subscribe.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/subscribe.js
 function Subscribe(postgres2, options) {
   const subscribers = /* @__PURE__ */ new Map(), slot = "postgresjs_" + Math.random().toString(36).slice(2), state = {};
   let connection2, stream, ended = false;
@@ -3896,14 +3944,14 @@ function parseEvent(x) {
 }
 var noop2;
 var init_subscribe = __esm({
-  "../../node_modules/postgres/src/subscribe.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/subscribe.js"() {
     "use strict";
     noop2 = () => {
     };
   }
 });
 
-// ../../node_modules/postgres/src/large.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/large.js
 import Stream2 from "stream";
 function largeObject(sql, oid, mode = 131072 | 262144) {
   return new Promise(async (resolve4, reject) => {
@@ -3969,12 +4017,12 @@ function largeObject(sql, oid, mode = 131072 | 262144) {
   });
 }
 var init_large = __esm({
-  "../../node_modules/postgres/src/large.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/large.js"() {
     "use strict";
   }
 });
 
-// ../../node_modules/postgres/src/index.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/index.js
 var src_exports = {};
 __export(src_exports, {
   default: () => src_default
@@ -4364,7 +4412,7 @@ function osUsername() {
 }
 var src_default;
 var init_src = __esm({
-  "../../node_modules/postgres/src/index.js"() {
+  "../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/node_modules/postgres/src/index.js"() {
     "use strict";
     init_types();
     init_connection();
@@ -5259,6 +5307,15 @@ var HELP_FOOTER_MD = `
 var STRATEGY_REVIEW_OFFER_GAP = 5;
 var STRATEGY_REVIEW_BLOCK_GAP = 7;
 var ZOOM_OUT_OFFER_GAP = 25;
+function isDatabaseBackedAdapter(known) {
+  if (known) return known === "pg" || known === "proxy";
+  try {
+    const { adapterType } = loadConfig();
+    return adapterType === "pg" || adapterType === "proxy";
+  } catch {
+    return process.env.PAPI_ADAPTER !== "md";
+  }
+}
 function loadConfig() {
   const projectArgIdx = process.argv.indexOf("--project");
   const configuredRoot = projectArgIdx !== -1 ? process.argv[projectArgIdx + 1] : process.env.PAPI_PROJECT_DIR;
@@ -5368,7 +5425,7 @@ Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env con
 import path3 from "path";
 import { execSync } from "child_process";
 
-// ../adapter-md/dist/index.js
+// ../../../../../Users/cathaloullivan/Ai-App-Projects/PapiUI/packages/adapter-md/dist/index.js
 import { readFile, writeFile, access } from "fs/promises";
 import { randomUUID as randomUUID6 } from "crypto";
 import { join } from "path";
@@ -5630,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"
@@ -5671,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;
@@ -6321,9 +6381,59 @@ 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) ?? [];
+    group.push(r);
+    perCycle.set(r.cycle, group);
+  }
+  const accuracy = [];
+  const velocity = [];
+  const sortedCycles = [...perCycle.keys()].sort((a, b2) => a - b2);
+  for (const cycle of sortedCycles) {
+    const reps = perCycle.get(cycle);
+    const deltas = [];
+    for (const r of reps) {
+      const actual = effortOrdinal(r.actualEffort);
+      const estimated = effortOrdinal(r.estimatedEffort);
+      if (actual !== void 0 && estimated !== void 0) {
+        deltas.push(actual - estimated);
+      }
+    }
+    if (deltas.length > 0) {
+      accuracy.push({
+        cycle,
+        reports: deltas.length,
+        matchRate: Math.round(deltas.filter((d) => d === 0).length / deltas.length * 100),
+        mae: Math.round(deltas.reduce((s, d) => s + Math.abs(d), 0) / deltas.length * 10) / 10,
+        bias: Math.round(deltas.reduce((s, d) => s + d, 0) / deltas.length * 10) / 10
+      });
+    }
+    velocity.push({
+      cycle,
+      completed: reps.filter((r) => r.completed === "Yes").length,
+      partial: reps.filter((r) => r.completed === "Partial").length,
+      failed: reps.filter((r) => r.completed === "No").length,
+      effortPoints: reps.reduce((s, r) => s + (effortOrdinal(r.actualEffort) ?? 0), 0)
+    });
+  }
+  return { accuracy, velocity, unparsedEffortCount };
+}
 function serializeAccuracyRow(a) {
   return `| ${a.cycle} | ${a.reports} | ${a.matchRate}% | ${a.mae} | ${a.bias >= 0 ? "+" : ""}${a.bias} |`;
 }
@@ -7972,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;
@@ -8035,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);
@@ -8402,6 +8533,24 @@ function formatBuildReports(reports, opts) {
 _\u2026and ${reports.length - capped.length} older build report(s) omitted to bound context size._` : "";
   return body + omitted;
 }
+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 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 && !resolves.has(id)) mentions.add(id);
+  }
+  return { resolves: [...resolves].sort(), mentions: [...mentions].sort() };
+}
 function formatRecentlyShippedCapabilities(reports) {
   const completed = reports.filter((r) => r.completed === "Yes" || r.completed === "Partial");
   if (completed.length === 0) return void 0;
@@ -8416,13 +8565,63 @@ function formatRecentlyShippedCapabilities(reports) {
     }
     return parts.join("\n");
   });
-  return [
+  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) {
+    const { resolves, mentions } = extractTaskReferences(r);
+    for (const ref of resolves) {
+      if (completedIds.has(ref)) continue;
+      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:`,
     "",
     ...lines,
     "",
     "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."
-  ].join("\n");
+  ];
+  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 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(", ")}`)
+    );
+  }
+  return out.join("\n");
 }
 function formatCycleLog(entries) {
   if (entries.length === 0) return "No cycle log entries yet.";
@@ -8669,13 +8868,14 @@ function computeSnapshotsFromBuildReports(reports, tasks) {
     const cycleReports = reportsByCycle.get(sn) ?? [];
     const cycleTaskRows = tasksByCycle.get(sn);
     const withEffort = cycleReports.filter((r) => r.estimatedEffort && r.actualEffort);
-    const accurate = withEffort.filter((r) => r.estimatedEffort === r.actualEffort).length;
-    const matchRate = withEffort.length > 0 ? Math.round(accurate / withEffort.length * 100) : 0;
+    const [computedAccuracy] = calculateCycleMetrics(withEffort, sn, 1).accuracy;
     const { completed, total, plannedPoints, deliveredPoints } = computeCycleEffort(cycleTaskRows, cycleReports);
     snapshots.push({
       cycle: sn,
       date: (/* @__PURE__ */ new Date()).toISOString(),
-      accuracy: [{ cycle: sn, reports: cycleReports.length, matchRate, mae: 0, bias: 0 }],
+      // No report in this cycle carried BOTH an estimate and an actual, so there
+      // is genuinely nothing to measure. Zeros here mean "no data", not "no bias".
+      accuracy: [computedAccuracy ?? { cycle: sn, reports: 0, matchRate: 0, mae: 0, bias: 0 }],
       velocity: [{
         cycle: sn,
         completed,
@@ -9196,7 +9396,7 @@ var PLAN_FRAGMENT_RESEARCH = `
 var PLAN_FRAGMENT_BUG = `
    **Bug task detection:** When a task's task type is "bug" or the title starts with "Bug:" or "Fix:", apply these rules:
    - **Auto-P1:** If the task's current priority is P2 or lower, upgrade it to "P1 High" via a boardCorrections entry in Part 2. Note the upgrade in Part 1 analysis.
-   - Replace the standard SCOPE (DO THIS) section with bug-specific sections:
+   - Inside SCOPE (DO THIS), use these bug-specific subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
      - **REPRODUCE:** Exact steps to reproduce the bug before touching any code. If the task notes describe the symptoms, include them. If not, the first build step is "confirm the bug reproduces."
      - **ROOT CAUSE:** One-sentence hypothesis for the root cause (what is wrong, not what the user sees). The builder must confirm or correct this before implementing a fix.
      - **MINIMAL FIX:** The smallest code change that resolves the root cause. "Bug fix \u2014 minimal blast radius. Change only what is necessary. Do not refactor surrounding code or expand scope."
@@ -9221,7 +9421,7 @@ var PLAN_FRAGMENT_SPIKE = `
    - Keep SCOPE BOUNDARY, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    - Spikes should be estimated conservatively: XS or S. If a spike needs M+ effort, it's not a spike \u2014 reclassify as a research task.`;
 var PLAN_FRAGMENT_DESIGN_BRIEF = `
-   **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Replace the standard SCOPE (DO THIS) section with these type-specific sections:
+   **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Inside SCOPE (DO THIS), use these type-specific subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - AUDIENCE: Who this design is for \u2014 persona and context of use (e.g. "non-technical Owner, first dashboard visit")
    - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` (dev patterns, anti-patterns, component rules) AND \`docs/branding/brand-book.html\` (brand identity, positioning, voice canon) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
    - DELIVERABLE FORMAT: What the output looks like \u2014 design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
@@ -9229,7 +9429,7 @@ var PLAN_FRAGMENT_DESIGN_BRIEF = `
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Deliverable format confirmed with Owner before starting" and "[ ] Design output is self-contained \u2014 includes enough context for a developer to implement without further clarification."`;
 var PLAN_FRAGMENT_RESEARCH_BRIEF = `
-   **Research brief task detection:** When a task's task type is "research-brief", generate a RESEARCH BRIEF handoff. Replace the standard SCOPE (DO THIS) section with:
+   **Research brief task detection:** When a task's task type is "research-brief", generate a RESEARCH BRIEF handoff. Inside SCOPE (DO THIS), use these subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - GOAL: The specific question this research answers \u2014 one sentence, phrased as a question (e.g. "What onboarding patterns do our top 3 competitors use?")
    - TIME-BOX: Maximum effort allowed \u2014 XS or S. Stop when the time-box is hit and report what was found, even if incomplete.
    - OUTPUT: Where findings land \u2014 a doc at \`docs/research/[topic]-findings.md\` or inline in the build report. State the path.
@@ -9237,7 +9437,7 @@ var PLAN_FRAGMENT_RESEARCH_BRIEF = `
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Question answered OR time-box hit \u2014 whichever comes first" and "[ ] Findings doc saved before any follow-up tasks are submitted."`;
 var PLAN_FRAGMENT_MARKETING_BRIEF = `
-   **Marketing brief task detection:** When a task's task type is "marketing-brief", generate a MARKETING BRIEF handoff. Replace the standard SCOPE (DO THIS) section with:
+   **Marketing brief task detection:** When a task's task type is "marketing-brief", generate a MARKETING BRIEF handoff. Inside SCOPE (DO THIS), use these subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - AUDIENCE: Who this marketing content targets \u2014 persona, awareness level, channel context (e.g. "cold Discord visitor, zero PAPI context")
    - CHANNEL: Where this content lives \u2014 Discord, landing page, email, social, etc.
    - MESSAGE FRAME: The core message to land \u2014 one sentence. What does the reader need to believe after seeing this? (e.g. "PAPI makes AI-assisted building systematic, not chaotic.")
@@ -9245,7 +9445,7 @@ var PLAN_FRAGMENT_MARKETING_BRIEF = `
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION as normal.
    Add to ACCEPTANCE CRITERIA: "[ ] Message Frame confirmed with Owner before drafting" and "[ ] Final content reviewed by Owner before publishing."`;
 var PLAN_FRAGMENT_OPS_BRIEF = `
-   **Ops brief task detection:** When a task's task type is "ops-brief", generate an OPS BRIEF handoff. Replace the standard SCOPE (DO THIS) section with:
+   **Ops brief task detection:** When a task's task type is "ops-brief", generate an OPS BRIEF handoff. Inside SCOPE (DO THIS), use these subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - SYSTEM: Which system or service this ops task touches \u2014 Vercel, Railway, Supabase, GitHub Actions, DNS, etc.
    - RISK: What could go wrong \u2014 data loss, downtime, broken deployments. Include estimated blast radius (e.g. "affects all authenticated users").
    - ROLLBACK PLAN: Exact steps to undo the change if something breaks. Must be specific enough to execute under pressure.
@@ -9738,6 +9938,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;
@@ -9777,10 +9988,12 @@ 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);
   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),
@@ -10888,8 +11101,9 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false)
       }
       const invalidFields = validateHandoffScope(parsed);
       if (invalidFields.length > 0) {
+        const scopeMissing = invalidFields.includes("scope");
         warnings.push(
-          `Rejected handoff for ${handoff.taskId}: missing or empty ${invalidFields.join(", ")}. Handoffs without explicit scope produce ambiguous builds.`
+          `Rejected handoff for ${handoff.taskId}: missing or empty ${invalidFields.join(", ")}. Handoffs without explicit scope produce ambiguous builds.` + (scopeMissing ? ` If this is a bug/design-brief/research-brief/marketing-brief/ops-brief task, KEEP the "SCOPE (DO THIS)" header and nest the type-specific sections (REPRODUCE / ROOT CAUSE / MINIMAL FIX / \u2026) inside it \u2014 the parser only recognises the standard headers, so replacing SCOPE outright drops it entirely.` : "")
         );
         continue;
       }
@@ -12894,7 +13108,7 @@ async function assertSingleActiveCycle(adapter2, opts = {}) {
   }
   return notes;
 }
-async function validateAndPrepare(adapter2, force, callerUserId) {
+async function validateAndPrepare(adapter2, force, callerUserId, adapterType) {
   let mode;
   let cycleNumber;
   let strategyReviewWarning = "";
@@ -12956,7 +13170,7 @@ Run \`strategy_review\` first, or pass \`force: true\` to bypass this gate.`
     if (err instanceof Error && (err.message.startsWith("Strategy Review") || err.message.startsWith("Cycle ") || err.message.startsWith("Stale reviews"))) {
       throw err;
     }
-    const isPg = process.env.PAPI_ADAPTER === "pg" || process.env.PAPI_ADAPTER === "proxy";
+    const isPg = isDatabaseBackedAdapter(adapterType);
     throw new Error(
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
@@ -13000,8 +13214,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;
@@ -13074,7 +13289,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   tracker?.mark("validate_and_prepare");
   let t = startTimer();
   const prepareScope = await resolvePlanScope(adapter2, config2);
-  const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force, prepareScope.callerUserId);
+  const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force, prepareScope.callerUserId, config2.adapterType);
   const validateMs = t();
   const incomingCycle = cycleNumber + 1;
   tracker?.setStreamScope({ cycle: incomingCycle });
@@ -15683,6 +15898,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();
@@ -15724,34 +15998,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) {
@@ -16007,7 +16254,7 @@ async function prepareStrategyReview(adapter2, force, projectRoot, adapterType,
       };
     }
   } catch {
-    const isPg = process.env.PAPI_ADAPTER === "pg" || process.env.PAPI_ADAPTER === "proxy";
+    const isPg = isDatabaseBackedAdapter(adapterType);
     throw new Error(
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
@@ -16451,13 +16698,13 @@ ${cleanContent}`;
 ${evidenceWarnings.map((w) => `- ${w}`).join("\n")}` : displayText;
   return { cycleNumber, displayText: fullText, writeBackFailed };
 }
-async function prepareStrategyChange(adapter2, text) {
+async function prepareStrategyChange(adapter2, text, adapterType) {
   let cycleNumber;
   try {
     const health = await adapter2.getCycleHealth();
     cycleNumber = health.totalCycles;
   } catch {
-    const isPg = process.env.PAPI_ADAPTER === "pg" || process.env.PAPI_ADAPTER === "proxy";
+    const isPg = isDatabaseBackedAdapter(adapterType);
     throw new Error(
       isPg ? "Could not read cycle health from the database. Check your DATABASE_URL and verify the project exists." : "Could not read cycle health from PLANNING_LOG.md. Run setup first to initialise your PAPI project."
     );
@@ -16509,37 +16756,45 @@ async function prepareStrategyChange(adapter2, text) {
 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",
@@ -16548,18 +16803,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({
@@ -16580,11 +16883,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
@@ -16700,6 +17005,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.'
@@ -16933,19 +17242,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.`
       );
@@ -16976,7 +17290,7 @@ Decision event logged.`
       return errorResponse("text is required for strategy_change. Describe the strategic shift to apply.");
     }
     {
-      const result = await prepareStrategyChange(adapter2, text);
+      const result = await prepareStrategyChange(adapter2, text, _config.adapterType);
       return textResponse(
         `## PAPI Strategy Change \u2014 Prepare Phase (Cycle ${result.cycleNumber})
 
@@ -17056,8 +17370,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;
@@ -17411,6 +17725,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"]
@@ -17664,6 +17982,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) {
@@ -17691,7 +18017,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(
@@ -17710,7 +18036,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.`);
     }
@@ -17729,7 +18055,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}]`;
@@ -17754,7 +18080,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;
@@ -17766,25 +18092,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(", ")}`
     ];
@@ -18588,7 +18914,7 @@ 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",
+      content: JSON.stringify({ permissions: { allow: [...PAPI_PERMISSIONS] } }, null, 2) + "\n",
       mode: "create",
       skip_if_exists: true
     });
@@ -18597,7 +18923,7 @@ async function scaffoldPapiDir(adapter2, config2, input, collector) {
   }
   return true;
 }
-var PAPI_PERMISSION = "mcp__papi__*";
+var PAPI_PERMISSIONS = ["mcp__papi__*", "mcp__plugin_papi_papi__*"];
 async function ensurePapiPermission(projectRoot) {
   const settingsPath = join9(projectRoot, ".claude", "settings.json");
   try {
@@ -18615,8 +18941,10 @@ async function ensurePapiPermission(projectRoot) {
       perms.allow = [];
     }
     const allow = perms.allow;
-    if (!allow.includes(PAPI_PERMISSION)) {
-      allow.push(PAPI_PERMISSION);
+    for (const permission of PAPI_PERMISSIONS) {
+      if (!allow.includes(permission)) {
+        allow.push(permission);
+      }
     }
     await mkdir(join9(projectRoot, ".claude"), { recursive: true });
     await writeFile2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
@@ -21653,7 +21981,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);
@@ -21661,17 +21989,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;
@@ -21697,6 +22028,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).";
@@ -21710,7 +22052,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)).`;
 }
@@ -22754,9 +23098,19 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
           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 = [];
@@ -22940,7 +23294,7 @@ 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 },
@@ -22963,6 +23317,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;
@@ -23073,7 +23428,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"]
   }
@@ -23230,6 +23589,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,
@@ -23241,13 +23616,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,
@@ -23273,16 +23648,16 @@ async function handleDocRegister(adapter2, args, config2) {
       }
       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
@@ -23306,7 +23681,7 @@ ${decision.message}`;
       durability = "";
     }
     return textResponse(
-      `**Registered:** ${entry.title}
+      `**Registered:** ${entry.title}${overrideNote}
 - **Path:** ${entry.path}
 - **Type:** ${entry.type} | **Status:** ${entry.status}
 - **Visibility:** ${visibilityLabel}
@@ -23870,7 +24245,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: {
@@ -24228,7 +24603,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 {
@@ -24475,8 +24850,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) {
@@ -25506,6 +25898,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;
@@ -25560,8 +25959,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(),
@@ -25651,6 +26074,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: []
@@ -25687,7 +26114,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,
@@ -25700,9 +26138,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,
@@ -25720,7 +26160,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,
@@ -25744,7 +26184,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.
@@ -25762,7 +26202,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._`
   );
 }
@@ -29032,18 +29472,7 @@ 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");
@@ -29389,7 +29818,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
@@ -31948,6 +32377,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")));
@@ -32124,7 +32554,8 @@ 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"
     );
@@ -32451,6 +32882,7 @@ ${usageLine(decision.usage)}`;
 // src/transport-http.ts
 init_proxy_adapter();
 import { createServer as createHttpServer } from "http";
+import { createHash as createHash7 } from "crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 var BEARER_PREFIX = "papi_";
 var BEARER_REGEX = /^(papi_|papi_oauth_)[a-f0-9]{64}$/;
@@ -32480,6 +32912,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;
@@ -32518,7 +32951,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"
   };
 }
@@ -32560,6 +32993,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 createHash7("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) => {
@@ -32661,21 +33136,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") {
@@ -32718,6 +33183,13 @@ function startHttpTransport(opts) {
           return;
         }
       }
+      logEvent({
+        level: "info",
+        msg: "mcp_request",
+        ip,
+        bearer_prefix: bearerPrefix(bearer),
+        install_client: installClient
+      });
       void dispatchRequest({
         req,
         res,
@@ -32798,6 +33270,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 {
@@ -32807,17 +33291,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;
@@ -32840,10 +33366,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,