@papi-ai/server 0.7.34 → 0.7.35

package/dist/index.js

@@ -51,6 +51,7 @@ __export(git_exports, {
   hasRemote: () => hasRemote,
   hasUncommittedChanges: () => hasUncommittedChanges,
   hasUnpushedCommits: () => hasUnpushedCommits,
+  isBranchMergedInto: () => isBranchMergedInto,
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
@@ -798,6 +799,15 @@ function listGroupedCycleBranches(cwd, cycleNum, baseBranch) {
   }
   return [...seen];
 }
+function isBranchMergedInto(cwd, branch, baseBranch) {
+  try {
+    const tip = execFileSync("git", ["rev-parse", branch], { cwd, encoding: "utf-8" }).trim();
+    execFileSync("git", ["merge-base", "--is-ancestor", tip, baseBranch], { cwd, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function pickModuleCycleBranch(candidates, cycleNumber, module) {
   if (candidates.length === 0) return void 0;
   const expected = cycleBranchName(cycleNumber, module);
@@ -1199,6 +1209,17 @@ Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI
       updateTaskStatus(id, status) {
         return this.invoke("updateTaskStatus", [id, status]);
       }
+      // task-2155 (MU-3 task B): hosted/proxy claim write-path. The data-proxy gates
+      // these via WRITE_METHODS (active editor may write, viewer cannot) and binds the
+      // assignee to the bearer-derived caller server-side — the assigneeId passed here
+      // is ignored by the edge function, so it cannot be spoofed to claim on another's
+      // behalf. Mirrors pg-papi-adapter.claimTask/unclaimTask (proxy-parity enforced).
+      claimTask(taskId, assigneeId) {
+        return this.invoke("claimTask", [taskId, assigneeId]);
+      }
+      unclaimTask(taskId, assigneeId) {
+        return this.invoke("unclaimTask", [taskId, assigneeId]);
+      }
       recordTransition(taskId, fromStatus, toStatus, changedBy) {
         return this.invoke("recordTransition", [taskId, fromStatus, toStatus, changedBy]);
       }
@@ -3075,7 +3096,7 @@ var init_connection = __esm({
 
 // ../../node_modules/postgres/src/subscribe.js
 function Subscribe(postgres2, options) {
-  const subscribers = /* @__PURE__ */ new Map(), slot = "postgresjs_" + Math.random().toString(36).slice(2), state2 = {};
+  const subscribers = /* @__PURE__ */ new Map(), slot = "postgresjs_" + Math.random().toString(36).slice(2), state = {};
   let connection2, stream, ended = false;
   const sql = subscribe.sql = postgres2({
     ...options,
@@ -3092,7 +3113,7 @@ function Subscribe(postgres2, options) {
       if (ended)
         return;
       stream = null;
-      state2.pid = state2.secret = void 0;
+      state.pid = state.secret = void 0;
       connected(await init(sql, slot, options.publications));
       subscribers.forEach((event) => event.forEach(({ onsubscribe }) => onsubscribe()));
     },
@@ -3123,13 +3144,13 @@ function Subscribe(postgres2, options) {
       connected(x);
       onsubscribe();
       stream && stream.on("error", onerror);
-      return { unsubscribe, state: state2, sql };
+      return { unsubscribe, state, sql };
     });
   }
   function connected(x) {
     stream = x.stream;
-    state2.pid = x.state.pid;
-    state2.secret = x.state.secret;
+    state.pid = x.state.pid;
+    state.secret = x.state.secret;
   }
   async function init(sql2, slot2, publications) {
     if (!publications)
@@ -3141,7 +3162,7 @@ function Subscribe(postgres2, options) {
     const stream2 = await sql2.unsafe(
       `START_REPLICATION SLOT ${slot2} LOGICAL ${x.consistent_point} (proto_version '1', publication_names '${publications}')`
     ).writable();
-    const state3 = {
+    const state2 = {
       lsn: Buffer.concat(x.consistent_point.split("/").map((x2) => Buffer.from(("00000000" + x2).slice(-8), "hex")))
     };
     stream2.on("data", data);
@@ -3153,9 +3174,9 @@ function Subscribe(postgres2, options) {
     }
     function data(x2) {
       if (x2[0] === 119) {
-        parse(x2.subarray(25), state3, sql2.options.parsers, handle, options.transform);
+        parse(x2.subarray(25), state2, sql2.options.parsers, handle, options.transform);
       } else if (x2[0] === 107 && x2[17]) {
-        state3.lsn = x2.subarray(1, 9);
+        state2.lsn = x2.subarray(1, 9);
         pong();
       }
     }
@@ -3171,7 +3192,7 @@ function Subscribe(postgres2, options) {
     function pong() {
       const x2 = Buffer.alloc(34);
       x2[0] = "r".charCodeAt(0);
-      x2.fill(state3.lsn, 1);
+      x2.fill(state2.lsn, 1);
       x2.writeBigInt64BE(BigInt(Date.now() - Date.UTC(2e3, 0, 1)) * BigInt(1e3), 25);
       stream2.write(x2);
     }
@@ -3183,12 +3204,12 @@ function Subscribe(postgres2, options) {
 function Time(x) {
   return new Date(Date.UTC(2e3, 0, 1) + Number(x / BigInt(1e3)));
 }
-function parse(x, state2, parsers2, handle, transform) {
+function parse(x, state, parsers2, handle, transform) {
   const char = (acc, [k, v]) => (acc[k.charCodeAt(0)] = v, acc);
   Object.entries({
     R: (x2) => {
       let i = 1;
-      const r = state2[x2.readUInt32BE(i)] = {
+      const r = state[x2.readUInt32BE(i)] = {
         schema: x2.toString("utf8", i += 4, i = x2.indexOf(0, i)) || "pg_catalog",
         table: x2.toString("utf8", i + 1, i = x2.indexOf(0, i + 1)),
         columns: Array(x2.readUInt16BE(i += 2)),
@@ -3215,12 +3236,12 @@ function parse(x, state2, parsers2, handle, transform) {
     },
     // Origin
     B: (x2) => {
-      state2.date = Time(x2.readBigInt64BE(9));
-      state2.lsn = x2.subarray(1, 9);
+      state.date = Time(x2.readBigInt64BE(9));
+      state.lsn = x2.subarray(1, 9);
     },
     I: (x2) => {
       let i = 1;
-      const relation = state2[x2.readUInt32BE(i)];
+      const relation = state[x2.readUInt32BE(i)];
       const { row } = tuples(x2, relation.columns, i += 7, transform);
       handle(row, {
         command: "insert",
@@ -3229,7 +3250,7 @@ function parse(x, state2, parsers2, handle, transform) {
     },
     D: (x2) => {
       let i = 1;
-      const relation = state2[x2.readUInt32BE(i)];
+      const relation = state[x2.readUInt32BE(i)];
       i += 4;
       const key = x2[i] === 75;
       handle(
@@ -3243,7 +3264,7 @@ function parse(x, state2, parsers2, handle, transform) {
     },
     U: (x2) => {
       let i = 1;
-      const relation = state2[x2.readUInt32BE(i)];
+      const relation = state[x2.readUInt32BE(i)];
       i += 4;
       const key = x2[i] === 75;
       const xs = key || x2[i] === 79 ? tuples(x2, relation.columns, i += 3, transform) : null;
@@ -3954,12 +3975,12 @@ function resolveDatabaseUrl() {
 function classifyWedged(rows) {
   const wedged = [];
   for (const r of rows) {
-    const state2 = (r.state ?? "").toLowerCase();
+    const state = (r.state ?? "").toLowerCase();
     const stateAge = Number(r.state_age ?? 0);
     const queryAge = Number(r.query_age ?? 0);
-    if (state2.startsWith("idle in transaction") && stateAge > WEDGED_IDLE_TX_SECONDS) {
+    if (state.startsWith("idle in transaction") && stateAge > WEDGED_IDLE_TX_SECONDS) {
       wedged.push({ pid: r.pid, state: r.state ?? "unknown", ageSeconds: Math.round(stateAge), reason: "idle-in-transaction" });
-    } else if (state2 === "active" && queryAge > WEDGED_ACTIVE_SECONDS) {
+    } else if (state === "active" && queryAge > WEDGED_ACTIVE_SECONDS) {
       wedged.push({ pid: r.pid, state: r.state ?? "unknown", ageSeconds: Math.round(queryAge), reason: "long-active" });
     }
   }
@@ -5163,7 +5184,10 @@ function toCycleTask(raw) {
     closureReason: raw.closure_reason || void 0,
     buildHandoff: raw.build_handoff ? parseBuildHandoff(raw.build_handoff) ?? void 0 : void 0,
     buildReport: raw.build_report || void 0,
-    scopeClass: raw.scope_class === "brief" ? "brief" : "task"
+    scopeClass: raw.scope_class === "brief" ? "brief" : "task",
+    assigneeId: raw.assignee_id || void 0,
+    claimSource: raw.claim_source === "pool" || raw.claim_source === "self_generated" ? raw.claim_source : void 0,
+    reviewerId: raw.reviewer_id || void 0
   };
 }
 function sanitizeDelimiters(value) {
@@ -5196,6 +5220,9 @@ function fromCycleTask(task) {
   if (task.buildHandoff) raw.build_handoff = sanitizeDelimiters(serializeBuildHandoff(task.buildHandoff));
   if (task.buildReport) raw.build_report = sanitizeDelimiters(task.buildReport);
   if (task.scopeClass && task.scopeClass !== "task") raw.scope_class = task.scopeClass;
+  if (task.assigneeId) raw.assignee_id = task.assigneeId;
+  if (task.claimSource) raw.claim_source = task.claimSource;
+  if (task.reviewerId) raw.reviewer_id = task.reviewerId;
   return raw;
 }
 function mergeConflictHint(content) {
@@ -5262,6 +5289,7 @@ function filterTasks(tasks, options) {
     if (options.reviewed !== void 0 && task.reviewed !== options.reviewed) return false;
     if (options.module && task.module !== options.module) return false;
     if (options.epic && task.epic !== options.epic) return false;
+    if (options.assigneeId && task.assigneeId !== options.assigneeId) return false;
     return true;
   });
 }
@@ -6043,6 +6071,7 @@ function toCycle(raw) {
     taskIds: raw.task_ids ?? []
   };
   if (raw.end_date) cycle.endDate = raw.end_date;
+  if (raw.user_id) cycle.userId = raw.user_id;
   return cycle;
 }
 function fromCycle(cycle) {
@@ -6056,6 +6085,7 @@ function fromCycle(cycle) {
     task_ids: cycle.taskIds
   };
   if (cycle.endDate) raw.end_date = cycle.endDate;
+  if (cycle.userId) raw.user_id = cycle.userId;
   return raw;
 }
 function extractYamlBlock2(content) {
@@ -6378,6 +6408,66 @@ var MdFileAdapter = class {
   async updateTaskStatus(id, status) {
     return this.updateTask(id, { status });
   }
+  /**
+   * task-1763 (C293): atomic compare-and-swap task claim. First-claim-wins —
+   * sets assigneeId only if the task is currently unclaimed. The markdown adapter
+   * is single-process, so the read-check-write is trivially atomic here; the real
+   * concurrency guarantee lives in the pg adapter's RETURNING CAS. Returns the
+   * claimed task, or null if it was already claimed or does not exist.
+   *
+   * task-2071 (MU-3): the pooled-task invariant is `assigneeId == null && cycle
+   * == null` — a task already pulled into someone's cycle is NOT in the pool and
+   * cannot be claimed. Sets claimSource='pool' on success.
+   */
+  async claimTask(taskId, assigneeId) {
+    const content = await this.read("SPRINT_BOARD.md");
+    const tasks = parseBoard(content);
+    const idx = tasks.findIndex((t) => t.id === taskId);
+    if (idx === -1) return null;
+    if (tasks[idx].assigneeId || tasks[idx].cycle != null) return null;
+    tasks[idx] = { ...tasks[idx], assigneeId, claimSource: "pool" };
+    await this.write("SPRINT_BOARD.md", serializeBoard(tasks, content));
+    return tasks[idx];
+  }
+  /**
+   * task-2071 (C293, MU-3): claimer-only release. Clears assigneeId + claimSource
+   * only if the task is currently assigned to `assigneeId` and has not entered
+   * review. Returns the unclaimed task, or null if the caller is not the claimer,
+   * the task has progressed, or it does not exist.
+   */
+  async unclaimTask(taskId, assigneeId) {
+    const content = await this.read("SPRINT_BOARD.md");
+    const tasks = parseBoard(content);
+    const idx = tasks.findIndex((t2) => t2.id === taskId);
+    if (idx === -1) return null;
+    const t = tasks[idx];
+    if (t.assigneeId !== assigneeId) return null;
+    if (t.status === "In Review" || t.status === "Done") return null;
+    const next = { ...t };
+    delete next.assigneeId;
+    delete next.claimSource;
+    tasks[idx] = next;
+    await this.write("SPRINT_BOARD.md", serializeBoard(tasks, content));
+    return tasks[idx];
+  }
+  /**
+   * task-2072 (C293, MU-4): atomic review claim. Sets reviewerId only if the task
+   * is In Review and not yet claimed for review (reviewerId == null). First-claim-
+   * wins. Returns the claimed task, or null if already review-claimed / not In
+   * Review / missing.
+   */
+  async claimReview(taskId, reviewerId) {
+    const content = await this.read("SPRINT_BOARD.md");
+    const tasks = parseBoard(content);
+    const idx = tasks.findIndex((t2) => t2.id === taskId);
+    if (idx === -1) return null;
+    const t = tasks[idx];
+    if (t.status !== "In Review") return null;
+    if (t.reviewerId) return null;
+    tasks[idx] = { ...t, reviewerId };
+    await this.write("SPRINT_BOARD.md", serializeBoard(tasks, content));
+    return tasks[idx];
+  }
   async recordTransition(_taskId, _fromStatus, _toStatus, _changedBy) {
   }
   // --- Build Reports ---
@@ -6817,6 +6907,8 @@ ${footer}`);
 - **source:** ${full.source}
 ` + (full.sourceRef ? `- **sourceRef:** ${full.sourceRef}
 ` : "") + (full.detail ? `- **detail:** ${full.detail}
+` : "") + (full.evidenceRef ? `- **evidenceRef:** ${full.evidenceRef}
+` : "") + (full.metricDelta ? `- **metricDelta:** ${JSON.stringify(full.metricDelta)}
 ` : "") + `- **createdAt:** ${full.createdAt}
 
 ---
@@ -6850,8 +6942,18 @@ ${footer}`);
       const sourceMatch = block.match(/\*\*source:\*\*\s+(.+)/);
       const sourceRefMatch = block.match(/\*\*sourceRef:\*\*\s+(.+)/);
       const detailMatch = block.match(/\*\*detail:\*\*\s+(.+)/);
+      const evidenceRefMatch = block.match(/\*\*evidenceRef:\*\*\s+(.+)/);
+      const metricDeltaMatch = block.match(/\*\*metricDelta:\*\*\s+(.+)/);
       const createdAtMatch = block.match(/\*\*createdAt:\*\*\s+(.+)/);
       if (!idMatch || !sourceMatch || !createdAtMatch) continue;
+      let metricDelta;
+      if (metricDeltaMatch?.[1]) {
+        try {
+          metricDelta = JSON.parse(metricDeltaMatch[1].trim());
+        } catch {
+          metricDelta = null;
+        }
+      }
       events.push({
         id: idMatch[1].trim(),
         decisionId: headingMatch[1],
@@ -6860,6 +6962,8 @@ ${footer}`);
         source: sourceMatch[1].trim(),
         sourceRef: sourceRefMatch?.[1]?.trim(),
         detail: detailMatch?.[1]?.trim(),
+        evidenceRef: evidenceRefMatch?.[1]?.trim(),
+        metricDelta,
         createdAt: createdAtMatch[1].trim()
       });
     }
@@ -7667,8 +7771,18 @@ function formatDetailedTask(t) {
   Reviewed: ${t.reviewed}${t.dependsOn ? ` | Depends on: ${t.dependsOn}` : ""}${hasHandoff ? " | Has BUILD HANDOFF: yes" : ""}${t.docRef ? ` | Doc ref: ${t.docRef}` : ""}${t.opportunity ? ` | Opportunity: ${t.opportunity}` : ""}${notes ? `
   Notes: ${notes}` : ""}`;
 }
-function formatBoardForPlan(tasks, filters, currentCycle) {
-  if (tasks.length === 0) return "No tasks on the board.";
+var PRIORITY_RANK = { "P0 Critical": 0, "P1 High": 1, "P2 Medium": 2, "P3 Low": 3 };
+function formatDeferredForPlan(deferred) {
+  if (deferred.length === 0) return "";
+  const sorted = [...deferred].sort(
+    (a, b2) => (PRIORITY_RANK[a.priority] ?? 9) - (PRIORITY_RANK[b2.priority] ?? 9)
+  );
+  return `**Deferred (${deferred.length} parked \u2014 re-triageable, NOT active candidates):**
+These were parked, not deleted. Do NOT auto-schedule them. If a task's blocker has cleared or it now fits this cycle's strategic theme, un-defer it with a \`boardCorrections\` "promote" entry; otherwise leave it parked.
+` + sorted.map(formatCompactTask).join("\n");
+}
+function formatBoardForPlan(tasks, filters, currentCycle, deferredTasks = []) {
+  if (tasks.length === 0 && deferredTasks.length === 0) return "No tasks on the board.";
   let active = tasks.filter((t) => !PLAN_EXCLUDED_STATUSES.has(t.status));
   const excludedCount = tasks.length - active.length;
   if (filters) {
@@ -7677,13 +7791,24 @@ function formatBoardForPlan(tasks, filters, currentCycle) {
     if (filters.epic) active = active.filter((t) => t.epic === filters.epic);
     if (filters.priority) active = active.filter((t) => t.priority === filters.priority);
   }
+  let deferred = deferredTasks.filter((t) => t.status === "Deferred");
+  if (filters) {
+    if (filters.phase) deferred = deferred.filter((t) => t.phase === filters.phase);
+    if (filters.module) deferred = deferred.filter((t) => t.module === filters.module);
+    if (filters.epic) deferred = deferred.filter((t) => t.epic === filters.epic);
+    if (filters.priority) deferred = deferred.filter((t) => t.priority === filters.priority);
+  }
+  const deferredSection = formatDeferredForPlan(deferred);
   const userFilteredCount = tasks.length - excludedCount - active.length;
   const filterParts = [];
   if (excludedCount > 0) filterParts.push(`${excludedCount} completed filtered`);
   if (userFilteredCount > 0) filterParts.push(`${userFilteredCount} excluded by filters`);
   const filterSuffix = filterParts.length > 0 ? filterParts.join(", ") : "";
   if (active.length === 0) {
-    return `No active tasks on the board (${filterSuffix || "all filtered"}).`;
+    const base = `No active tasks on the board (${filterSuffix || "all filtered"}).`;
+    return deferredSection ? `${base}
+
+${deferredSection}` : base;
   }
   const byCounts = (statuses) => statuses.map((s) => {
     const n = active.filter((t) => t.status === s).length;
@@ -7692,9 +7817,12 @@ function formatBoardForPlan(tasks, filters, currentCycle) {
   const summary = `Board: ${active.length} active tasks (${byCounts(["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Blocked"])})` + (filterSuffix ? ` \u2014 ${filterSuffix}` : "");
   if (currentCycle === void 0) {
     const formatted = active.map(formatDetailedTask).join("\n\n");
-    return `${summary}
+    const body = `${summary}
 
 ${formatted}`;
+    return deferredSection ? `${body}
+
+${deferredSection}` : body;
   }
   const recent = [];
   const stable = [];
@@ -7715,6 +7843,7 @@ ${formatted}`;
 ` + stable.map(formatCompactTask).join("\n")
     );
   }
+  if (deferredSection) sections.push(deferredSection);
   return sections.join("\n\n");
 }
 function formatCandidateTaskFullNotes(tasks) {
@@ -8166,11 +8295,19 @@ This is Cycle 0 \u2014 the first planning cycle for a brand-new project.
 
 2. **North Star** \u2014 Propose a one-sentence North Star statement, a success metric, and a key metric.
 
-3. **Initial Board** \u2014 Generate 3-5 tasks based on the project's actual tech stack and goals:
+3. **Initial Board** \u2014 Generate 3-5 tasks based on the project's actual tech stack and goals.
+
+   **Sequencing principle \u2014 local-first / thinnest-vertical-slice-first (AD-51).** Plan the way the everyday builder gets value, NOT the way a backend team scaffolds. Order the first cycle so the user SEES the core loop working as fast as possible:
+   1. **Thinnest visible vertical slice first** \u2014 the core loop on screen, running on local / mock / hardcoded data. Cycle 1 should make the thing actually work in front of the user.
+   2. **Persistence / real data model** \u2014 only after the slice exists.
+   3. **Auth** \u2014 later, and **NEVER third-party OAuth (Google/GitHub/etc.) as an opening task.** Start with no-auth or the simplest local auth.
+   4. **RLS / cloud hardening / multi-tenant security** \u2014 last. These are not cycle-1 work for a new project.
+   Defer infrastructure (cloud DB schema, RLS, OAuth providers, large data seeds) until a working slice exists. A first cycle that opens with "Supabase schema + RLS + third-party OAuth + a big data seed" is the exact anti-pattern this rule exists to prevent.
+
    - Infer the project type from the brief/description (CLI, web app, mobile app, API, library, game, data pipeline, etc.)
-   - Task 1: Project-appropriate setup (toolchain, dependencies, config \u2014 NOT "scaffolding" if the project already has code)
-   - Task 2: Core functionality that proves the concept works (data model, main loop, core algorithm \u2014 whatever the project needs first)
-   - Tasks 3-5: First deliverables that demonstrate value, broken into small steps appropriate for the project type
+   - Task 1: The thinnest vertical slice that puts the core loop in front of the user (local/mock data is fine \u2014 and preferred \u2014 at this stage). NOT infra scaffolding unless the project literally has no runnable surface without it.
+   - Task 2: The next slice, or the minimal persistence the core loop needs \u2014 only once the slice works.
+   - Tasks 3-5: Further value-demonstrating slices, broken into small steps appropriate for the project type. Keep auth, cloud, and hardening OUT of the opening cycle unless the brief makes them the literal core product.
    - Do NOT assume web-app patterns (routes, pages, components) unless the brief explicitly describes a web application
    - All tasks: status Backlog, priority P1-P2, reviewed true, phase "Phase 1"
 
@@ -8333,7 +8470,7 @@ Standard planning cycle with full board review.
   }
   parts.push(`
 6. **Maturity Gate** \u2014 Before scheduling any task, check whether the project is ready for it:
-   - **Cycle number as signal:** A Cycle 3 project should not be scheduling OAuth, billing, or analytics tasks. Early cycles focus on core functionality and proving the concept works.
+   - **Cycle number as signal (local-first sequencing, AD-51):** A Cycle 1-3 project should not be scheduling OAuth, billing, analytics, or RLS/cloud-hardening tasks. Early cycles sequence local-first / thinnest-vertical-slice-first: get the core loop working on local/mock data, THEN persistence, THEN auth (never third-party OAuth as an opening task), and RLS/cloud hardening LAST. Defer infrastructure until a working slice exists \u2014 plan the way the everyday builder gets value, not the way a backend team scaffolds.
    - **Phase prerequisites:** If the board has phases, tasks from later phases should only be scheduled when earlier phases have completed tasks (check Done count per phase). A task in "Phase 4: Monetisation" is premature if Phase 2 tasks are still in Backlog.
    - **Dependency chain:** If a task's \`dependsOn\` references incomplete tasks, it cannot be scheduled regardless of priority.
    - **Task maturity:** Tasks with \`maturity: "raw"\` are unscoped ideas from the idea tool. The planner IS the scoping mechanism \u2014 scope them as part of planning. For raw tasks selected for a cycle: (a) derive clear scope, acceptance criteria, and effort from the title, notes, and project context, (b) upgrade them to \`maturity: "investigated"\` via a \`boardCorrections\` entry, and (c) generate a BUILD HANDOFF as normal. For research-type raw tasks, scope the handoff as an investigation task \u2014 the deliverable is findings + follow-up backlog tasks, not code. Only leave a raw task unscheduled if you genuinely cannot derive scope from the available context \u2014 note why in the cycle log. Tasks with \`maturity: "ready"\` or no maturity field are considered cycle-ready. Tasks with \`maturity: "investigated"\` have been scoped but may still need refinement \u2014 schedule them if priority warrants it.
@@ -8407,7 +8544,7 @@ ${AD_REJECTION_RULES}
    - **Architecture Notes:** If a pattern was established that needs follow-up (e.g. "shared service layer created, MCP migration needed"), propose the follow-up.
    - **Strategy gaps:** If an Active Decision has no board tasks supporting it, propose one.
    - **Dogfood observations:** Unactioned dogfood entries span FOUR categories (friction, methodology, signal, commercial) \u2014 consider ALL of them, not just friction. If an entry (with ID) maps to no existing task, propose one, matching task type to category: friction/signal \u2192 fix or improvement; methodology \u2192 process/tooling change; commercial \u2192 GTM/positioning. **CRITICAL: Include \`dogfood:<uuid>\` in the new task's \`notes\` field** (e.g. \`"notes": "dogfood:abc12345-..."\`). This links the task to the observation so the pipeline can track what was actioned. Without this annotation, the observation stays unactioned forever.
-   Create new tasks via the \`newTasks\` array in Part 2. Use \`new-N\` IDs in \`cycleHandoffs\` to reference them. **Limit: 3 new tasks per cycle** to prevent backlog bloat.
+   Create new tasks via the \`newTasks\` array in Part 2. Use \`new-N\` IDs in \`cycleHandoffs\` to reference them. **New-task cap \u2014 scale it to backlog depth, do NOT hard-cap at 3:** when 5+ unblocked backlog candidates already exist, limit new tasks to 3 (there is plenty to select from, so prevent backlog bloat). When the backlog is thin (fewer than 5 unblocked candidates), create as many as needed to bring the cycle into the healthy 5-8 range \u2014 roughly \`6 \u2212 unblocked_candidates\` additional new tasks, derived from the brief, roadmap phases, and recent build reports \u2014 up to an absolute ceiling of **8 new tasks**. This removes the contradiction with the Cycle-sizing rule above (a healthy cycle is 6-10 tasks; <5 needs justification), which the old flat cap of 3 violated whenever the backlog was thin. Never invent filler to hit a number: every new task must trace to a real discovered issue, dogfood entry, roadmap phase, or brief item.
    **\u26A0\uFE0F DUPLICATE CHECK:** Before adding a task to \`newTasks\`, scan the Cycle Board above for any existing task with the same or very similar title/scope. If a matching task already exists (even with slightly different wording), do NOT create a duplicate \u2014 reference the existing task ID instead. The board already contains all active tasks; re-creating them wastes IDs and bloats the board.
    **\u26A0\uFE0F ALREADY-BUILT CHECK:** Before creating a task, check the recent build reports and cycle log for evidence that this capability was already shipped. If a recent build report shows this feature was completed (even under a different task name), do NOT create a new task for it. This is especially important for UI features, data models, and integrations that may already exist.`);
   parts.push(PLAN_FRAGMENT_PRODUCT_BRIEF);
@@ -8485,6 +8622,9 @@ function buildPlanUserMessage(ctx) {
       ""
     );
   }
+  if (ctx.siblingRepoWarning) {
+    parts.push("", ctx.siblingRepoWarning, "");
+  }
   parts.push("", "---", "", "## PROJECT CONTEXT", "");
   if (ctx.contextTier) {
     parts.push(`**Context tier:** ${ctx.contextTier}`, "");
@@ -8840,7 +8980,9 @@ After your natural language output, include this EXACT format on its own line:
     {
       "id": "string \u2014 AD-N (existing) or new AD-N (for new decisions)",
       "action": "confidence_change | modify | resolve | supersede | new | delete",
-      "body": "string \u2014 full AD block including ### heading, confidence tag, and body text (empty string for delete)"
+      "body": "string \u2014 full AD block including ### heading, confidence tag, and body text (empty string for delete)",
+      "evidenceRef": "string (optional) \u2014 for DELIBERATE decisions (modify / resolve / delete = validate/modify/invalidate), a pointer to the evidence that justified the change: a doc path (docs/research/foo.md), a build-report id, or a metric name. Builds the decision->outcome ledger. Omit if no concrete evidence.",
+      "metricDelta": "object (optional) \u2014 { "metric": string, "before": number, "after": number, "delta": number } \u2014 which metric moved and by how much. Use a REAL metric name from cycle_metrics_snapshots where possible (e.g. scope_accuracy, velocity, est_actual_drift). Omit if no metric moved."
     }
   ],
   "decisionScores": [
@@ -8900,6 +9042,8 @@ The JSON must be valid. Use null for optional fields that don't apply.
 For activeDecisionUpdates, the body field must be the COMPLETE replacement text for the AD block (including the ### heading line).
 Only include ADs that need changes \u2014 omit unchanged ADs.${compressionNote}
 
+**Decision-outcome ledger (task-2168):** For DELIBERATE decisions \u2014 \`modify\`, \`resolve\`, or \`delete\` (i.e. you validated, modified, or invalidated an AD based on what actually happened) \u2014 include \`evidenceRef\` and/or \`metricDelta\` so the decision becomes a queryable ledger entry rather than freetext. \`evidenceRef\` points at WHAT justified the change (a doc path, a build-report id, or a metric name). \`metricDelta\` records WHICH metric moved (prefer a real metric from cycle_metrics_snapshots) and its before->after. This is **guidance, not a hard requirement** \u2014 if a deliberate change genuinely has no concrete evidence, omit both and proceed; the apply will record the event with a non-blocking warning.
+
 ## PERSISTENCE RULES \u2014 READ THIS CAREFULLY
 
 Everything in Part 1 (natural language) is **display-only**. Part 2 (structured JSON) is what gets written to files.
@@ -9065,7 +9209,9 @@ After your natural language output, include this EXACT format on its own line:
     {
       "id": "string \u2014 AD-N (existing) or new AD-N (for new decisions)",
       "action": "confidence_change | modify | resolve | supersede | new | delete",
-      "body": "string \u2014 full AD block including ### heading, confidence tag, and body text (empty string for delete)"
+      "body": "string \u2014 full AD block including ### heading, confidence tag, and body text (empty string for delete)",
+      "evidenceRef": "string (optional) \u2014 for DELIBERATE changes (modify / resolve / delete), a pointer to the justifying evidence: a doc path, a build-report id, or a metric name. Builds the decision->outcome ledger. Omit if none.",
+      "metricDelta": "object (optional) \u2014 { "metric": string, "before": number, "after": number, "delta": number } \u2014 which metric moved. Prefer a real metric name from cycle_metrics_snapshots. Omit if none."
     }
   ],
   "phaseUpdates": [
@@ -9382,6 +9528,37 @@ Return a JSON array of 3-10 tasks. Each task must have:
 - Use the full complexity range: XS (config/one-liner), Small (one file), Medium (2-5 files), Large (cross-module), XL (architectural)
 - Tasks should be specific enough to execute without further investigation
 - Maximum 10 tasks \u2014 fewer is better if the codebase is well-maintained`;
+var VISION_TASKS_SYSTEM = `You are a product engineer turning a project VISION into a starter backlog for a brand-new project (no code exists yet). The user has described what they want to build; your job is to make that vision legible as concrete, buildable tasks.
+
+IMPORTANT: You are running as a non-interactive API call. Do NOT ask questions. Produce tasks directly.
+
+## OUTPUT FORMAT
+
+Return a JSON array of 15-20 tasks. Each task must have:
+- "title": Clear, actionable task title (start with a verb)
+- "priority": "P0 Critical", "P1 High", "P2 Medium", or "P3 Low"
+- "complexity": "XS", "Small", "Medium", "Large", or "XL"
+- "module": A module name inferred from the vision (e.g. "Core", "Auth", "Frontend", "API", "Payments")
+- "phase": A phase name ("Phase 1" for the first shippable slice, "Phase 2" for what follows, etc.)
+- "notes": 1-2 sentences tying this task to the user's stated vision
+
+## GUIDELINES
+
+- Cover the VISION, not a generic app skeleton. Every task must trace to something the user actually described.
+- Sequence local-first / thinnest-vertical-slice-first (AD-51): the first few P0/P1 tasks should be the smallest path to a visibly working thing, NOT infrastructure scaffolding (no "set up CI", "configure auth provider", "design database schema" as opening tasks). Plan the way the user gets value, not the way a backend team scaffolds.
+- Mix: the first shippable feature slice (Phase 1), then the next features, then supporting/foundational work behind them.
+- 15-20 is a TARGET BAND for good vision coverage, NOT a quota. If the vision is genuinely small, produce fewer high-quality tasks. NEVER pad with filler ("add tests", "write docs", "refactor") to hit a number.
+- Use the full complexity range. Keep titles concrete enough to execute without re-deriving the vision.
+- Do NOT add PAPI-setup tasks \u2014 those are handled by the setup flow.`;
+function buildVisionTasksPrompt(inputs) {
+  const line = (label, val) => val?.trim() ? `**${label}:** ${val.trim()}
+` : "";
+  return `Turn this project vision into a 15-20 item starter backlog.
+
+**Project:** ${inputs.projectName}
+${line("What it is", inputs.description)}${line("Target users", inputs.targetUsers)}${line("Problems it solves", inputs.problems)}${line("Project type", inputs.projectType)}
+You are ALSO generating this project's Product Brief in this same setup round \u2014 use that fuller vision as your primary source. Return a JSON array of 15-20 tasks (coverage over count; do not pad) that make this vision a buildable backlog, thinnest-shippable-slice first.`;
+}
 function buildInitialTasksPrompt(inputs) {
   const description = inputs.description?.trim() ? `**Description:** ${inputs.description}
 ` : `**Description:** (not provided \u2014 derive from the codebase analysis below)
@@ -9533,8 +9710,8 @@ function oneLine(ad) {
 }
 function formatHierarchy(horizons, stages) {
   if (!horizons.length && !stages.length) return "";
-  const activeHorizon = horizons.find((h) => h.status === "active") ?? horizons[0];
-  const activeStage = stages.find((s) => s.status === "active") ?? stages[0];
+  const activeHorizon = horizons.find((h) => h.status === "In Progress") ?? horizons[0];
+  const activeStage = stages.find((s) => s.status === "In Progress") ?? stages[0];
   const parts = [];
   if (activeHorizon) parts.push(activeHorizon.slug || activeHorizon.label);
   if (activeStage) parts.push(activeStage.slug || activeStage.label);
@@ -9557,7 +9734,7 @@ function validateHandoffScope(handoff) {
   if (!isMeaningful(handoff.scopeBoundary)) invalid.push("scopeBoundary");
   return invalid;
 }
-async function prepareHandoffs(adapter2, _config, taskIds) {
+async function prepareHandoffs(adapter2, _config, taskIds, force = false) {
   const timer2 = startTimer();
   const cycles = await adapter2.readCycles();
   const activeCycle = cycles.find((c) => c.status === "active");
@@ -9571,10 +9748,10 @@ async function prepareHandoffs(adapter2, _config, taskIds) {
     const idSet = new Set(taskIds);
     cycleTasks = cycleTasks.filter((t) => idSet.has(t.id));
   }
-  const tasksNeedingHandoffs = cycleTasks.filter((t) => !t.buildHandoff);
+  const tasksNeedingHandoffs = force ? cycleTasks : cycleTasks.filter((t) => !t.buildHandoff);
   if (tasksNeedingHandoffs.length === 0) {
     throw new Error(
-      taskIds?.length ? `All specified tasks already have BUILD HANDOFFs. Nothing to generate.` : `All ${cycleTasks.length} cycle task(s) already have BUILD HANDOFFs. Nothing to generate.`
+      force ? taskIds?.length ? `No matching cycle task(s) found to regenerate. Check the task IDs are in the active cycle.` : `No cycle task(s) found to regenerate.` : taskIds?.length ? `All specified tasks already have BUILD HANDOFFs. Nothing to generate. Pass force: true to regenerate.` : `All ${cycleTasks.length} cycle task(s) already have BUILD HANDOFFs. Nothing to generate. Pass force: true to regenerate.`
     );
   }
   const [decisions, reports, brief] = await Promise.all([
@@ -9605,7 +9782,7 @@ async function prepareHandoffs(adapter2, _config, taskIds) {
     taskCount: tasksNeedingHandoffs.length
   };
 }
-async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber) {
+async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false) {
   const timer2 = startTimer();
   const { data } = parseStructuredOutput(rawLlmOutput);
   if (!data) {
@@ -9629,7 +9806,7 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber) {
   const warnings = [];
   for (const handoff of handoffs) {
     try {
-      if (existingHandoffSet.has(handoff.taskId)) {
+      if (!force && existingHandoffSet.has(handoff.taskId)) {
         console.error(`[handoff] skipping ${handoff.taskId} \u2014 already has handoff`);
         skipped++;
         continue;
@@ -10005,7 +10182,72 @@ async function resolveVisibilityFromDocs(adapter2, docRefs) {
   };
 }
 
+// src/lib/owner-identity.ts
+function isProjectOwner(callerUserId, ownerUserId) {
+  if (!callerUserId || !ownerUserId) return false;
+  const caller = callerUserId.trim().toLowerCase();
+  const owner = ownerUserId.trim().toLowerCase();
+  if (caller.length === 0 || owner.length === 0) return false;
+  return caller === owner;
+}
+async function resolveOwnerGate(adapter2, config2) {
+  if (typeof adapter2.getOwnerIdentity === "function") {
+    try {
+      const identity = await adapter2.getOwnerIdentity();
+      const callerUserId = identity.callerUserId ?? config2.userId ?? null;
+      return {
+        enforced: true,
+        callerIsOwner: isProjectOwner(callerUserId, identity.ownerUserId),
+        callerUserId,
+        ownerUserId: identity.ownerUserId
+      };
+    } catch (err) {
+      return {
+        enforced: true,
+        callerIsOwner: false,
+        callerUserId: config2.userId ?? null,
+        ownerUserId: null,
+        resolutionError: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  if (typeof adapter2.getProjectOwnerUserId === "function") {
+    let ownerUserId = null;
+    let resolutionError;
+    try {
+      ownerUserId = await adapter2.getProjectOwnerUserId();
+    } catch (err) {
+      resolutionError = err instanceof Error ? err.message : String(err);
+    }
+    const callerUserId = config2.userId ?? null;
+    return {
+      enforced: true,
+      callerIsOwner: isProjectOwner(callerUserId, ownerUserId),
+      callerUserId,
+      ownerUserId,
+      ...resolutionError !== void 0 ? { resolutionError } : {}
+    };
+  }
+  return {
+    enforced: false,
+    callerIsOwner: true,
+    callerUserId: config2.userId ?? null,
+    ownerUserId: null
+  };
+}
+
 // src/services/plan.ts
+async function resolvePlanScope(adapter2, config2) {
+  const gate = await resolveOwnerGate(adapter2, config2);
+  return { callerUserId: gate.callerUserId, ownerUserId: gate.ownerUserId, callerIsOwner: gate.callerIsOwner };
+}
+function filterToPersonalBacklog(tasks, scope) {
+  if (!scope.callerUserId) return tasks;
+  if (scope.callerIsOwner) {
+    return tasks.filter((t) => !t.assigneeId || t.assigneeId === scope.callerUserId);
+  }
+  return tasks.filter((t) => t.assigneeId === scope.callerUserId);
+}
 function determineContextTier(cycleCount) {
   if (cycleCount <= 5) return 1;
   if (cycleCount <= 20) return 2;
@@ -10294,8 +10536,8 @@ var BRIEF_SECTIONS = [
   }
 ];
 function assessBriefThinness(brief) {
-  const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
-  const briefWithoutTemplate = brief.replace(TEMPLATE_MARKER, "");
+  const TEMPLATE_MARKER2 = "*Describe your project's core value proposition here.*";
+  const briefWithoutTemplate = brief.replace(TEMPLATE_MARKER2, "");
   const populated = [];
   const missing = [];
   for (const section of BRIEF_SECTIONS) {
@@ -10434,12 +10676,34 @@ async function readDogfoodEntries(projectRoot, count = 5, adapter2) {
     return void 0;
   }
 }
+function formatSiblingRepoWarning(siblings) {
+  const lines = siblings.slice(0, 20).map(
+    (s) => `- ${s.displayId} [${s.sourceProjectName}] (${s.status}${s.epic ? `, ${s.epic}` : ""}): ${s.title}`
+  );
+  const more = siblings.length > 20 ? `
+  \u2026and ${siblings.length - 20} more` : "";
+  return [
+    "## \u26A0\uFE0F SHARED-REPO SIBLING WORK \u2014 CHECK BEFORE SCHEDULING",
+    "",
+    "Other PAPI projects share THIS repository and have the tasks below IN FLIGHT (backlog / in progress / in review). Shared-repo work (multi-user, RLS, auth, common codebase) may already be built or underway in a sibling project. Do NOT schedule a task that duplicates one below \u2014 skip it or note the overlap in cycleLogNotes instead of re-building. (Root cause of the C292 incident: the planner re-scheduled already-merged multi-user work, costing a build + a prod DB revert.)",
+    "",
+    ...lines,
+    more
+  ].filter(Boolean).join("\n");
+}
 async function assembleContext(adapter2, mode, _config, filters, focus) {
   const totalTimer = startTimer();
   const timings = {};
+  const planScope = await resolvePlanScope(adapter2, _config);
   let t = startTimer();
   const health = await adapter2.getCycleHealth();
   timings["getCycleHealth"] = t();
+  let siblingRepoWarning;
+  try {
+    const siblings = await adapter2.getSiblingRepoTasks?.() ?? [];
+    if (siblings.length > 0) siblingRepoWarning = formatSiblingRepoWarning(siblings);
+  } catch {
+  }
   t = startTimer();
   const [rawProductBrief, currentNorthStar] = await Promise.all([
     adapter2.readProductBrief(),
@@ -10564,9 +10828,10 @@ ${lines.join("\n")}`;
       const doneIds = doneTasksResult.status === "fulfilled" ? new Set(doneTasksResult.value.map((t2) => t2.displayId)) : void 0;
       carryForwardStalenessLean = computeCarryForwardStaleness(cycleLogResult.value, doneIds);
     }
+    const candidateTasksLean = preAssignedResult.status === "fulfilled" ? filterToPersonalBacklog(preAssignedResult.value, planScope) : [];
     let preAssignedTextLean;
     if (preAssignedResult.status === "fulfilled") {
-      const preAssigned2 = preAssignedResult.value.filter((t2) => t2.cycle === leanTargetCycle);
+      const preAssigned2 = candidateTasksLean.filter((t2) => t2.cycle === leanTargetCycle);
       preAssignedTextLean = formatPreAssignedTasks(preAssigned2, leanTargetCycle);
     }
     let recentlyShippedLean;
@@ -10575,7 +10840,7 @@ ${lines.join("\n")}`;
     }
     let candidateTaskFullNotesLean;
     if (preAssignedResult.status === "fulfilled") {
-      candidateTaskFullNotesLean = formatCandidateTaskFullNotes(preAssignedResult.value);
+      candidateTaskFullNotesLean = formatCandidateTaskFullNotes(candidateTasksLean);
     }
     logDataSourceSummary("plan (lean)", [
       { label: "cycleHealth", hasData: !!health },
@@ -10617,7 +10882,8 @@ ${lines.join("\n")}`;
       recentlyShippedCapabilities: recentlyShippedLean,
       strategyReviewCadence,
       candidateTaskFullNotes: candidateTaskFullNotesLean,
-      foundationalTasksGuidance: computeFoundationalTasksGuidance(health.totalCycles, productBrief)
+      foundationalTasksGuidance: computeFoundationalTasksGuidance(health.totalCycles, productBrief),
+      siblingRepoWarning
     };
     const { label: leanTierLabel } = applyContextTier(ctx2, health.totalCycles);
     ctx2.contextTier = leanTierLabel;
@@ -10633,7 +10899,7 @@ ${lines.join("\n")}`;
     return { context: ctx2, contextHashes: newHashes2 };
   }
   t = startTimer();
-  const [decisions, reportsSinceCycle, log2, tasks, rawMetricsSnapshots, reviews, phases, dogfoodEntries, allBuildReports] = await Promise.all([
+  const [decisions, reportsSinceCycle, log2, tasks, rawMetricsSnapshots, reviews, phases, dogfoodEntries, allBuildReports, deferredRaw] = await Promise.all([
     adapter2.getActiveDecisions(),
     adapter2.getBuildReportsSince(health.totalCycles ?? 0),
     adapter2.getCycleLog(3),
@@ -10642,7 +10908,10 @@ ${lines.join("\n")}`;
     adapter2.getRecentReviews(5),
     adapter2.readPhases(),
     readDogfoodEntries(_config.projectRoot, 5, adapter2),
-    adapter2.getRecentBuildReports(50)
+    adapter2.getRecentBuildReports(50),
+    // task-2198: Deferred tasks queried SEPARATELY so they reach the planner as a
+    // re-triageable set without ever entering the selectable candidate pool.
+    adapter2.queryBoard({ status: ["Deferred"], contextTier: 2, compact: true })
   ]);
   timings["fullQueries"] = t();
   const reports = reportsSinceCycle.length > 0 ? reportsSinceCycle : allBuildReports.slice(0, 5);
@@ -10699,9 +10968,13 @@ ${lines.join("\n")}`;
   const briefExcluded = strippedTasks.filter(
     (t2) => t2.scopeClass === "brief" && !ACTIVE_STATUSES2.has(t2.status)
   );
-  const plannerTasks = strippedTasks.filter(
-    (t2) => (t2.priority !== "P3 Low" || ACTIVE_STATUSES2.has(t2.status)) && (t2.scopeClass !== "brief" || ACTIVE_STATUSES2.has(t2.status))
+  const plannerTasks = filterToPersonalBacklog(
+    strippedTasks.filter(
+      (t2) => (t2.priority !== "P3 Low" || ACTIVE_STATUSES2.has(t2.status)) && (t2.scopeClass !== "brief" || ACTIVE_STATUSES2.has(t2.status))
+    ),
+    planScope
   );
+  const deferredTasks = filterToPersonalBacklog(stripTasksForPlan(deferredRaw), planScope);
   if (p3Excluded.length > 0) {
     console.error(`[plan-perf] board tiering: excluded ${p3Excluded.length} P3 Low tasks from planner context`);
   }
@@ -10771,7 +11044,7 @@ ${logLines}`);
     activeDecisions: formatActiveDecisionsForPlan(decisions),
     recentBuildReports: formatBuildReports(cappedReports),
     cycleLog: formatCycleLog(log2),
-    board: formatBoardForPlan(plannerTasks, filters, health.totalCycles),
+    board: formatBoardForPlan(plannerTasks, filters, health.totalCycles, deferredTasks),
     northStar,
     methodologyMetrics: formatCycleMetrics(metricsSnapshots),
     recentReviews: formatReviews(reviews),
@@ -10794,7 +11067,8 @@ ${logLines}`);
     recentlyShippedCapabilities: formatRecentlyShippedCapabilities(reports),
     strategyReviewCadence: strategyReviewCadenceFull,
     candidateTaskFullNotes: formatCandidateTaskFullNotes(plannerTasks),
-    foundationalTasksGuidance: computeFoundationalTasksGuidance(health.totalCycles, productBrief)
+    foundationalTasksGuidance: computeFoundationalTasksGuidance(health.totalCycles, productBrief),
+    siblingRepoWarning
   };
   const { label: fullTierLabel } = applyContextTier(ctx, health.totalCycles);
   ctx.contextTier = fullTierLabel;
@@ -10860,7 +11134,10 @@ ${cleanContent}`;
     goals: data.cycleLogTitle ? [data.cycleLogTitle] : [],
     boardHealth: data.boardHealth || "",
     taskIds: cycleTaskIds,
-    contextHashes
+    contextHashes,
+    // task-2071 (MU-3): own the cycle by the planning member (pg defaults to the
+    // project owner when unset, so owner-operated plans stay correct).
+    ...options.ownerUserId ? { userId: options.ownerUserId } : {}
   };
   let dedupedNewTasks = data.newTasks ?? [];
   if (dedupedNewTasks.length > 0) {
@@ -10945,25 +11222,12 @@ ${cleanContent}`;
   const writeBackMs = writeBackTimer();
   console.error(`[plan-perf] transactionalWriteBack: total=${writeBackMs}ms`);
   const verifyWarnings = [];
-  try {
-    const [cycles, boardTasks] = await Promise.all([
-      adapter2.readCycles(),
-      adapter2.queryBoard({ status: ["In Cycle", "Backlog", "In Progress", "In Review"], compact: true })
-    ]);
-    const newCycle = cycles.find((s) => s.number === newCycleNumber);
-    if (!newCycle) {
-      verifyWarnings.push(`Post-write verification FAILED: cycle ${newCycleNumber} entity not found after commit \u2014 data may not have persisted`);
-    } else {
-      const expectedTaskCount = data.cycleTaskIds?.length ?? data.cycleHandoffs?.length ?? 0;
-      const actualCycleTasks = boardTasks.filter((t) => t.cycle === newCycleNumber).length;
-      if (expectedTaskCount > 0 && actualCycleTasks === 0) {
-        verifyWarnings.push(`Post-write verification FAILED: cycle ${newCycleNumber} exists but has 0 tasks assigned (expected ${expectedTaskCount}) \u2014 task cycle assignment may have failed`);
-      } else if (expectedTaskCount > 0 && actualCycleTasks < expectedTaskCount) {
-        verifyWarnings.push(`Post-write verification WARNING: cycle ${newCycleNumber} has ${actualCycleTasks} tasks but expected ${expectedTaskCount} \u2014 some task assignments may have failed`);
-      }
-    }
-  } catch {
-    verifyWarnings.push("Post-write verification: could not read cycles/tasks tables");
+  const expectedNewTasks = dedupedNewTasks.length;
+  const actualNewTasks = result.newTaskIdMap.size;
+  if (expectedNewTasks > 0 && actualNewTasks < expectedNewTasks) {
+    verifyWarnings.push(
+      `Plan write-back created ${actualNewTasks} of ${expectedNewTasks} new tasks the transaction was asked to create \u2014 investigate the planWriteBack handler. (This count is returned by the committed transaction, not a board re-read, so it is not a hosted read-lag artifact.)`
+    );
   }
   const allWarnings = [...result.warnings, ...verifyWarnings];
   const handoffCount = data.cycleHandoffs?.length ?? 0;
@@ -11258,7 +11522,9 @@ ${cleanContent}`;
         goals: data.cycleLogTitle ? [data.cycleLogTitle] : [],
         boardHealth: data.boardHealth || "",
         taskIds: cycleTaskIds,
-        contextHashes
+        contextHashes,
+        // task-2071 (MU-3): own the cycle by the planning member.
+        ...options.ownerUserId ? { userId: options.ownerUserId } : {}
       };
       await adapter2.createCycle(cycle);
     } catch (err) {
@@ -11300,7 +11566,7 @@ async function assertSingleActiveCycle(adapter2, opts = {}) {
   for (const c of cycles) {
     if (!newestByNumber.has(c.number)) newestByNumber.set(c.number, c);
   }
-  const blocking = [...newestByNumber.values()].filter((c) => c.status === "active" && c.number !== opts.allowNumber);
+  const blocking = [...newestByNumber.values()].filter((c) => c.status === "active" && c.number !== opts.allowNumber).filter((c) => opts.userId == null || c.userId === opts.userId);
   if (blocking.length === 0) return [];
   if (!opts.autoComplete) {
     const nums = blocking.map((c) => c.number).join(", ");
@@ -11319,7 +11585,7 @@ async function assertSingleActiveCycle(adapter2, opts = {}) {
   }
   return notes;
 }
-async function validateAndPrepare(adapter2, force) {
+async function validateAndPrepare(adapter2, force, callerUserId) {
   let mode;
   let cycleNumber;
   let strategyReviewWarning = "";
@@ -11358,7 +11624,7 @@ Run \`review_submit\` to clear them, or pass \`force: true\` to bypass this bloc
         );
       }
     }
-    const autoCompleted = await assertSingleActiveCycle(adapter2, { autoComplete: force === true });
+    const autoCompleted = await assertSingleActiveCycle(adapter2, { autoComplete: force === true, userId: callerUserId ?? void 0 });
     for (const note of autoCompleted) {
       console.error(`[plan] ${note}`);
     }
@@ -11390,7 +11656,8 @@ Run \`strategy_review\` first, or pass \`force: true\` to bypass this gate.`
 }
 async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber, contextHashes, planRunMeta) {
   const applyStartMs = Date.now();
-  await assertSingleActiveCycle(adapter2, { allowNumber: cycleNumber + 1 });
+  const applyScope = await resolvePlanScope(adapter2, config2);
+  await assertSingleActiveCycle(adapter2, { allowNumber: cycleNumber + 1, userId: applyScope.callerUserId ?? void 0 });
   const { displayText, data } = parseStructuredOutput(rawOutput);
   let resolvedDisplayText = displayText;
   let autoCommitNote = "";
@@ -11409,7 +11676,7 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
         cycleNumber,
         data,
         contextHashes,
-        { confirmCancellations: planRunMeta?.confirmCancellations === true }
+        { confirmCancellations: planRunMeta?.confirmCancellations === true, ownerUserId: applyScope.callerUserId ?? void 0 }
       );
       if (wbWarnings.length > 0) {
         writeBackWarnings = wbWarnings;
@@ -11484,7 +11751,8 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   const prepareTimer = startTimer();
   tracker?.mark("validate_and_prepare");
   let t = startTimer();
-  const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force);
+  const prepareScope = await resolvePlanScope(adapter2, config2);
+  const { mode, cycleNumber, strategyReviewWarning } = await validateAndPrepare(adapter2, force, prepareScope.callerUserId);
   const validateMs = t();
   if (handoffsOnly) {
     tracker?.mark("handoffs_only_assemble");
@@ -11530,8 +11798,8 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
   t = startTimer();
   const { context, contextHashes } = await assembleContext(adapter2, mode, config2, filters, focus);
   const assembleMs = t();
-  const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
-  if (mode !== "bootstrap" && context.productBrief.includes(TEMPLATE_MARKER)) {
+  const TEMPLATE_MARKER2 = "*Describe your project's core value proposition here.*";
+  if (mode !== "bootstrap" && context.productBrief.includes(TEMPLATE_MARKER2)) {
     throw new Error("TEMPLATE_BRIEF");
   }
   if (skipHandoffs) context.skipHandoffs = true;
@@ -11755,9 +12023,9 @@ function defaultHint(tool) {
     "release"
   ]);
   if (knownTools.has(tool)) {
-    return `Re-run \`${tool}\`. If the crash repeats, share the diagnostic JSON above with PAPI support.`;
+    return `Re-run \`${tool}\`. If the crash repeats, offer to submit it upstream \u2014 \`bug\` with report=true \u2014 and ask the user (a) notify when fixed? (b) OK for the PAPI team to reach out?`;
   }
-  return "Re-run the tool. If the crash repeats, share the diagnostic JSON above with PAPI support.";
+  return "Re-run the tool. If the crash repeats, offer to submit it upstream \u2014 `bug` with report=true \u2014 and ask the user (a) notify when fixed? (b) OK for the PAPI team to reach out?";
 }
 
 // src/lib/subagent-dispatch.ts
@@ -11899,12 +12167,174 @@ async function resolveLlmResponse(inlineResponse, filePath) {
   return { ok: true, llmResponse: contents };
 }
 
+// src/services/session-guidance.ts
+var DEFAULT_CALLER_KEY = "__default__";
+var sessionStates = /* @__PURE__ */ new Map();
+var MAX_SESSION_STATES = 1e3;
+function newSessionState(now) {
+  return {
+    toolCallCount: 0,
+    lastOrientAt: null,
+    releaseSinceLastOrient: false,
+    sessionStartedAt: now,
+    lastReviewListAt: null,
+    failureTimestamps: [],
+    consecutiveFailures: 0,
+    lastTouchedAt: now
+  };
+}
+function evictIfNeeded() {
+  if (sessionStates.size <= MAX_SESSION_STATES) return;
+  const entries = [...sessionStates.entries()].sort(
+    (a, b2) => a[1].lastTouchedAt - b2[1].lastTouchedAt
+  );
+  const overflow = sessionStates.size - MAX_SESSION_STATES;
+  for (let i = 0; i < overflow; i++) {
+    sessionStates.delete(entries[i][0]);
+  }
+}
+function getState(callerKey) {
+  const key = callerKey ?? DEFAULT_CALLER_KEY;
+  const now = Date.now();
+  let s = sessionStates.get(key);
+  if (!s) {
+    s = newSessionState(now);
+    sessionStates.set(key, s);
+    evictIfNeeded();
+  } else {
+    s.lastTouchedAt = now;
+  }
+  return s;
+}
+function callerKeyFromConfig(config2) {
+  return config2.projectId ?? config2.userId ?? void 0;
+}
+var CONTEXT_BLOAT_CALL_THRESHOLD = 40;
+var ORIENT_GAP_MS = 3 * 60 * 60 * 1e3;
+var REVIEW_LIST_GUARD_WINDOW_MS = 15 * 60 * 1e3;
+var FAILURE_WINDOW_MS = 30 * 60 * 1e3;
+var FAILURE_RATE_THRESHOLD = 8;
+var CONSECUTIVE_FAILURE_THRESHOLD = 4;
+function recordToolCall(name, callerKey) {
+  const state = getState(callerKey);
+  state.toolCallCount++;
+  if (name === "release") state.releaseSinceLastOrient = true;
+  if (name === "review_list") state.lastReviewListAt = Date.now();
+}
+function recordToolOutcome(success, callerKey) {
+  const state = getState(callerKey);
+  if (success) {
+    state.consecutiveFailures = 0;
+    return;
+  }
+  const now = Date.now();
+  state.consecutiveFailures++;
+  state.failureTimestamps.push(now);
+  const cutoff = now - FAILURE_WINDOW_MS;
+  state.failureTimestamps = state.failureTimestamps.filter((t) => t >= cutoff);
+}
+function wasReviewListSeenRecently(windowMs = REVIEW_LIST_GUARD_WINDOW_MS, callerKey) {
+  const state = getState(callerKey);
+  if (state.lastReviewListAt == null) return false;
+  return Date.now() - state.lastReviewListAt <= windowMs;
+}
+function markOrient(callerKey) {
+  const state = getState(callerKey);
+  state.lastOrientAt = Date.now();
+  state.releaseSinceLastOrient = false;
+}
+function getProjectConnectionBanner(projectName, projectSlug) {
+  if (!projectName || !projectSlug) return null;
+  return `[Connected: ${projectName} (${projectSlug})] \u2014 confirm this is the project you mean before I write to it. If it's wrong, don't proceed: pass \`project=<id>\` on the call to target a different project, or fix the project id in your MCP config (PAPI_PROJECT_ID for local, x-papi-project-id header for remote) and reconnect.`;
+}
+function detectContextDegradation(now = Date.now(), callerKey) {
+  const state = getState(callerKey);
+  if (state.consecutiveFailures >= CONSECUTIVE_FAILURE_THRESHOLD) {
+    return `Context degradation (clash): ${state.consecutiveFailures} tool calls failed in a row \u2014 the session may be stuck on a contradiction. Consider a fresh window after this task.`;
+  }
+  const cutoff = now - FAILURE_WINDOW_MS;
+  const recentFailures = state.failureTimestamps.filter((t) => t >= cutoff).length;
+  if (recentFailures >= FAILURE_RATE_THRESHOLD) {
+    const mins = Math.round(FAILURE_WINDOW_MS / 6e4);
+    return `Context degradation (distraction/confusion): ${recentFailures} tool failures in the last ${mins}min. A fresh window often clears this faster than pushing on.`;
+  }
+  return null;
+}
+async function buildSessionGuidance(callerKey) {
+  const state = getState(callerKey);
+  const signals = [];
+  const degradation = detectContextDegradation(Date.now(), callerKey);
+  if (degradation) signals.push(degradation);
+  if (state.toolCallCount > CONTEXT_BLOAT_CALL_THRESHOLD) {
+    signals.push(
+      `${state.toolCallCount} tool calls this session \u2014 context may be bloated. Consider starting a fresh window.`
+    );
+  }
+  if (state.lastOrientAt && Date.now() - state.lastOrientAt > ORIENT_GAP_MS) {
+    const hours = Math.round((Date.now() - state.lastOrientAt) / (60 * 60 * 1e3));
+    signals.push(
+      `${hours}h since last orient \u2014 session may be stale. Consider a fresh window for best results.`
+    );
+  }
+  if (state.releaseSinceLastOrient) {
+    signals.push(
+      "Release just ran \u2014 start a fresh session before the next `plan` to keep planning context clean."
+    );
+  }
+  return signals.slice(0, 3);
+}
+
+// src/lib/per-caller-cache.ts
+var DEFAULT_CALLER_KEY2 = "__default__";
+var MAX_PER_CALLER_ENTRIES = 1e3;
+var PerCallerCache = class {
+  constructor(max = MAX_PER_CALLER_ENTRIES) {
+    this.max = max;
+  }
+  store = /* @__PURE__ */ new Map();
+  /** Stash the prepare-phase value for this caller (undefined caller → default bucket). */
+  set(callerKey, value) {
+    this.store.set(callerKey ?? DEFAULT_CALLER_KEY2, { value, touchedAt: this.now() });
+    this.evictIfNeeded();
+  }
+  /**
+   * Read the caller's prepare-phase value WITHOUT removing it — used to peek the
+   * expected value during apply-validation (the prior singletons were read then
+   * cleared, so callers that need the clear-on-read semantics use `take`).
+   */
+  peek(callerKey) {
+    return this.store.get(callerKey ?? DEFAULT_CALLER_KEY2)?.value;
+  }
+  /** Read AND remove this caller's value — the prepare→apply handshake consumes it once. */
+  take(callerKey) {
+    const key = callerKey ?? DEFAULT_CALLER_KEY2;
+    const entry = this.store.get(key);
+    if (entry) this.store.delete(key);
+    return entry?.value;
+  }
+  /** Drop this caller's value without reading it. */
+  clear(callerKey) {
+    this.store.delete(callerKey ?? DEFAULT_CALLER_KEY2);
+  }
+  /** Test/inspection helper — number of live caller buckets. */
+  size() {
+    return this.store.size;
+  }
+  now() {
+    return Date.now();
+  }
+  evictIfNeeded() {
+    if (this.store.size <= this.max) return;
+    const entries = [...this.store.entries()].sort((a, b2) => a[1].touchedAt - b2[1].touchedAt);
+    const overflow = this.store.size - this.max;
+    for (let i = 0; i < overflow; i++) {
+      this.store.delete(entries[i][0]);
+    }
+  }
+};
+
 // src/tools/plan.ts
-var lastPrepareContextHashes;
-var lastPrepareUserMessage;
-var lastPrepareContextBytes;
-var lastPrepareCycleNumber;
-var lastPrepareSkipHandoffs;
+var planPrepareCache = new PerCallerCache();
 var planTool = {
   name: "plan",
   description: 'Run once per cycle to select tasks and generate BUILD HANDOFFs. Call after setup (first time) or after completing all builds AND running release for the previous cycle. Returns prioritised task recommendations with detailed implementation specs. NEVER call when unbuilt cycle tasks exist \u2014 build and release first. First call returns a planning prompt for you to execute (prepare phase). Then call again with mode "apply" and your output to write results. Use skip_handoffs=true for large backlogs \u2014 handoffs are then generated separately via `handoff_generate`.',
@@ -12046,6 +12476,7 @@ function formatPlanResult(result) {
 }
 async function handlePlan(adapter2, config2, args) {
   const toolMode = args.mode;
+  const callerKey = callerKeyFromConfig(config2);
   const filters = {};
   if (typeof args.phase === "string") filters.phase = args.phase;
   if (typeof args.module === "string") filters.module = args.module;
@@ -12068,11 +12499,12 @@ async function handlePlan(adapter2, config2, args) {
       const planMode = args.plan_mode || "full";
       const rawCycleNumber = args.cycle_number != null ? Number(args.cycle_number) : NaN;
       const strategyReviewWarning = args.strategy_review_warning || "";
-      const contextHashes = lastPrepareContextHashes;
-      const inputContext = lastPrepareUserMessage;
-      const contextBytes = lastPrepareContextBytes;
-      let expectedCycleNumber = lastPrepareCycleNumber;
-      const skipHandoffsCached = lastPrepareSkipHandoffs;
+      const prep = planPrepareCache.peek(callerKey);
+      const contextHashes = prep?.contextHashes;
+      const inputContext = prep?.userMessage;
+      const contextBytes = prep?.contextBytes;
+      let expectedCycleNumber = prep?.cycleNumber;
+      const skipHandoffsCached = prep?.skipHandoffs;
       const skipHandoffs = args.skip_handoffs === true || skipHandoffsCached === true;
       if (expectedCycleNumber === void 0 && process.env.PAPI_GUARD_RESTART === "true") {
         try {
@@ -12094,11 +12526,7 @@ async function handlePlan(adapter2, config2, args) {
         );
       }
       const cycleNumber = newCycleNumber - 1;
-      lastPrepareContextHashes = void 0;
-      lastPrepareUserMessage = void 0;
-      lastPrepareContextBytes = void 0;
-      lastPrepareCycleNumber = void 0;
-      lastPrepareSkipHandoffs = void 0;
+      planPrepareCache.clear(callerKey);
       let utilisation;
       if (inputContext) {
         try {
@@ -12127,11 +12555,13 @@ async function handlePlan(adapter2, config2, args) {
       }
       const skipHandoffs = args.skip_handoffs === true;
       const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker);
-      lastPrepareContextHashes = result.contextHashes;
-      lastPrepareUserMessage = result.userMessage;
-      lastPrepareContextBytes = result.contextBytes;
-      lastPrepareCycleNumber = result.cycleNumber;
-      lastPrepareSkipHandoffs = skipHandoffs || void 0;
+      planPrepareCache.set(callerKey, {
+        contextHashes: result.contextHashes,
+        userMessage: result.userMessage,
+        contextBytes: result.contextBytes,
+        cycleNumber: result.cycleNumber,
+        skipHandoffs: skipHandoffs || void 0
+      });
       const autoDispatchEnabled = process.env.PAPI_AUTO_DISPATCH !== "false";
       const autoDispatchThreshold = 50 * 1024;
       let dispatch;
@@ -13406,7 +13836,18 @@ ${lines.join("\n")}`;
   console.error(`[strategy_review] Context size: ${contextSize.toLocaleString()} chars (~${estimatedTokens.toLocaleString()} tokens)`);
   return context;
 }
-async function writeBack2(adapter2, cycleNumber, data, fullAnalysis) {
+function extractDecisionEvidence(ad, eventType, warnings) {
+  const isDeliberate = eventType === "validated" || eventType === "invalidated" || eventType === "modified";
+  const evidenceRef = ad.evidenceRef?.trim() || void 0;
+  const metricDelta = ad.metricDelta ?? null;
+  if (isDeliberate && !evidenceRef && !metricDelta?.metric) {
+    warnings?.push(
+      `${ad.id}: ${eventType} decision recorded without evidence_ref or metric_delta \u2014 ledger entry has no outcome pointer. Add evidence in the strategy output to make this decision queryable.`
+    );
+  }
+  return { evidenceRef, metricDelta };
+}
+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();
   const lastReviewCycle = await adapter2.getLastStrategyReviewCycle();
@@ -13460,6 +13901,7 @@ ${cleanContent}`;
         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,
@@ -13467,7 +13909,9 @@ ${cleanContent}`;
           cycle: cycleNumber,
           source: "strategy_review",
           sourceRef: `cycle-${cycleNumber}-review`,
-          detail: `Action: ${ad.action}`
+          detail: `Action: ${ad.action}`,
+          evidenceRef: evidence.evidenceRef,
+          metricDelta: evidence.metricDelta
         });
       } catch {
       }
@@ -13626,6 +14070,7 @@ async function processReviewOutput(adapter2, rawOutput, cycleNumber) {
   let slackWarning;
   let writeBackFailed;
   let phaseChanges;
+  const evidenceWarnings = [];
   if (!data) {
     const marker = "<!-- PAPI_STRUCTURED_OUTPUT -->";
     const hasMarker = rawOutput.includes(marker);
@@ -13639,7 +14084,7 @@ async function processReviewOutput(adapter2, rawOutput, cycleNumber) {
   }
   if (data) {
     try {
-      phaseChanges = await writeBack2(adapter2, cycleNumber, data, displayText);
+      phaseChanges = await writeBack2(adapter2, cycleNumber, data, displayText, evidenceWarnings);
     } catch (err) {
       writeBackFailed = err instanceof Error ? err.message : String(err);
       try {
@@ -13687,9 +14132,15 @@ ${report}`;
 **Discovery Canvas Auto-Populated:** ${populated.join(", ")}`;
     }
   }
+  const evidenceWarningSection = evidenceWarnings.length ? `
+
+---
+
+**Decision-ledger evidence warnings (${evidenceWarnings.length}):**
+${evidenceWarnings.map((w) => `- ${w}`).join("\n")}` : "";
   const fullText = phaseChanges?.length ? `${displayText}
 
-${formatPhaseChanges(phaseChanges)}${valueReportSection}${canvasSection}` : `${displayText}${valueReportSection}${canvasSection}`;
+${formatPhaseChanges(phaseChanges)}${valueReportSection}${canvasSection}${evidenceWarningSection}` : `${displayText}${valueReportSection}${canvasSection}${evidenceWarningSection}`;
   return {
     cycleNumber,
     displayText: fullText,
@@ -13996,6 +14447,7 @@ function buildStrategyChangeUserMessage(cycleNumber, text, productBrief, activeD
 async function processStrategyChangeOutput(adapter2, rawOutput, cycleNumber) {
   const { displayText, data } = parseStrategyChangeOutput(rawOutput);
   let writeBackFailed;
+  const evidenceWarnings = [];
   if (data) {
     try {
       const cleanTitle = data.cycleLogTitle.replace(/^(?:Cycle|Session)\s+\d+\s*—\s*/i, "").trim();
@@ -14023,6 +14475,7 @@ ${cleanContent}`;
             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, evidenceWarnings);
           try {
             await adapter2.appendDecisionEvent({
               decisionId: ad.id,
@@ -14030,7 +14483,9 @@ ${cleanContent}`;
               cycle: cycleNumber,
               source: "strategy_change",
               sourceRef: `cycle-${cycleNumber}-change`,
-              detail: `Action: ${ad.action}`
+              detail: `Action: ${ad.action}`,
+              evidenceRef: evidence.evidenceRef,
+              metricDelta: evidence.metricDelta
             });
           } catch {
           }
@@ -14050,7 +14505,13 @@ ${cleanContent}`;
       writeBackFailed = err instanceof Error ? err.message : String(err);
     }
   }
-  return { cycleNumber, displayText, writeBackFailed };
+  const fullText = evidenceWarnings.length ? `${displayText}
+
+---
+
+**Decision-ledger evidence warnings (${evidenceWarnings.length}):**
+${evidenceWarnings.map((w) => `- ${w}`).join("\n")}` : displayText;
+  return { cycleNumber, displayText: fullText, writeBackFailed };
 }
 async function prepareStrategyChange(adapter2, text) {
   let cycleNumber;
@@ -14189,11 +14650,10 @@ Confidence: ${input.confidence}. Captured mid-conversation via strategy_change c
 }
 
 // src/tools/strategy.ts
-var lastReviewUserMessage;
-var lastReviewContextBytes;
+var reviewPrepareCache = new PerCallerCache();
 var strategyReviewTool = {
   name: "strategy_review",
-  description: 'Run a Strategy Review \u2014 assesses project direction, velocity, and Active Decisions. Produces recommendations and potential AD updates that feed into the next plan. Offered every 5 cycles; hard-blocked at 7+ overdue cycles. Run in its own dedicated session \u2014 do not mix with building. First call returns a review prompt for you to execute (prepare phase). Then call again with mode "apply" and your output. Pass `force: true` to run before the cadence gate.',
+  description: 'Run a Strategy Review \u2014 assesses project direction, velocity, and Active Decisions. Produces recommendations and potential AD updates that feed into the next plan. Offered every 5 cycles; hard-blocked at 7+ overdue cycles. If your current session is already heavy with build context, running the review in a fresh session gives cleaner output \u2014 but a genuinely fresh session needs no restart, just run it. First call returns a review prompt for you to execute (prepare phase). Then call again with mode "apply" and your output. Pass `force: true` to run before the cadence gate.',
   annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
@@ -14258,7 +14718,7 @@ var strategyAgendaTool = {
 };
 var strategyChangeTool = {
   name: "strategy_change",
-  description: 'Apply a strategic shift to the project. Three modes: "capture" for lightweight mid-conversation decision capture (no LLM round-trip), "prepare" to get a change prompt for full analysis, "apply" to persist analysis output. Use "capture" when you detect a strategic decision in conversation and want to persist it quickly without disrupting the build flow.',
+  description: 'Apply a strategic shift to the project. Three modes: "capture" for lightweight mid-conversation decision capture (no LLM round-trip), "prepare" to get a change prompt for full analysis, "apply" to persist analysis output. Use "capture" when you detect a strategic decision in conversation and want to persist it quickly without disrupting the build flow. In "capture" mode, pass north_star to directly set/update the project North Star (no decision text needed).',
   annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
@@ -14296,6 +14756,10 @@ var strategyChangeTool = {
       confidence_only: {
         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.`
+      },
+      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.'
       }
     },
     required: []
@@ -14304,6 +14768,7 @@ var strategyChangeTool = {
 async function handleStrategyReview(adapter2, config2, args) {
   const toolMode = args.mode;
   const force = args.force === true;
+  const callerKey = callerKeyFromConfig(config2);
   const tracker = new ProgressTracker(toolMode === "apply" ? "apply_validate" : "prepare_validate");
   try {
     if (toolMode === "apply") {
@@ -14316,10 +14781,9 @@ async function handleStrategyReview(adapter2, config2, args) {
       }
       const llmResponse = resolved.llmResponse;
       const cycleNumber = typeof args.cycle_number === "number" ? args.cycle_number : 0;
-      const inputContext = lastReviewUserMessage;
-      const contextBytes = lastReviewContextBytes;
-      lastReviewUserMessage = void 0;
-      lastReviewContextBytes = void 0;
+      const prep = reviewPrepareCache.take(callerKey);
+      const inputContext = prep?.userMessage;
+      const contextBytes = prep?.contextBytes;
       const result = await applyStrategyReviewOutput(adapter2, llmResponse, cycleNumber, tracker);
       let utilisation;
       if (inputContext) {
@@ -14384,14 +14848,17 @@ ${recLines.join("\n")}
       if ("notDue" in result) {
         return textResponse(result.message);
       }
-      lastReviewUserMessage = result.userMessage;
-      lastReviewContextBytes = Buffer.byteLength(result.userMessage, "utf-8");
+      const reviewContextBytes = Buffer.byteLength(result.userMessage, "utf-8");
+      reviewPrepareCache.set(callerKey, {
+        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 && lastReviewContextBytes > autoDispatchThreshold) {
+      } else if (autoDispatchEnabled && reviewContextBytes > autoDispatchThreshold) {
         dispatch = "subagent";
       } else {
         dispatch = "inline";
@@ -14402,7 +14869,7 @@ ${recLines.join("\n")}
           cycleNumber: result.cycleNumber,
           systemPrompt: result.systemPrompt,
           userMessage: result.userMessage,
-          contextBytes: lastReviewContextBytes
+          contextBytes: reviewContextBytes
         });
         return textResponse(dispatchPrompt);
       }
@@ -14499,9 +14966,25 @@ async function handleStrategyChange(adapter2, _config, args) {
   const toolMode = args.mode;
   try {
     if (toolMode === "capture") {
+      const northStar = args.north_star;
+      if (northStar && northStar.trim()) {
+        if (!adapter2.upsertNorthStar) {
+          return errorResponse("North Star write is not available on this adapter (requires the pg/proxy or md adapter).");
+        }
+        const health = await adapter2.getCycleHealth();
+        const cycleNumber = health.totalCycles;
+        await adapter2.upsertNorthStar(northStar.trim(), cycleNumber);
+        return textResponse(
+          `**North Star set** (Cycle ${cycleNumber})
+
+${northStar.trim()}
+
+orient and the project foundation will read this value.`
+        );
+      }
       const text2 = args.text;
       if (!text2 || !text2.trim()) {
-        return errorResponse("text is required for capture mode. Describe the decision.");
+        return errorResponse("text is required for capture mode. Describe the decision (or pass north_star to set the project North Star).");
       }
       const adId = args.ad_id;
       const confidence = args.confidence ?? "MEDIUM";
@@ -14612,7 +15095,17 @@ async function viewBoard(adapter2, phaseFilter, options) {
   const allTasks = await adapter2.queryBoard(
     Object.keys(queryOptions).length > 0 ? queryOptions : void 0
   );
-  allTasks.sort((a, b2) => {
+  let filtered = allTasks;
+  if (options?.cycle != null) {
+    filtered = filtered.filter((t) => t.cycle === options.cycle);
+  }
+  if (options?.query && options.query.trim()) {
+    const q = options.query.trim().toLowerCase();
+    filtered = filtered.filter(
+      (t) => t.title.toLowerCase().includes(q) || (t.notes?.toLowerCase().includes(q) ?? false)
+    );
+  }
+  filtered.sort((a, b2) => {
     const aTier = STATUS_TIER[a.status] ?? 4;
     const bTier = STATUS_TIER[b2.status] ?? 4;
     if (aTier !== bTier) return aTier - bTier;
@@ -14624,10 +15117,10 @@ async function viewBoard(adapter2, phaseFilter, options) {
     const bDate = b2.createdAt ? String(b2.createdAt) : "";
     return bDate.localeCompare(aDate);
   });
-  const total = allTasks.length;
+  const total = filtered.length;
   const offset = options?.offset ?? 0;
   const limit = options?.limit ?? 50;
-  const paged = allTasks.slice(offset, offset + limit);
+  const paged = filtered.slice(offset, offset + limit);
   return {
     tasks: paged,
     total,
@@ -14684,11 +15177,23 @@ async function archiveTasks(adapter2, phases, statuses) {
 // src/tools/board.ts
 var boardViewTool = {
   name: "board_view",
-  description: 'View the Board. By default shows active tasks only (excludes Done/Cancelled), sorted by priority, limited to 50. Use status="all" to see everything. Use mode="summary" for counts only (no task details). Does not call the Anthropic API.',
+  description: 'View the Board. To find a SPECIFIC task or subset, FILTER FIRST \u2014 do not dump the whole board: pass task_id for one task (full detail), query="<text>" for a title/notes substring match, or cycle=<n> for one cycle. Combine with status/phase. By default shows active tasks only (excludes Done/Cancelled), sorted by priority, limited to 50; titles are truncated in the table (single-task lookup shows the full title). Use status="all" to see everything, mode="summary" for counts only. Does not call the Anthropic API.',
   annotations: { readOnlyHint: true, destructiveHint: false },
   inputSchema: {
     type: "object",
     properties: {
+      task_id: {
+        type: "string",
+        description: 'Direct lookup of a single task by its display_id (e.g. "task-2154"). Returns full untruncated detail for just that task \u2014 no board scan. Takes precedence over the list filters.'
+      },
+      query: {
+        type: "string",
+        description: "Case-insensitive substring match on task title OR notes. Returns only matching tasks \u2014 use this instead of dumping the whole board to find something."
+      },
+      cycle: {
+        type: "number",
+        description: "Filter to tasks assigned to this cycle number."
+      },
       phase: {
         type: "string",
         description: 'Filter to tasks in this phase (e.g. "Phase 5").'
@@ -14828,14 +15333,45 @@ var boardEditTool = {
       cycle: {
         type: ["number", "null"],
         description: "Cycle assignment. Pass a cycle number to assign, or null to remove from any cycle. Validated against existing cycles. Replaces the prior workaround of editing cycle_tasks.cycle directly via SQL."
-      }
-    },
-    required: ["task_id"]
-  }
-};
+      },
+      estimated_effort: {
+        type: "string",
+        enum: ["XS", "S", "M", "L", "XL"],
+        description: "task-2182: correct the estimated effort on this task's LATEST build report (fixes a mis-recorded estimate). Updates the build_reports row, not the task \u2014 feeds the next estimation-accuracy recompute."
+      },
+      actual_effort: {
+        type: "string",
+        enum: ["XS", "S", "M", "L", "XL"],
+        description: "task-2182: correct the actual effort on this task's LATEST build report (fixes a mis-recorded actual)."
+      }
+    },
+    required: ["task_id"]
+  }
+};
 function pad(value, width) {
   return value.length >= width ? value : value + " ".repeat(width - value.length);
 }
+var TITLE_MAX = 80;
+function truncateTitle(title) {
+  return title.length > TITLE_MAX ? `${title.slice(0, TITLE_MAX - 1)}\u2026` : title;
+}
+function formatSingleTask(t) {
+  const lines = [
+    `**${t.id} \u2014 ${t.title}**`,
+    "",
+    `- **Status:** ${t.status}`,
+    `- **Priority:** ${t.priority}`,
+    `- **Cycle:** ${t.cycle != null ? t.cycle : "-"}`,
+    `- **Phase:** ${t.phase ?? "-"}`,
+    `- **Module:** ${t.module ?? "-"}`,
+    `- **Epic:** ${t.epic ?? "-"}`,
+    `- **Effort:** ${t.complexity ?? "-"}`,
+    `- **Source:** ${t.source ?? "-"}`
+  ];
+  if (t.notes?.trim()) lines.push(`- **Notes:** ${t.notes.trim()}`);
+  if (t.why?.trim()) lines.push(`- **Why:** ${t.why.trim()}`);
+  return lines.join("\n");
+}
 function formatBoard(result) {
   if (result.tasks.length === 0) {
     return "No tasks found.";
@@ -14844,7 +15380,7 @@ function formatBoard(result) {
   const rows = result.tasks.map((t) => [
     t.priority,
     t.id,
-    t.title,
+    truncateTitle(t.title),
     t.status,
     t.cycle != null ? String(t.cycle) : "-",
     t.phase ?? "-",
@@ -14896,11 +15432,19 @@ async function handleBoardView(adapter2, args) {
     const summary = await viewBoardSummary(adapter2);
     return textResponse(formatSummary(summary));
   }
+  const taskIdArg = args.task_id ?? args.display_id;
+  if (taskIdArg) {
+    const task = await adapter2.getTask(taskIdArg);
+    if (!task) return errorResponse(`Task ${taskIdArg} not found.`);
+    return textResponse(formatSingleTask(task));
+  }
   const result = await viewBoard(adapter2, void 0, {
     phase: args.phase,
     status: args.status,
     limit: args.limit,
-    offset: args.offset
+    offset: args.offset,
+    query: args.query,
+    cycle: args.cycle
   });
   let output = formatBoard(result);
   try {
@@ -15022,6 +15566,15 @@ async function handleBoardEdit(adapter2, args) {
       changes.push(field);
     }
   }
+  const effortCorrection = {};
+  if (typeof args.estimated_effort === "string") {
+    effortCorrection.estimatedEffort = args.estimated_effort;
+    changes.push("estimated_effort");
+  }
+  if (typeof args.actual_effort === "string") {
+    effortCorrection.actualEffort = args.actual_effort;
+    changes.push("actual_effort");
+  }
   const notesMode = args.notes_mode;
   if (notesMode === "clear" && !changes.includes("notes")) {
     changes.push("notes");
@@ -15106,7 +15659,15 @@ ${existing}` : entry;
     if (updates.status === "Cancelled" && !updates.cancelledBy) {
       updates.cancelledBy = "user";
     }
-    await adapter2.updateTask(taskId, updates);
+    if (effortCorrection.estimatedEffort || effortCorrection.actualEffort) {
+      if (!adapter2.correctLatestBuildReportEffort) {
+        return errorResponse("Correcting build-report effort requires a database adapter (pg). The md adapter does not support it.");
+      }
+      await adapter2.correctLatestBuildReportEffort(taskId, effortCorrection);
+    }
+    if (Object.keys(updates).length > 0) {
+      await adapter2.updateTask(taskId, updates);
+    }
     if ((updates.status === "Done" || updates.status === "Cancelled") && adapter2.updateDogfoodEntryStatus) {
       try {
         const dogfoodLog = await adapter2.getDogfoodLog?.(50) ?? [];
@@ -15383,7 +15944,7 @@ This is a one-time check at the start of the cycle, not per-task. It catches sco
 Every 5 cycles, PAPI offers a strategy review \u2014 a deep analysis of velocity, estimation accuracy, active decisions, and project direction.
 
 - **Don't skip them.** They're where compounding value comes from.
-- Strategy reviews run in their own session \u2014 don't mix with building.
+- If your session is already heavy with build context, run the review fresh for cleaner output \u2014 a genuinely fresh session needs no restart.
 - Reviews produce recommendations that feed into the next plan.
 - If the review recommends AD changes, use \`strategy_change\` to apply them.
 
@@ -15781,6 +16342,9 @@ async function ensurePapiPermission(projectRoot) {
   } catch {
   }
 }
+var TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
+var CONVENTIONS_SENTINEL = "<!-- PAPI_CONVENTIONS -->";
+var CONVENTIONS_HEADING = "## Code Style Conventions";
 async function applySetupOutputs(adapter2, config2, input, collector, briefText, adSeedText, conventionsText) {
   const warnings = [];
   await adapter2.updateProductBrief(briefText);
@@ -15818,13 +16382,21 @@ async function applySetupOutputs(adapter2, config2, input, collector, briefText,
     }
   }
   let seededAds = 0;
+  let skippedAds = 0;
   if (adSeedText) {
     try {
       const cleaned = adSeedText.replace(/^```(?:json)?\s*/m, "").replace(/\s*```\s*$/m, "").trim();
       const ads = JSON.parse(cleaned);
       if (Array.isArray(ads)) {
+        const existingAdIds = adapter2.getActiveDecisions ? new Set(
+          (await adapter2.getActiveDecisions({ includeRetired: true }).catch(() => [])).map((a) => a.displayId)
+        ) : /* @__PURE__ */ new Set();
         for (const ad of ads) {
           if (ad.id && ad.body) {
+            if (existingAdIds.has(ad.id) && !input.force) {
+              skippedAds++;
+              continue;
+            }
             if (adapter2.upsertActiveDecision) {
               const title = ad.title || ad.body.split("\n")[0].replace(/^#+\s*/, "").slice(0, 120);
               await adapter2.upsertActiveDecision(ad.id, ad.body, title, ad.confidence || "MEDIUM", 0);
@@ -15842,7 +16414,11 @@ async function applySetupOutputs(adapter2, config2, input, collector, briefText,
       );
       seededAds = 0;
     }
-    if (seededAds === 0 && adSeedText) {
+    if (skippedAds > 0) {
+      warnings.push(
+        `Active Decisions: detected ${skippedAds} existing AD(s) and left them untouched${seededAds > 0 ? `; created ${seededAds} new one(s)` : " (none new to create)"}.`
+      );
+    } else if (seededAds === 0 && adSeedText) {
       if (!warnings.some((w) => w.startsWith("AD seeding failed"))) {
         warnings.push(
           "AD seeding produced 0 active decisions \u2014 the JSON may be valid but empty or missing required `id` and `body` fields."
@@ -15851,17 +16427,29 @@ async function applySetupOutputs(adapter2, config2, input, collector, briefText,
     }
   }
   if (conventionsText?.trim()) {
+    const conventionsBlock = `${CONVENTIONS_SENTINEL}
+${conventionsText.trim()}
+`;
     if (config2.adapterType === "proxy") {
       collector.add({
         path: "CLAUDE.md",
-        content: "\n" + conventionsText.trim() + "\n",
+        content: "\n" + conventionsBlock,
         mode: "append"
       });
+      warnings.push(
+        `Conventions: append the block to CLAUDE.md only if it does not already contain \`${CONVENTIONS_SENTINEL}\` or a "${CONVENTIONS_HEADING}" section.`
+      );
     } else {
       try {
         const claudeMdPath = join5(config2.projectRoot, "CLAUDE.md");
         const existing = await readFile4(claudeMdPath, "utf-8");
-        await writeFile2(claudeMdPath, existing + "\n" + conventionsText.trim() + "\n", "utf-8");
+        if (existing.includes(CONVENTIONS_SENTINEL) || existing.includes(CONVENTIONS_HEADING)) {
+          warnings.push(
+            "Conventions: CLAUDE.md already contains a conventions block \u2014 skipped append to avoid duplication."
+          );
+        } else {
+          await writeFile2(claudeMdPath, existing + "\n" + conventionsBlock, "utf-8");
+        }
       } catch {
       }
     }
@@ -16048,8 +16636,8 @@ async function prepareSetup(adapter2, config2, input) {
       config2.adapterType === "proxy" ? "Could not read Product Brief from PAPI. Check your PAPI connection (OAuth sign-in, bearer token, or PAPI_DATA_API_KEY) and that PAPI_PROJECT_ID matches the project you want to scaffold." : config2.adapterType === "pg" ? "Could not read Product Brief from database. Check DATABASE_URL and PAPI_PROJECT_ID are set correctly in your MCP config." : "Could not read PRODUCT_BRIEF.md. Ensure .papi/ directory exists."
     );
   }
-  const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
-  const briefHasRealContent = existingBrief.trim().length > 0 && !existingBrief.includes(TEMPLATE_MARKER);
+  const TEMPLATE_MARKER2 = "*Describe your project's core value proposition here.*";
+  const briefHasRealContent = existingBrief.trim().length > 0 && !existingBrief.includes(TEMPLATE_MARKER2);
   const briefAlreadyExists = briefHasRealContent && !input.force;
   const canScanFilesystem = hasLocalWorkspace();
   const warnings = [];
@@ -16160,6 +16748,15 @@ async function prepareSetup(adapter2, config2, input) {
       targetUsers: input.targetUsers,
       codebaseContext: codebaseSummary
     })
+  } : input.description?.trim() ? {
+    system: VISION_TASKS_SYSTEM,
+    user: buildVisionTasksPrompt({
+      projectName: input.projectName,
+      description: input.description,
+      targetUsers: input.targetUsers,
+      problems: input.problems,
+      projectType: input.projectType
+    })
   } : void 0;
   return {
     createdProject,
@@ -16181,7 +16778,6 @@ async function prepareSetup(adapter2, config2, input) {
 async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText) {
   const collector = new FileWriteCollector();
   const createdProject = await scaffoldPapiDir(adapter2, config2, input, collector);
-  const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
   let effectiveBriefText = briefText;
   let briefRegenerated = false;
   if (!effectiveBriefText.trim()) {
@@ -16240,7 +16836,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
           `100% overlap \u2014 all ${validTasks.length} initial task(s) already exist in the board (matched by title). Re-run without initial_tasks_response, or add force: true to skip the overlap guard.`
         );
       }
-      const MAX_INITIAL_TASKS = 10;
+      const MAX_INITIAL_TASKS = 20;
       const failedTasks = [];
       for (const task of toCreate.slice(0, MAX_INITIAL_TASKS)) {
         try {
@@ -16516,10 +17112,11 @@ ${result.seededAds} Active Decision${result.seededAds > 1 ? "s" : ""} seeded bas
   const taskNote = result.createdTasks > 0 || (result.tasksSkipped ?? 0) > 0 ? (() => {
     const created = result.createdTasks > 0 ? `${result.createdTasks} initial backlog task${result.createdTasks > 1 ? "s" : ""} created` : "";
     const skipped = (result.tasksSkipped ?? 0) > 0 ? `${result.tasksSkipped} duplicate${(result.tasksSkipped ?? 0) > 1 ? "s" : ""} skipped` : "";
+    const idea = result.createdTasks < 8 ? ` Your backlog is light \u2014 add more with \`idea "<what you want to build>"\` so your next plan has fuel.` : ` Capture new ideas any time with \`idea "<...>"\` \u2014 mid-build or after a cycle, it all feeds the next plan.`;
     return `
 
-${[created, skipped].filter(Boolean).join(", ")}.`;
-  })() : "";
+${[created, skipped].filter(Boolean).join(", ")}.${idea}`;
+  })() : '\n\nNo starter tasks yet. Describe what you want to build, or seed the board with `idea "<what you want to build>"`, so your first `plan` has something to work from.';
   const constraintsHint = !constraints ? '\n\nTip: consider adding `constraints` (e.g. "must use PostgreSQL", "HIPAA compliant", "offline-first") to improve Active Decision seeding.' : "";
   const editorNote = result.cursorScaffolded ? "\n\nCursor detected \u2014 `.cursor/rules/papi.mdc` scaffolded alongside CLAUDE.md." : "";
   const gitignoreNote = result.gitignoreNote ? `
@@ -16619,6 +17216,17 @@ PAPI needs the project name. Description and target users are optional \u2014 th
           ""
         );
       }
+      if (result.briefPrompt && !result.briefAlreadyExists) {
+        sections.push(
+          `**\u{1F4C4} Before you write the brief \u2014 does the user already have a PRD, brief, spec, or design doc?**`,
+          `A brief generated from the user's real spec produces a far better first plan than a generic scaffold.`,
+          `1. **Ask:** "Do you already have a PRD, brief, spec, or design doc for this \u2014 in this folder or anywhere else (even another directory)? Point me at it or paste it in."`,
+          `2. **Scan the working directory yourself** for likely files and offer them: \`PRD*\`, \`README*\`, \`SPEC*\`/\`spec*\`, design docs, and \`*.md\` under \`docs/\`.`,
+          `3. If the user supplies or approves any, **re-run \`setup\` with \`sources: "<comma-separated file paths>"\`** (local stdio install) so the brief is generated FROM the real doc. Over a hosted/remote connector PAPI can't read local paths \u2014 paste the content into \`description\` instead.`,
+          `If there's no existing doc, skip this and generate the brief from what you know \u2014 the zero-doc path is fully supported.`,
+          ""
+        );
+      }
       sections.push(
         `Generate the outputs below, then call \`setup\` again with:`,
         `- \`mode\`: "apply"`,
@@ -17000,8 +17608,16 @@ function inferCycleFromVersion(version) {
   const m = version.match(/^v0\.(\d+)\./);
   return m ? parseInt(m[1], 10) : 0;
 }
-async function resolveCycleToClose(adapter2, version) {
+async function resolveCycleToClose(adapter2, version, callerUserId) {
   if (adapter2) {
+    if (callerUserId) {
+      try {
+        const mine = callerUserId.trim().toLowerCase();
+        const owned = (await adapter2.readCycles()).filter((c) => c.status === "active" && c.userId?.trim().toLowerCase() === mine).map((c) => c.number);
+        if (owned.length > 0) return Math.max(...owned);
+      } catch {
+      }
+    }
     try {
       const health = await adapter2.getCycleHealth();
       if (health.totalCycles > 0) return health.totalCycles;
@@ -17010,21 +17626,11 @@ async function resolveCycleToClose(adapter2, version) {
   }
   return inferCycleFromVersion(version);
 }
-async function createRelease(config2, branch, version, adapter2, cycleNum, options) {
-  const collector = new FileWriteCollector();
-  if (!isGitAvailable()) {
-    throw new Error("git is not available.");
-  }
-  if (!isGitRepo(config2.projectRoot)) {
-    throw new Error("not a git repository.");
-  }
-  if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
-    throw new Error("working directory has uncommitted changes. Commit or stash them before releasing.");
-  }
+async function closeCycleState(config2, adapter2, version, cycleNum, options) {
   const warnings = [];
   const force = options?.force ?? false;
   const skipVersion = options?.skipVersion ?? false;
-  const resolvedCycleNum = cycleNum && cycleNum > 0 ? cycleNum : await resolveCycleToClose(adapter2, version);
+  const resolvedCycleNum = cycleNum && cycleNum > 0 ? cycleNum : await resolveCycleToClose(adapter2, version, options?.callerUserId);
   const versionRegexCycle = inferCycleFromVersion(version);
   if (resolvedCycleNum > 0 && versionRegexCycle > 0 && versionRegexCycle !== resolvedCycleNum) {
     warnings.push(
@@ -17068,30 +17674,6 @@ To override, pass force=true (emits a telemetry warning).`
       warnings.push(`Release-readiness check failed (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  if (adapter2) {
-    try {
-      const resolvedBase = resolveBaseBranch(config2.projectRoot, branch);
-      const orphans = listOrphanFeatBranches(config2.projectRoot, resolvedBase);
-      const allDoneOrphans = [];
-      for (const orphanBranch of orphans) {
-        const taskIds = getTaskIdsOnBranch(config2.projectRoot, orphanBranch, resolvedBase);
-        if (taskIds.length === 0) continue;
-        const tasks = await adapter2.getTasks(taskIds);
-        if (tasks.length === 0) continue;
-        const allDone = tasks.every((t) => t.status === "Done");
-        if (allDone) {
-          allDoneOrphans.push(`${orphanBranch} (${taskIds.join(", ")})`);
-        }
-      }
-      if (allDoneOrphans.length > 0) {
-        warnings.push(
-          `Orphan branches detected \u2014 ${allDoneOrphans.length} feature branch(es) have all tasks Done but are not merged into ${resolvedBase}. Merge or delete before next release: ${allDoneOrphans.join("; ")}`
-        );
-      }
-    } catch (err) {
-      warnings.push(`Orphan-branch detection failed (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
   if (adapter2) {
     const currentCycle = resolvedCycleNum;
     if (currentCycle > 0) {
@@ -17115,9 +17697,64 @@ To override, pass force=true (emits a telemetry warning).`
         const msg = `createCycle (mark complete) failed for cycle ${currentCycle}: ${err instanceof Error ? err.message : String(err)}`;
         console.error(`[release] ${msg}`);
         throw new Error(
-          `Release blocked \u2014 could not mark cycle ${currentCycle} complete in the DB before tagging. ${err instanceof Error ? err.message : String(err)}. Resolve the DB error and re-run \`release\`.`
+          `Release blocked \u2014 could not mark cycle ${currentCycle} complete in the DB. ${err instanceof Error ? err.message : String(err)}. Resolve the DB error and re-run \`release\`.`
         );
       }
+      if (adapter2.appendCycleMetrics && adapter2.getBuildReportsSince) {
+        try {
+          const cycleReports = (await adapter2.getBuildReportsSince(currentCycle)).filter((r) => r.cycle === currentCycle);
+          const [snapshot] = computeSnapshotsFromBuildReports(cycleReports);
+          if (snapshot) await adapter2.appendCycleMetrics(snapshot);
+        } catch (err) {
+          console.error(
+            `[release] cycle-metrics snapshot write failed for cycle ${currentCycle} (non-blocking): ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    }
+  }
+  return { resolvedCycleNum, warnings, force, skipVersion };
+}
+async function createRelease(config2, branch, version, adapter2, cycleNum, options) {
+  const collector = new FileWriteCollector();
+  if (!isGitAvailable()) {
+    throw new Error("git is not available.");
+  }
+  if (!isGitRepo(config2.projectRoot)) {
+    throw new Error("not a git repository.");
+  }
+  if (hasUncommittedChanges(config2.projectRoot, AUTO_WRITTEN_PATHS)) {
+    throw new Error("working directory has uncommitted changes. Commit or stash them before releasing.");
+  }
+  const { resolvedCycleNum, warnings, skipVersion } = await closeCycleState(
+    config2,
+    adapter2,
+    version,
+    cycleNum,
+    options
+  );
+  if (adapter2) {
+    try {
+      const resolvedBase = resolveBaseBranch(config2.projectRoot, branch);
+      const orphans = listOrphanFeatBranches(config2.projectRoot, resolvedBase);
+      const allDoneOrphans = [];
+      for (const orphanBranch of orphans) {
+        const taskIds = getTaskIdsOnBranch(config2.projectRoot, orphanBranch, resolvedBase);
+        if (taskIds.length === 0) continue;
+        const tasks = await adapter2.getTasks(taskIds);
+        if (tasks.length === 0) continue;
+        const allDone = tasks.every((t) => t.status === "Done");
+        if (allDone) {
+          allDoneOrphans.push(`${orphanBranch} (${taskIds.join(", ")})`);
+        }
+      }
+      if (allDoneOrphans.length > 0) {
+        warnings.push(
+          `\u26A0\uFE0F DATA-INTEGRITY \u2014 ${allDoneOrphans.length} branch(es) have all tasks marked **Done** but were NEVER merged into ${resolvedBase}: their Done status is not backed by git. Merge or delete before next release: ${allDoneOrphans.join("; ")}`
+        );
+      }
+    } catch (err) {
+      warnings.push(`Orphan-branch detection failed (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
     }
   }
   const checkout = checkoutBranch(config2.projectRoot, branch);
@@ -17148,6 +17785,21 @@ To override, pass force=true (emits a telemetry warning).`
       }
     }
   }
+  if (adapter2 && resolvedCycleNum > 0) {
+    try {
+      const stampedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const doneCycleTasks = (await adapter2.queryBoard()).filter(
+        (t) => t.cycle === resolvedCycleNum && t.status === "Done"
+      );
+      for (const t of doneCycleTasks) {
+        try {
+          await adapter2.updateTask(t.id, { mergedAt: stampedAt });
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
   const latestTag = getLatestTag(config2.projectRoot);
   const changelogPath = join7(config2.projectRoot, "CHANGELOG.md");
   if (!latestTag) {
@@ -17207,60 +17859,6 @@ To override, pass force=true (emits a telemetry warning).`
 // src/tools/release.ts
 init_git();
 
-// src/lib/owner-identity.ts
-function isProjectOwner(callerUserId, ownerUserId) {
-  if (!callerUserId || !ownerUserId) return false;
-  const caller = callerUserId.trim().toLowerCase();
-  const owner = ownerUserId.trim().toLowerCase();
-  if (caller.length === 0 || owner.length === 0) return false;
-  return caller === owner;
-}
-async function resolveOwnerGate(adapter2, config2) {
-  if (typeof adapter2.getOwnerIdentity === "function") {
-    try {
-      const identity = await adapter2.getOwnerIdentity();
-      const callerUserId = identity.callerUserId ?? config2.userId ?? null;
-      return {
-        enforced: true,
-        callerIsOwner: isProjectOwner(callerUserId, identity.ownerUserId),
-        callerUserId,
-        ownerUserId: identity.ownerUserId
-      };
-    } catch (err) {
-      return {
-        enforced: true,
-        callerIsOwner: false,
-        callerUserId: config2.userId ?? null,
-        ownerUserId: null,
-        resolutionError: err instanceof Error ? err.message : String(err)
-      };
-    }
-  }
-  if (typeof adapter2.getProjectOwnerUserId === "function") {
-    let ownerUserId = null;
-    let resolutionError;
-    try {
-      ownerUserId = await adapter2.getProjectOwnerUserId();
-    } catch (err) {
-      resolutionError = err instanceof Error ? err.message : String(err);
-    }
-    const callerUserId = config2.userId ?? null;
-    return {
-      enforced: true,
-      callerIsOwner: isProjectOwner(callerUserId, ownerUserId),
-      callerUserId,
-      ownerUserId,
-      ...resolutionError !== void 0 ? { resolutionError } : {}
-    };
-  }
-  return {
-    enforced: false,
-    callerIsOwner: true,
-    callerUserId: config2.userId ?? null,
-    ownerUserId: null
-  };
-}
-
 // src/lib/registry-updates.ts
 import { execFile } from "child_process";
 import { promisify } from "util";
@@ -17371,21 +17969,32 @@ function parseGithubOwner(input) {
 function sanitiseBranchSuffix(branch) {
   return branch.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-async function postReleaseToDiscord(version, cycleClosed) {
-  const url = process.env["DISCORD_CHANGELOG_WEBHOOK"]?.trim();
-  if (!url) return false;
-  const cyclePart = cycleClosed > 0 ? `Cycle ${cycleClosed}` : "New cycle";
-  const content = `${cyclePart} released: ${version}. https://getpapi.ai/changelog`;
-  try {
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ content })
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
+var CYCLE_UPDATES_CHANNEL_ENV = "DISCORD_CYCLE_UPDATES_CHANNEL_ID";
+function buildCycleUpdateCurationDirective(version, cycleClosed) {
+  const channelId = process.env[CYCLE_UPDATES_CHANNEL_ENV]?.trim();
+  if (!channelId) return null;
+  const cyclePart = cycleClosed > 0 ? `Cycle ${cycleClosed}` : "New release";
+  return [
+    "",
+    "---",
+    "## \u{1F4E3} Post a curated cycle update to Discord #papi-cycle-updates",
+    "",
+    `**${cyclePart} \u2014 ${version}** just shipped. Post a curated, safety-gated **rich embed** (NOT plain content, so the link does not unfurl) to the private #papi-cycle-updates channel (id \`${channelId}\`) via \`mcp__discord__send_embed\`.`,
+    "",
+    "**LOCKED TEMPLATE \u2014 every cycle update uses this exact shape so they stay consistent (do NOT improvise the structure):**",
+    `- \`title\`: \`${cyclePart} shipped \u2014 ${version}\``,
+    "- `url`: `https://getpapi.ai/changelog` (makes the title link to the changelog)",
+    "- `color`: `#5a4b8a` (Papi plum)",
+    "- `description`: 4-6 PLAIN one-line bullets (`- ` prefix). No emoji-headed sections, no theme intro paragraph, no sub-headings. Each bullet = one user-facing outcome in the `/patch-notes` voice (warm, plain, outcome-framed). Strip task-IDs and internal framing. Only genuinely user-facing changes \u2014 internal/owner-only/site-plumbing tasks do NOT get a bullet.",
+    `- \`footer\`: \`Built with PAPI \xB7 <N> tasks \xB7 getpapi.ai\` where <N> = the count of THIS cycle's completed tasks (${cyclePart}).`,
+    "",
+    "Then:",
+    "1. Run the build-in-public safety gate: NO external usernames, NO contributor/private work, NO owner cost/commercial data. (#papi-cycle-updates is private \u2014 internal detail is OK \u2014 but keep the gate habit so anything later promoted to public is already clean.)",
+    "2. Show the draft embed for a quick approval BEFORE posting.",
+    `3. On approval, send the embed to channel \`${channelId}\`.`,
+    "",
+    "Skip entirely if nothing user-facing is worth sharing this cycle. Do NOT post to public #changelog per-cycle \u2014 that now happens at strategy-review cadence via /patch-notes."
+  ].join("\n");
 }
 async function postReleaseToX(version, cycleClosed) {
   const url = process.env["X_RELEASE_WEBHOOK_URL"]?.trim();
@@ -17469,14 +18078,48 @@ async function handleRelease(adapter2, config2, args) {
       version = `${version}-${suffix}`;
     }
   }
-  if (isHostedTransport()) {
-    const tagAnnotation = `Release ${version}`;
-    return errorResponse(
-      `Release is not available on the hosted remote MCP transport.
+  const tracker = new ProgressTracker("validate-args");
+  try {
+    tracker.mark("owner-identity-guard");
+    const gate = await resolveOwnerGate(adapter2, config2);
+    const productionBaseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
+    if (branch === productionBaseBranch) {
+      if (gate.enforced && !gate.callerIsOwner) {
+        const resolutionNote = gate.resolutionError ? `
+
+Identity resolution failed (${gate.resolutionError}) \u2014 the gate fails closed. Retry once connectivity is restored.` : "";
+        return errorResponse(
+          `Release to ${productionBaseBranch} is restricted to the project owner.
+
+Your identity does not match this project's owner. If you are a contributor, push your branch and open a PR for the owner to release. If you ARE the owner on a local (pg) setup, set PAPI_USER_ID to your account UUID in .mcp.json; on the hosted/proxy setup your identity comes from your API key \u2014 check you are using YOUR key for YOUR project. Releasing to a non-base branch (e.g. dev) is unaffected.` + resolutionNote
+        );
+      }
+    }
+    if (isHostedTransport()) {
+      tracker.mark("hosted-close-cycle");
+      let closed;
+      try {
+        closed = await closeCycleState(config2, adapter2, version, void 0, {
+          force: force ?? false,
+          callerUserId: gate.callerUserId
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return errorResponse(message);
+      }
+      const tagAnnotation = `Release ${version}`;
+      const cyclePart = closed.resolvedCycleNum > 0 ? `Cycle ${closed.resolvedCycleNum}` : "The cycle";
+      const warningsBlock = closed.warnings.length > 0 ? `
+\u26A0\uFE0F Warnings: ${closed.warnings.join("; ")}
+` : "";
+      return textResponse(
+        `## Release ${version} \u2014 cycle closed in the DB
 
-The release tool runs git (tag, push) and generates CHANGELOG.md on the server's filesystem. The hosted server (mcp.getpapi.ai) has no checkout of your project and no git binary, so these steps can't run remotely.
+${cyclePart} is now marked **complete** in PAPI's database, so \`orient\` will no longer flag "Release has not been run."
+` + warningsBlock + `
+The hosted remote MCP transport (mcp.getpapi.ai) has no checkout of your project and no git binary, so the git half of the release (tag, push, CHANGELOG.md) must run on your own machine.
 
-To close this cycle locally, on your own machine:
+Finish the release locally:
 \`\`\`
 git checkout ${branch}
 git pull
@@ -17490,11 +18133,9 @@ If git reports "Author identity unknown" or "Committer identity unknown" (no glo
 git -c user.name="Your Name" -c user.email="you@example.com" tag -a ${version} -m "${tagAnnotation}"
 \`\`\`
 
-Known limitation: PAPI's internal "cycle marked complete" state is updated by the release tool itself, so until you can run release from a local PAPI install, \`orient\` will continue to flag "Release has not been run." Tracked as a follow-up under SUP-2026-016.`
-    );
-  }
-  const tracker = new ProgressTracker("validate-args");
-  try {
+Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`
+      );
+    }
     tracker.mark("remote-project-guard");
     if (adapter2.getProjectInfo) {
       try {
@@ -17516,21 +18157,6 @@ Run \`project_switch <slug>\` to switch the active PAPI project, or verify your
         console.error("[release] remote-project guard: skipped due to error \u2014 " + (err instanceof Error ? err.message : String(err)));
       }
     }
-    tracker.mark("owner-identity-guard");
-    const productionBaseBranch = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
-    if (branch === productionBaseBranch) {
-      const gate = await resolveOwnerGate(adapter2, config2);
-      if (gate.enforced && !gate.callerIsOwner) {
-        const resolutionNote = gate.resolutionError ? `
-
-Identity resolution failed (${gate.resolutionError}) \u2014 the gate fails closed. Retry once connectivity is restored.` : "";
-        return errorResponse(
-          `Release to ${productionBaseBranch} is restricted to the project owner.
-
-Your identity does not match this project's owner. If you are a contributor, push your branch and open a PR for the owner to release. If you ARE the owner on a local (pg) setup, set PAPI_USER_ID to your account UUID in .mcp.json; on the hosted/proxy setup your identity comes from your API key \u2014 check you are using YOUR key for YOUR project. Releasing to a non-base branch (e.g. dev) is unaffected.` + resolutionNote
-        );
-      }
-    }
     tracker.mark("preflight-grouped-branches");
     const cycleMatch = version.match(/^v0\.(\d+)\./);
     const cycleNumForPreflight = cycleMatch ? parseInt(cycleMatch[1], 10) : void 0;
@@ -17542,7 +18168,11 @@ Your identity does not match this project's owner. If you are a contributor, pus
       }
     }
     tracker.mark("create-release");
-    const result = await createRelease(config2, branch, version, adapter2, void 0, { force: force ?? false, skipVersion: skipVersion ?? false });
+    const result = await createRelease(config2, branch, version, adapter2, void 0, {
+      force: force ?? false,
+      skipVersion: skipVersion ?? false,
+      callerUserId: gate.callerUserId
+    });
     const lines = [
       `## Release ${result.version}${skipVersion ? " (skip version)" : ""}`,
       "",
@@ -17594,11 +18224,8 @@ Your identity does not match this project's owner. If you are a contributor, pus
         lines.push("", "\u26A0\uFE0F Dogfood observations could not be saved to DB \u2014 log them manually in DOGFOOD_LOG.md.");
       }
     }
-    try {
-      const posted = await postReleaseToDiscord(result.version, result.cycleClosed ?? 0);
-      if (posted) lines.push("", "Posted release announcement to Discord #changelog.");
-    } catch {
-    }
+    const cycleUpdateDirective = buildCycleUpdateCurationDirective(result.version, result.cycleClosed ?? 0);
+    if (cycleUpdateDirective) lines.push(cycleUpdateDirective);
     try {
       const xPosted = await postReleaseToX(result.version, result.cycleClosed ?? 0);
       if (xPosted) lines.push("", "Posted release announcement to X.");
@@ -17618,7 +18245,7 @@ Your identity does not match this project's owner. If you are a contributor, pus
       }
     } catch {
     }
-    lines.push("", `Next: cycle released! Run \`plan\` to start your next planning cycle.`);
+    lines.push("", `Next: cycle released! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`);
     const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
     return textResponse(lines.join("\n") + filesToWriteSection);
   } catch (err) {
@@ -17746,6 +18373,16 @@ function selectAutostashPaths(modified, untracked) {
   const stashableUntracked = untracked.filter((p) => !isDocsPath(p));
   return { toStash: [...trackedDirty, ...stashableUntracked], preservedDocs };
 }
+function resolveRelatedDecisions(provided, buildHandoff) {
+  const fromInput = (provided ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (fromInput.length > 0) return { adIds: Array.from(new Set(fromInput)), inferred: false };
+  if (buildHandoff) {
+    const text = typeof buildHandoff === "string" ? buildHandoff : JSON.stringify(buildHandoff);
+    const matches = text.match(/\bAD-\d+\b/g);
+    if (matches && matches.length > 0) return { adIds: Array.from(new Set(matches)), inferred: true };
+  }
+  return { adIds: [], inferred: false };
+}
 var buildStartTimes = /* @__PURE__ */ new Map();
 var taskBranchMap = /* @__PURE__ */ new Map();
 var taskStartShaMap = /* @__PURE__ */ new Map();
@@ -17761,16 +18398,36 @@ function sanitisePredictedFiles(raw) {
   const out = [];
   for (const entry of raw) {
     if (typeof entry !== "string") continue;
-    const altMatches = entry.match(/\(\s*or\s+`([^`]+)`\s*\)/gi) ?? [];
-    for (const alt of altMatches) {
-      const inner = alt.match(/`([^`]+)`/);
-      if (inner) out.push(inner[1].trim());
+    for (const segment of entry.split(";")) {
+      const altMatches = segment.match(/\(\s*or\s+`([^`]+)`\s*\)/gi) ?? [];
+      for (const alt of altMatches) {
+        const inner = alt.match(/`([^`]+)`/);
+        if (inner) out.push(inner[1].trim());
+      }
+      const cleaned = segment.replace(/`/g, "").replace(/\s*\(.*$/, "").trim();
+      if (cleaned) out.push(cleaned);
     }
-    const cleaned = entry.replace(/`/g, "").replace(/\s*\(.*$/, "").trim();
-    if (cleaned) out.push(cleaned);
   }
   return Array.from(new Set(out));
 }
+function pathBasename(p) {
+  const parts = p.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
+  return parts[parts.length - 1] ?? p;
+}
+function isPathInPredictedScope(changedPath, predicted) {
+  const changedLower = changedPath.replace(/\\/g, "/").toLowerCase();
+  const changedBase = pathBasename(changedPath);
+  for (const raw of predicted) {
+    const entry = raw.replace(/\\/g, "/").replace(/\/+$/, "").trim();
+    if (!entry) continue;
+    if (pathBasename(entry) === changedBase) return true;
+    const entryLower = entry.toLowerCase();
+    if (changedLower === entryLower || changedLower.startsWith(`${entryLower}/`)) {
+      return true;
+    }
+  }
+  return false;
+}
 function autoCommit(config2, taskId, taskTitle, predictedFiles) {
   const cwd = config2.projectRoot;
   const message = `feat(${taskId}): ${taskTitle}`;
@@ -17800,17 +18457,12 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
     if (modified.length === 0) {
       return "Auto-commit: skipped (no working-tree changes).";
     }
-    const basename2 = (p) => {
-      const parts = p.split(/[\\/]/);
-      return parts[parts.length - 1] ?? p;
-    };
     const dirname6 = (p) => {
       const idx = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
       return idx > 0 ? p.slice(0, idx) : "";
     };
     const cleanedPredicted = sanitisePredictedFiles(predictedFiles);
-    const predictedNames = new Set(cleanedPredicted.map(basename2).filter(Boolean));
-    const scoped = modified.filter((p) => predictedNames.has(basename2(p)));
+    const scoped = modified.filter((p) => isPathInPredictedScope(p, cleanedPredicted));
     if (scoped.length === 0) {
       const modSample = modified.slice(0, 5).join(", ");
       const predSample = cleanedPredicted.slice(0, 5).join(", ");
@@ -17938,12 +18590,8 @@ function computeScopeDriftSignal(predicted, changed) {
   if (!predicted || predicted.length === 0) return null;
   const filtered = changed.filter((c) => !isAmbientPath(c));
   if (filtered.length === 0) return null;
-  const basename2 = (p) => {
-    const parts = p.split(/[\\/]/);
-    return parts[parts.length - 1] ?? p;
-  };
-  const predictedNames = new Set(predicted.map(basename2).filter(Boolean));
-  const unexpected = filtered.filter((c) => !predictedNames.has(basename2(c)));
+  const cleanedPredicted = sanitisePredictedFiles(predicted);
+  const unexpected = filtered.filter((c) => !isPathInPredictedScope(c, cleanedPredicted));
   const fraction = unexpected.length / filtered.length;
   const triggered = fraction > 0.5 || unexpected.length > 5;
   if (!triggered) return null;
@@ -18020,6 +18668,14 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
   if (!task) {
     throw new Error(`Task "${taskId}" not found on the Cycle Board.`);
   }
+  if (task.assigneeId) {
+    const gate = await resolveOwnerGate(adapter2, config2);
+    if (!gate.callerUserId || gate.callerUserId !== task.assigneeId) {
+      throw new Error(
+        `Task "${taskId}" (${task.title}) is claimed by another member \u2014 only its assignee can build it. Have the claimer build it, or run \`task_unclaim\` to release it first.`
+      );
+    }
+  }
   if (task.status === "Done" || task.status === "Archived") {
     throw new Error(`Task "${taskId}" (${task.title}) is already ${task.status}. Cannot execute a completed task.`);
   }
@@ -18361,10 +19017,14 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
   };
   buildStartTimes.delete(taskId);
   taskBranchMap.delete(taskId);
-  if (input.relatedDecisions) {
-    const adIds = input.relatedDecisions.split(",").map((s) => s.trim()).filter(Boolean);
-    if (adIds.length > 0) report.relatedDecisions = adIds;
-  }
+  const { adIds: relatedAdIds, inferred: relatedInferred } = resolveRelatedDecisions(
+    input.relatedDecisions,
+    task.buildHandoff
+  );
+  if (relatedAdIds.length > 0) report.relatedDecisions = relatedAdIds;
+  console.error(
+    `[build] task ${taskId} related_decisions: ${relatedAdIds.length} AD(s) (${relatedAdIds.length === 0 ? "none" : relatedInferred ? "inferred from handoff" : "builder-provided"}).`
+  );
   if (report.startedAt && report.completedAt && typeof adapter2.getToolCallCount === "function") {
     try {
       const count = await adapter2.getToolCallCount(report.startedAt, report.completedAt);
@@ -18863,7 +19523,7 @@ var buildExecuteTool = {
       },
       related_decisions: {
         type: "string",
-        description: 'Comma-separated AD IDs that this build validated or challenged (e.g. "AD-5,AD-12"). Optional.'
+        description: 'Comma-separated AD IDs this build validated or challenged (e.g. "AD-5,AD-12"). Optional but high-value: name any Active Decision your work CONFIRMED, CONTRADICTED, or DEPENDED ON \u2014 this is the primary signal feeding the decision-intelligence graph (validated-decision events). Check the BUILD HANDOFF for AD references. If you leave this empty, AD IDs found in the handoff are auto-captured as a fallback.'
       },
       handoff_accuracy: {
         type: "object",
@@ -19592,7 +20252,7 @@ function collectDiagnostics(config2) {
 }
 var bugTool = {
   name: "bug",
-  description: "Report a bug. Two modes: (1) Default \u2014 creates a Backlog task with severity-based priority for the project board. (2) With report=true \u2014 submits a diagnostic bug report with system info for cross-project visibility (external user issue reporting). Does not call the Anthropic API.",
+  description: "Report a bug OR submit an idea to PAPI. Two modes: (1) Default \u2014 creates a Backlog task with severity-based priority for the project board. (2) With report=true \u2014 submits a bug or idea (set `type`) upstream to PAPI maintainers with diagnostics, optionally recording notify-when-fixed and contact-ok consent. Use report=true at a friction moment \u2014 e.g. when a PAPI tool returns a workflow-blocking error. Does not call the Anthropic API.",
   annotations: { readOnlyHint: false, destructiveHint: false },
   inputSchema: {
     type: "object",
@@ -19626,6 +20286,19 @@ var bugTool = {
         type: "boolean",
         description: "When true, submits a diagnostic bug report with system info instead of creating a board task. Use this to report issues to PAPI maintainers."
       },
+      type: {
+        type: "string",
+        enum: ["bug", "idea"],
+        description: 'Report mode only: submission kind \u2014 "bug" (default) or "idea" (feature request / suggestion). Both route to the same upstream PAPI triage.'
+      },
+      notify_when_fixed: {
+        type: "boolean",
+        description: "Report mode only: set true if the user wants to be notified when this submission is resolved (surfaced in a later orient/MCP call and on their dashboard)."
+      },
+      contact_ok: {
+        type: "boolean",
+        description: "Report mode only: set true if the user consents to the PAPI team reaching out about this submission."
+      },
       project: {
         type: "string",
         description: "Project id (UUID) or slug to file this bug 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."
@@ -19643,6 +20316,9 @@ async function handleBug(adapter2, config2, args) {
     if (!adapter2.submitBugReport) {
       return errorResponse("Bug reports require a database adapter (pg or proxy). The md adapter does not support bug reports.");
     }
+    const type = args.type === "idea" ? "idea" : "bug";
+    const notifyRequested = args.notify_when_fixed === true;
+    const contactOk = args.contact_ok === true;
     const diagnostics = collectDiagnostics(config2);
     const notes = args.notes?.trim();
     if (notes) {
@@ -19658,17 +20334,27 @@ async function handleBug(adapter2, config2, args) {
     }
     const report = await adapter2.submitBugReport({
       projectId,
+      type,
       description: text,
       diagnostics,
-      status: "open"
+      status: "open",
+      notifyRequested,
+      contactOk
     });
+    const kindLabel = type === "idea" ? "Idea" : "Bug report";
+    const followUps = [];
+    if (notifyRequested) followUps.push("you'll be notified when it's resolved");
+    if (contactOk) followUps.push("the PAPI team may reach out");
+    const followUpLine = followUps.length ? `
+
+Noted: ${followUps.join("; ")}.` : "";
     return textResponse(
-      `**Bug report submitted** \u2014 ID: \`${report.id}\`
+      `**${kindLabel} submitted** \u2014 ID: \`${report.id}\`
 
-Description: ${text}
+${type === "idea" ? "Idea" : "Description"}: ${text}
 Diagnostics collected: Node ${diagnostics.nodeVersion}, ${diagnostics.platform}/${diagnostics.arch}, adapter=${diagnostics.adapterType}
 
-This report is visible to PAPI maintainers. No further action needed from you.`
+This ${type} is visible to PAPI maintainers.${followUpLine}`
     );
   }
   let target = adapter2;
@@ -20045,7 +20731,7 @@ async function prepareReconcile(adapter2, projectRoot) {
     const misaligned = allTasks.filter((t) => {
       const mapping = phaseStageMap.get(t.phase ?? "");
       if (!mapping) return false;
-      return mapping.stage.status === "deferred" || mapping.horizon.status === "deferred";
+      return mapping.stage.status === "Deferred" || mapping.horizon.status === "Deferred";
     });
     if (misaligned.length > 0) {
       lines.push("### Hierarchy Misalignment (tasks in deferred stages/horizons)");
@@ -20643,108 +21329,29 @@ Re-run build_execute complete with a production_verification field, then re-subm
   const handoffRegenerated = false;
   let handoffRegenPrompt;
   if (input.stage === "handoff-review" && input.verdict === "request-changes" && task.buildHandoff) {
-    handoffRegenPrompt = await prepareHandoffRegen(task, input.comments, adapter2);
-  }
-  const stageLabel = input.stage === "handoff-review" ? "Handoff Review" : "Build Acceptance";
-  let phaseChanges = [];
-  if (newStatus) {
-    try {
-      phaseChanges = await propagatePhaseStatus(adapter2);
-    } catch {
-    }
-  }
-  return {
-    stageLabel,
-    taskId: input.taskId,
-    verdict: input.verdict,
-    comments: input.comments.trim(),
-    newStatus,
-    unblockedTasks,
-    handoffRegenerated,
-    handoffRegenPrompt,
-    currentCycle: cycle,
-    phaseChanges,
-    closedDocActions
-  };
-}
-
-// src/services/session-guidance.ts
-var state = {
-  toolCallCount: 0,
-  lastOrientAt: null,
-  releaseSinceLastOrient: false,
-  sessionStartedAt: Date.now(),
-  lastReviewListAt: null,
-  failureTimestamps: [],
-  consecutiveFailures: 0
-};
-var CONTEXT_BLOAT_CALL_THRESHOLD = 40;
-var ORIENT_GAP_MS = 3 * 60 * 60 * 1e3;
-var REVIEW_LIST_GUARD_WINDOW_MS = 15 * 60 * 1e3;
-var FAILURE_WINDOW_MS = 30 * 60 * 1e3;
-var FAILURE_RATE_THRESHOLD = 8;
-var CONSECUTIVE_FAILURE_THRESHOLD = 4;
-function recordToolCall(name) {
-  state.toolCallCount++;
-  if (name === "release") state.releaseSinceLastOrient = true;
-  if (name === "review_list") state.lastReviewListAt = Date.now();
-}
-function recordToolOutcome(success) {
-  if (success) {
-    state.consecutiveFailures = 0;
-    return;
-  }
-  const now = Date.now();
-  state.consecutiveFailures++;
-  state.failureTimestamps.push(now);
-  const cutoff = now - FAILURE_WINDOW_MS;
-  state.failureTimestamps = state.failureTimestamps.filter((t) => t >= cutoff);
-}
-function wasReviewListSeenRecently(windowMs = REVIEW_LIST_GUARD_WINDOW_MS) {
-  if (state.lastReviewListAt == null) return false;
-  return Date.now() - state.lastReviewListAt <= windowMs;
-}
-function markOrient() {
-  state.lastOrientAt = Date.now();
-  state.releaseSinceLastOrient = false;
-}
-function getProjectConnectionBanner(projectName, projectSlug) {
-  if (!projectName || !projectSlug) return null;
-  return `[Connected: ${projectName} (${projectSlug})] \u2014 confirm this is the project you mean before I write to it. If it's wrong, don't proceed: pass \`project=<id>\` on the call to target a different project, or fix the project id in your MCP config (PAPI_PROJECT_ID for local, x-papi-project-id header for remote) and reconnect.`;
-}
-function detectContextDegradation(now = Date.now()) {
-  if (state.consecutiveFailures >= CONSECUTIVE_FAILURE_THRESHOLD) {
-    return `Context degradation (clash): ${state.consecutiveFailures} tool calls failed in a row \u2014 the session may be stuck on a contradiction. Consider a fresh window after this task.`;
-  }
-  const cutoff = now - FAILURE_WINDOW_MS;
-  const recentFailures = state.failureTimestamps.filter((t) => t >= cutoff).length;
-  if (recentFailures >= FAILURE_RATE_THRESHOLD) {
-    const mins = Math.round(FAILURE_WINDOW_MS / 6e4);
-    return `Context degradation (distraction/confusion): ${recentFailures} tool failures in the last ${mins}min. A fresh window often clears this faster than pushing on.`;
-  }
-  return null;
-}
-async function buildSessionGuidance() {
-  const signals = [];
-  const degradation = detectContextDegradation();
-  if (degradation) signals.push(degradation);
-  if (state.toolCallCount > CONTEXT_BLOAT_CALL_THRESHOLD) {
-    signals.push(
-      `${state.toolCallCount} tool calls this session \u2014 context may be bloated. Consider starting a fresh window.`
-    );
-  }
-  if (state.lastOrientAt && Date.now() - state.lastOrientAt > ORIENT_GAP_MS) {
-    const hours = Math.round((Date.now() - state.lastOrientAt) / (60 * 60 * 1e3));
-    signals.push(
-      `${hours}h since last orient \u2014 session may be stale. Consider a fresh window for best results.`
-    );
+    handoffRegenPrompt = await prepareHandoffRegen(task, input.comments, adapter2);
   }
-  if (state.releaseSinceLastOrient) {
-    signals.push(
-      "Release just ran \u2014 start a fresh session before the next `plan` to keep planning context clean."
-    );
+  const stageLabel = input.stage === "handoff-review" ? "Handoff Review" : "Build Acceptance";
+  let phaseChanges = [];
+  if (newStatus) {
+    try {
+      phaseChanges = await propagatePhaseStatus(adapter2);
+    } catch {
+    }
   }
-  return signals.slice(0, 3);
+  return {
+    stageLabel,
+    taskId: input.taskId,
+    verdict: input.verdict,
+    comments: input.comments.trim(),
+    newStatus,
+    unblockedTasks,
+    handoffRegenerated,
+    handoffRegenPrompt,
+    currentCycle: cycle,
+    phaseChanges,
+    closedDocActions
+  };
 }
 
 // src/tools/review.ts
@@ -20893,6 +21500,11 @@ function formatReviewList(pendingBuilds) {
   for (const t of pendingBuilds) {
     lines.push(`- **${t.id}:** ${t.title}`);
     lines.push(`  Status: ${t.status} | Priority: ${t.priority} | Complexity: ${t.complexity}`);
+    if (t.assigneeId || t.reviewerId) {
+      const built = t.assigneeId ? `built by ${t.assigneeId}` : "unattributed build";
+      const review = t.reviewerId ? `claimed by reviewer ${t.reviewerId}` : "unclaimed \u2014 `review_claim` to take it";
+      lines.push(`  ${built} \xB7 ${review}`);
+    }
   }
   lines.push("");
   lines.push('Use `review_submit` with task_id, stage "build-acceptance", verdict, and comments \u2014 are you happy with the build, or would you like changes?');
@@ -20946,6 +21558,10 @@ function mergeAfterAccept(config2, taskId) {
   }
   const merge = mergePullRequest(config2.projectRoot, featureBranch);
   if (!merge.success) {
+    if (isBranchMergedInto(config2.projectRoot, featureBranch, baseBranch)) {
+      details.push(`Branch '${featureBranch}' is already merged into '${baseBranch}'.`);
+      return { merged: true, skipped: false, message: `Already merged: \`${featureBranch}\` \u2192 \`${baseBranch}\`.`, details };
+    }
     return { merged: false, skipped: false, message: `PR merge failed: ${merge.message}`, details };
   }
   details.push(merge.message);
@@ -21070,12 +21686,28 @@ async function handleReviewSubmit(adapter2, config2, args) {
   }
   if (stage === "build-acceptance" && verdict === "accept") {
     const reviewerConfirmed = args.reviewer_confirmed === true;
-    if (!reviewerConfirmed && !wasReviewListSeenRecently()) {
+    if (!reviewerConfirmed && !wasReviewListSeenRecently(void 0, callerKeyFromConfig(config2))) {
       return errorResponse(
         "REVIEW_LIST_REQUIRED \u2014 call review_list first to see what is pending, then submit review_submit with reviewer_confirmed: true after reviewing the build report. (Guards against accepting work without inspecting it \u2014 see SUP-2026-010.)"
       );
     }
   }
+  if (stage === "build-acceptance") {
+    const gate = await resolveOwnerGate(adapter2, config2);
+    const caller = gate.callerUserId;
+    const reviewTask = await adapter2.getTask(taskId);
+    if (reviewTask?.reviewerId && caller && reviewTask.reviewerId !== caller && !gate.callerIsOwner) {
+      return errorResponse(
+        `Task "${taskId}" is claimed for review by another member (${reviewTask.reviewerId}). Only the claiming reviewer (or the project owner) can submit its verdict.`
+      );
+    }
+    if (reviewTask && !reviewTask.reviewerId && caller) {
+      try {
+        await adapter2.updateTask(taskId, { reviewerId: caller });
+      } catch {
+      }
+    }
+  }
   const tracker = new ProgressTracker("validate-args");
   const handoffRegenResponse = args.handoff_regen_response;
   if (handoffRegenResponse?.trim()) {
@@ -21123,6 +21755,7 @@ ${result.handoffRegenPrompt.userMessage}
     }
     let mergeNote = "";
     let overlapNote = "";
+    let mergeFailed = false;
     if (stage === "build-acceptance" && verdict === "accept") {
       const mergeResult = mergeAfterAccept(config2, taskId);
       if (mergeResult.skipped) {
@@ -21132,14 +21765,24 @@ ${result.handoffRegenPrompt.userMessage}
 > ${mergeResult.message}`;
         }
       } else if (!mergeResult.merged) {
+        mergeFailed = true;
+        let revertNote = "";
+        try {
+          await adapter2.updateTask(taskId, { status: "In Review" });
+          revertNote = ` Task rolled back to **In Review** \u2014 re-run \`review_submit ${taskId} build-acceptance accept\` once the merge succeeds.`;
+        } catch (err) {
+          revertNote = ` \u26A0\uFE0F Could not auto-revert the status (${err instanceof Error ? err.message : String(err)}) \u2014 set ${taskId} back to In Review manually so the board does not show it as Done.`;
+        }
         mergeNote = `
 
-\u26A0\uFE0F **PR merge failed** \u2014 task is Done but the branch was NOT merged.
-
-${mergeResult.message}
+\u26A0\uFE0F **PR merge failed \u2014 task NOT marked Done.**${revertNote}
 
-Resolve this before running \`release\`.`;
+${mergeResult.message}`;
       } else {
+        try {
+          await adapter2.updateTask(taskId, { mergedAt: (/* @__PURE__ */ new Date()).toISOString() });
+        } catch {
+        }
         const detailLines = mergeResult.details.map((l) => `> ${l}`).join("\n");
         mergeNote = `
 
@@ -21159,7 +21802,7 @@ ${overlap}`;
     }
     let autoReleaseNote = "";
     let batchSummaryNote = "";
-    if (stage === "build-acceptance" && verdict === "accept" && result.newStatus === "Done" && result.currentCycle > 0) {
+    if (stage === "build-acceptance" && verdict === "accept" && result.newStatus === "Done" && result.currentCycle > 0 && !mergeFailed) {
       try {
         const allTasks = await adapter2.queryBoard();
         const cycleTasks = allTasks.filter((t) => t.cycle === result.currentCycle);
@@ -21252,9 +21895,28 @@ Resolve the issue above, then run \`release\` manually.`;
       }
     }
     const phaseNote = result.phaseChanges.length > 0 ? "\n\n" + result.phaseChanges.map((c) => `Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`).join("\n") : "";
-    const autoReviewNote = autoReview ? `
+    let autoReviewNote = "";
+    if (autoReview) {
+      const findingLines = autoReview.findings.slice(0, 10).map((f) => {
+        const loc = f.file ? ` (${f.file}${f.line ? `:${f.line}` : ""})` : "";
+        return `  - [${f.severity}]${loc} ${f.message}`;
+      }).join("\n");
+      const more = autoReview.findings.length > 10 ? `
+  \u2026and ${autoReview.findings.length - 10} more` : "";
+      autoReviewNote = `
+
+**Quality Gate (auto-review): ${autoReview.verdict}** \u2014 ${autoReview.summary}` + (autoReview.findings.length > 0 ? `
+${findingLines}${more}` : "");
+      if (stage === "build-acceptance" && verdict === "accept" && autoReview.verdict !== "pass") {
+        autoReviewNote += `
 
-**Auto-Review:** ${autoReview.verdict} \u2014 ${autoReview.summary}` + (autoReview.findings.length > 0 ? ` (${autoReview.findings.length} finding${autoReview.findings.length === 1 ? "" : "s"})` : "") : "";
+\u26A0\uFE0F **Override recorded:** ${reviewer} accepted past a ${autoReview.verdict} quality gate (${autoReview.findings.length} finding${autoReview.findings.length === 1 ? "" : "s"}). The verdict + findings are stored on this review for the audit trail.`;
+      }
+    } else if (stage === "build-acceptance" && verdict === "accept") {
+      autoReviewNote = `
+
+**Quality Gate:** no auto-review attached. PAPI's standard pre-accept step is a code review of the branch diff \u2014 run \`review_submit\` with \`dispatch:"subagent"\` to auto-review, or attach \`auto_review\` findings. Risk-tier work (auth, data, migrations, CI) should always carry one.`;
+    }
     let nextStepNote = "";
     if (!autoReleaseNote && stage === "build-acceptance") {
       if (verdict === "accept") {
@@ -21290,6 +21952,66 @@ ${statusNote}${autoReviewNote}${unblockNote}${docClosureNote}${regenNote}${merge
     }));
   }
 }
+var reviewClaimTool = {
+  name: "review_claim",
+  description: "Claim a Pending Review from the shared cross-user review queue so you are the one reviewing it. Atomic first-claim-wins \u2014 two reviewers cannot grab the same build. After claiming, run review_submit to record your verdict. Owner-or-active-member only. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      task_id: { type: "string", description: 'The In Review task to claim for review, e.g. "task-2072".' }
+    },
+    required: ["task_id"]
+  }
+};
+async function resolveReviewerIdentity(adapter2, config2) {
+  const gate = await resolveOwnerGate(adapter2, config2);
+  const callerUserId = gate.callerUserId;
+  if (!callerUserId) {
+    const note = gate.resolutionError ? ` (${gate.resolutionError})` : "";
+    return { error: "Reviewing requires a resolvable user identity, but none was found" + note + ". Set PAPI_USER_ID to your account UUID (local) \u2014 hosted sessions derive it from the bearer token." };
+  }
+  if (!gate.callerIsOwner && typeof adapter2.listContributors === "function") {
+    try {
+      const members = await adapter2.listContributors();
+      if (!members.some((m) => m.userId === callerUserId)) {
+        return { error: "Only the project owner or an active contributor can claim reviews on this project." };
+      }
+    } catch (err) {
+      return { error: `Could not verify membership: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  return { callerUserId, callerIsOwner: gate.callerIsOwner };
+}
+async function handleReviewClaim(adapter2, config2, args) {
+  const taskId = typeof args.task_id === "string" ? args.task_id.trim() : "";
+  if (!taskId) return errorResponse('A task_id is required. Example: review_claim task_id="task-2072"');
+  if (typeof adapter2.claimReview !== "function") {
+    return errorResponse("The shared review queue is not available on this adapter.");
+  }
+  const identity = await resolveReviewerIdentity(adapter2, config2);
+  if ("error" in identity) return errorResponse(identity.error);
+  const me = identity.callerUserId;
+  const claimed = await adapter2.claimReview(taskId, me);
+  if (!claimed) {
+    const task = await adapter2.getTask(taskId);
+    if (!task) return errorResponse(`Task "${taskId}" not found on the board.`);
+    if (task.status !== "In Review") {
+      return errorResponse(`Task "${taskId}" is ${task.status}, not In Review \u2014 there is no pending review to claim.`);
+    }
+    if (task.reviewerId && task.reviewerId !== me) {
+      return errorResponse(`Task "${taskId}" is already being reviewed by another member (${task.reviewerId}).`);
+    }
+    if (task.reviewerId === me) {
+      return textResponse(`You have already claimed the review for **${taskId}** \u2014 run \`review_submit\` to record your verdict.`);
+    }
+    return errorResponse(`Could not claim the review for "${taskId}".`);
+  }
+  const builtBy = claimed.assigneeId ? ` (built by ${claimed.assigneeId})` : "";
+  return textResponse(
+    `\u2705 Claimed the review for **${claimed.id}** (${claimed.title})${builtBy}. You are now the reviewer. Read the build report, then run \`review_submit\` with your verdict.`
+  );
+}
 
 // src/tools/init.ts
 import { randomUUID as randomUUID15 } from "crypto";
@@ -22023,7 +22745,7 @@ ${lines.join("\n")}`;
 
 // src/lib/version-handshake.ts
 var MIN_PROXY_VERSION = "1.0.0";
-var SERVER_VERSION = "0.7.15";
+var SERVER_VERSION = "0.7.35";
 function meetsMinVersion(actual, required) {
   const actualParts = actual.split(".").map((n) => parseInt(n, 10));
   const requiredParts = required.split(".").map((n) => parseInt(n, 10));
@@ -22405,13 +23127,29 @@ function normalizeDocPath(rawPath, projectRoot) {
     error: `doc_register received an absolute path: \`${input}\`. Pass a path relative to your project root instead (e.g. \`docs/research/x.md\`). Absolute paths break visibility inference and on-disk lookups.`
   };
 }
+function docRegisterSoftFail(adapterType, lastStep, error, hint) {
+  const payload = { tool: "doc_register", adapter: adapterType, lastStep, error, hint };
+  return textResponse(
+    `\u26A0\uFE0F doc_register skipped (non-blocking) at step "${lastStep}" \u2014 your build/plan/review flow can continue safely; document registration is advisory.
+
+Diagnostic JSON:
+${JSON.stringify(payload, null, 2)}`
+  );
+}
 async function handleDocRegister(adapter2, args, config2) {
+  const adapterType = config2?.adapterType ?? "unknown";
+  const continueHint = "doc_register is advisory \u2014 your build/plan/review flow is unaffected. Fix the input (or wait for the registry to recover) and re-run doc_register; or just continue without it.";
   if (!adapter2.registerDoc) {
-    return errorResponse("Doc registry not available \u2014 requires pg adapter.");
+    return docRegisterSoftFail(
+      adapterType,
+      "adapter-capability-check",
+      "Doc registry not available \u2014 requires the pg/proxy adapter.",
+      "On the md adapter doc_register is a no-op. Continue without it \u2014 nothing is blocked."
+    );
   }
   const normalized = normalizeDocPath(args.path, config2?.projectRoot);
   if ("error" in normalized) {
-    return errorResponse(normalized.error);
+    return docRegisterSoftFail(adapterType, "path-normalization", normalized.error, continueHint);
   }
   const path7 = normalized.path;
   const title = args.title;
@@ -22424,39 +23162,49 @@ async function handleDocRegister(adapter2, args, config2) {
   const supersededByPath = args.superseded_by_path;
   const visibility = resolveDocVisibility(args.visibility, path7);
   if (!path7 || !title || !type || !summary || !cycle) {
-    return errorResponse("Required fields: path, title, type, summary, cycle.");
+    return docRegisterSoftFail(
+      adapterType,
+      "field-validation",
+      "Required fields: path, title, type, summary, cycle.",
+      continueHint
+    );
   }
-  let supersededBy;
-  if (supersededByPath) {
-    const existing = await adapter2.getDoc?.(supersededByPath);
-    if (existing) {
-      supersededBy = existing.id;
-      await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
+  try {
+    let supersededBy;
+    if (supersededByPath) {
+      const existing = await adapter2.getDoc?.(supersededByPath);
+      if (existing) {
+        supersededBy = existing.id;
+        await adapter2.updateDocStatus?.(existing.id, "superseded", void 0);
+      }
     }
-  }
-  const entry = await adapter2.registerDoc({
-    title,
-    type,
-    path: path7,
-    status: supersededByPath ? "superseded" : status,
-    summary,
-    tags,
-    cycleCreated: cycle,
-    cycleUpdated: cycle,
-    supersededBy,
-    actions,
-    visibility
-  });
-  const visibilityLabel = entry.visibility === "contributors" ? "team member" : entry.visibility ?? "private";
-  return textResponse(
-    `**Registered:** ${entry.title}
+    const entry = await adapter2.registerDoc({
+      title,
+      type,
+      path: path7,
+      status,
+      summary,
+      tags,
+      cycleCreated: cycle,
+      cycleUpdated: cycle,
+      supersededBy,
+      actions,
+      visibility
+    });
+    const visibilityLabel = entry.visibility === "contributors" ? "team member" : entry.visibility ?? "private";
+    return textResponse(
+      `**Registered:** ${entry.title}
 - **Path:** ${entry.path}
 - **Type:** ${entry.type} | **Status:** ${entry.status}
 - **Visibility:** ${visibilityLabel}
 - **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
 - **Actions:** ${actions?.length ?? 0} items
 - **ID:** ${entry.id}`
-  );
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return docRegisterSoftFail(adapterType, "registry-write", message, continueHint);
+  }
 }
 async function handleDocSearch(adapter2, args, config2) {
   if (!adapter2.searchDocs) {
@@ -22807,6 +23555,10 @@ var orientTool = {
       deep_housekeeping: {
         type: "boolean",
         description: "Run expensive cross-referencing checks: board-vs-branch reconciliation, unrecorded commit detection, unregistered doc scan. Default false \u2014 orient stays fast and noise-light at session start. Pass true when you specifically want a sweep (e.g. before release or after a long break). One-liner in default output points users at this flag when they need it."
+      },
+      full: {
+        type: "boolean",
+        description: "Run the heavy enrichment blocks that the lean default path skips: Research Signals (doc search) and npm version-drift. Default false \u2014 the lean path keeps the per-session query count down so orient stays well under the tool timeout on large projects. Implied automatically when deep_housekeeping is true."
       }
     },
     required: []
@@ -22837,7 +23589,7 @@ function formatSynthesisParagraph(opts) {
   parts.push(`Next: ${cleanMode}`);
   return parts.join(" ");
 }
-function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoot, environment = "unknown", subAgents = [], projectName) {
+function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoot, environment = "unknown", subAgents = [], projectName, teamSummary) {
   const lines = [];
   const cycleIsComplete = health.latestCycleStatus === "complete";
   const tagSuffix = latestTag ? ` \u2014 ${latestTag}` : "";
@@ -22904,6 +23656,10 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
   lines.push("## Board");
   lines.push(health.boardSummary);
   lines.push("");
+  if (teamSummary) {
+    lines.push(teamSummary);
+    lines.push("");
+  }
   if (subAgents.length > 0) {
     lines.push(`**Sub-agents (${subAgents.length}):** ` + subAgents.map((a) => {
       const desc = a.description ? ` (${a.description.slice(0, 60)})` : "";
@@ -23108,9 +23864,56 @@ function formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds) {
   }
   return { alertsNote, unactionedIssuesNote };
 }
+async function computeTeamSummary(adapter2) {
+  if (typeof adapter2.listContributors !== "function") return void 0;
+  let members;
+  try {
+    members = (await adapter2.listContributors()).length;
+  } catch {
+    return void 0;
+  }
+  if (members <= 1) return void 0;
+  let tasks;
+  try {
+    tasks = await adapter2.queryBoard({ compact: true });
+  } catch {
+    return void 0;
+  }
+  const isOpen = (t) => t.status !== "Done" && t.status !== "Cancelled" && t.status !== "Archived";
+  const pool = tasks.filter((t) => isOpen(t) && !t.assigneeId && t.cycle == null).length;
+  const inFlight = tasks.filter((t) => t.status === "In Progress").length;
+  const reviewQueue = tasks.filter((t) => t.status === "In Review").length;
+  return `**Team:** ${members} members \xB7 ${pool} in pool \xB7 ${inFlight} in flight \xB7 ${reviewQueue} in review`;
+}
+async function computeReleaseHistory(adapter2) {
+  if (typeof adapter2.listContributors !== "function") return void 0;
+  let contributors;
+  try {
+    contributors = await adapter2.listContributors();
+  } catch {
+    return void 0;
+  }
+  if (contributors.length <= 1) return void 0;
+  let cycles;
+  try {
+    cycles = await adapter2.readCycles();
+  } catch {
+    return void 0;
+  }
+  const nameOf = new Map(
+    contributors.map((c) => [c.userId, c.displayName || c.email || c.userId.slice(0, 8)])
+  );
+  const released = cycles.filter((c) => c.status === "complete").sort((a, b2) => b2.number - a.number).slice(0, 5).map((c) => {
+    const who = c.userId ? nameOf.get(c.userId) ?? c.userId.slice(0, 8) : null;
+    return `Cycle ${c.number}${who ? ` (${who})` : ""}`;
+  });
+  if (released.length === 0) return void 0;
+  return `**Recent releases:** ${released.join(" \xB7 ")}`;
+}
 async function handleOrient(adapter2, config2, args = {}) {
   const environment = normaliseEnvironment(args.environment);
   const deepHousekeeping = args.deep_housekeeping === true;
+  const fullEnrichment = args.full === true || deepHousekeeping;
   const tracker = new ProgressTracker("start");
   try {
     tracker.mark("propagate-phase-status");
@@ -23157,6 +23960,7 @@ async function handleOrient(adapter2, config2, args = {}) {
       ownerActionsOutcome,
       ownerActionsNudgedOutcome,
       ownerActionsBlockingOutcome,
+      reviewChangesOutcome,
       ttfvOutcome,
       latestTagOutcome,
       versionDriftOutcome,
@@ -23247,6 +24051,37 @@ async function handleOrient(adapter2, config2, args = {}) {
           return void 0;
         }
       }),
+      // task-2105 (C296): review-verdict notification. When a build was bounced
+      // back (request-changes/reject → status In Progress) and not yet resubmitted,
+      // surface it in orient so the builder gets a signal — submitReview itself has
+      // no notification channel. Derived from existing data (no new schema): latest
+      // review per task + current status. Within-project only (board visibility
+      // already scopes the caller); per-assignee targeting is a future refinement.
+      tracked("review-changes-requested", async () => {
+        if (!adapter2.getRecentReviews || !adapter2.getTask) return void 0;
+        try {
+          const reviews = await adapter2.getRecentReviews(100);
+          const latestByTask = /* @__PURE__ */ new Map();
+          for (const r of reviews) {
+            if (!latestByTask.has(r.taskId)) latestByTask.set(r.taskId, { verdict: r.verdict, comments: r.comments });
+          }
+          const bounced = [];
+          for (const [taskId, rev] of latestByTask) {
+            if (rev.verdict !== "request-changes" && rev.verdict !== "reject") continue;
+            const task = await adapter2.getTask(taskId);
+            if (task && task.status === "In Progress") {
+              bounced.push({ id: task.displayId ?? taskId, comment: rev.comments ?? "" });
+            }
+          }
+          if (bounced.length === 0) return void 0;
+          const list = bounced.slice(0, 5).map((b2) => b2.id).join(", ");
+          const c = bounced[0].comment.trim();
+          const snippet = c ? ` \u2014 ${bounced[0].id}: "${c.length > 80 ? `${c.slice(0, 80)}\u2026` : c}"` : "";
+          return `\u26A0\uFE0F ${bounced.length} task${bounced.length === 1 ? "" : "s"} bounced back with changes requested: ${list}${snippet}. Address the feedback, then build_execute to resubmit.`;
+        } catch {
+          return void 0;
+        }
+      }),
       // Time-to-first-value: setup/plan milestones (only for early projects).
       // PERF: hasToolMilestone is a cheap EXISTS lookup; avoids 5000-row pull.
       tracked("ttfv", async () => {
@@ -23265,11 +24100,16 @@ async function handleOrient(adapter2, config2, args = {}) {
         return `
 **Time to first plan:** ${deltaMinutes} minutes (setup \u2192 first plan)`;
       }),
-      // Latest git tag + npm version drift (both exec calls with own timeouts)
+      // 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("npm-version-drift", () => checkNpmVersionDrift()),
-      // Research Signals — research docs with pending actions since last strategy review
+      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
+      // mid-session — gated behind `full`/deep_housekeeping to keep the default lean.
       tracked("research-signals", async () => {
+        if (!fullEnrichment) return "";
         if (!adapter2.searchDocs) return "";
         const cycleHealth = await adapter2.getCycleHealth();
         const lastReviewCycle = Math.max(0, cycleHealth.totalCycles - cycleHealth.cyclesSinceLastStrategyReview);
@@ -23370,8 +24210,9 @@ async function handleOrient(adapter2, config2, args = {}) {
       }),
       // Session guidance — proactive nudges (doc_register, context bloat, mode switch)
       tracked("session-guidance", async () => {
-        const signals = await buildSessionGuidance();
-        markOrient();
+        const callerKey = callerKeyFromConfig(config2);
+        const signals = await buildSessionGuidance(callerKey);
+        markOrient(callerKey);
         if (signals.length === 0) return "";
         const lines = ["\n\n## Session Guidance"];
         for (const s of signals) lines.push(`- ${s}`);
@@ -23468,6 +24309,8 @@ async function handleOrient(adapter2, config2, args = {}) {
     if (ownerActionsNudgedWarning) buildResult.warnings.push(ownerActionsNudgedWarning);
     const ownerActionsBlockingWarning = ownerActionsBlockingOutcome.status === "fulfilled" ? ownerActionsBlockingOutcome.value : void 0;
     if (ownerActionsBlockingWarning) buildResult.warnings.push(ownerActionsBlockingWarning);
+    const reviewChangesWarning = reviewChangesOutcome.status === "fulfilled" ? reviewChangesOutcome.value : void 0;
+    if (reviewChangesWarning) buildResult.warnings.push(reviewChangesWarning);
     try {
       const verifyWarnings = await verifyProject(adapter2);
       for (const w of verifyWarnings) buildResult.warnings.push(w);
@@ -23531,8 +24374,13 @@ ${section}`;
     }
     tracker.mark("format-summary");
     const subAgents = await listAgents(config2.projectRoot);
-    const deepHint = deepHousekeeping ? "" : "\n\n*Tip: pass `deep_housekeeping: true` to also check orphaned branches, unrecorded commits, unregistered docs, and stale skill forks.*";
-    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName) + unblockNote + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
+    const [teamSummaryLine, releaseHistoryLine] = await Promise.all([
+      tracked("team-summary", () => computeTeamSummary(adapter2))().catch(() => void 0),
+      tracked("release-history", () => computeReleaseHistory(adapter2))().catch(() => void 0)
+    ]);
+    const teamSummary = [teamSummaryLine, releaseHistoryLine].filter(Boolean).join("\n") || void 0;
+    const deepHint = deepHousekeeping ? "" : "\n\n*Tip: pass `full: true` for Research Signals + version-drift, or `deep_housekeeping: true` to also check orphaned branches, unrecorded commits, unregistered docs, and stale skill forks (implies `full`).*";
+    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary) + unblockNote + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Orient failed|Project not found|No project|Setup required)/i.test(message);
@@ -23806,6 +24654,18 @@ async function assembleZoomOutContext(adapter2, cycleNumber, projectRoot) {
       const lines = [];
       for (const [adId, adEvents] of byDecision) {
         lines.push(`**${adId}:** ${adEvents.length} events \u2014 ${adEvents.map((e) => `${e.eventType} (S${e.cycle})`).join(", ")}`);
+        for (const e of adEvents) {
+          const parts = [];
+          if (e.evidenceRef) parts.push(`evidence: ${e.evidenceRef}`);
+          if (e.metricDelta?.metric) {
+            const d = e.metricDelta;
+            const movement = d.before !== void 0 && d.after !== void 0 ? `${d.before}\u2192${d.after}` : d.delta !== void 0 ? `\u0394${d.delta}` : "";
+            parts.push(`metric: ${d.metric}${movement ? ` (${movement})` : ""}`);
+          }
+          if (parts.length > 0) {
+            lines.push(`  - ${e.eventType} S${e.cycle}: ${parts.join("; ")}`);
+          }
+        }
       }
       adLifecycleText = lines.join("\n");
     }
@@ -24136,8 +24996,7 @@ Check that the project IDs are correct and exist in the same Supabase instance.`
 }
 
 // src/tools/handoff.ts
-var lastPrepareCycleNumber2;
-var lastPrepareContextBytes2;
+var handoffPrepareCache = new PerCallerCache();
 var handoffGenerateTool = {
   name: "handoff_generate",
   description: "Generate BUILD HANDOFFs for cycle tasks that don't have one yet. Run after `plan` (with skip_handoffs=true) or to regenerate stale handoffs. Uses the prepare/apply pattern \u2014 first call returns a prompt, second call persists results.",
@@ -24166,6 +25025,10 @@ var handoffGenerateTool = {
       cycle_number: {
         type: "number",
         description: 'The cycle number returned from prepare phase (mode "apply" only).'
+      },
+      force: {
+        type: "boolean",
+        description: "Regenerate handoffs for tasks that ALREADY have one, overwriting the stored handoff (default false = only fill in missing handoffs). Use to propagate a changed Active Decision or dependency into an in-flight task. Pass on the prepare call (it is remembered through apply); combine with task_ids to target specific tasks."
       }
     },
     required: []
@@ -24173,6 +25036,7 @@ var handoffGenerateTool = {
 };
 async function handleHandoffGenerate(adapter2, config2, args) {
   const toolMode = args.mode;
+  const callerKey = callerKeyFromConfig(config2);
   try {
     if (toolMode === "apply") {
       const resolved = await resolveLlmResponse(
@@ -24181,20 +25045,20 @@ async function handleHandoffGenerate(adapter2, config2, args) {
       );
       if (!resolved.ok) return errorResponse(resolved.error);
       const llmResponse = resolved.llmResponse;
-      const cycleNumber = typeof args.cycle_number === "number" ? args.cycle_number : lastPrepareCycleNumber2;
+      const prep = handoffPrepareCache.take(callerKey);
+      const expectedCycleNumber = prep?.cycleNumber;
+      const contextBytes = prep?.contextBytes;
+      const cycleNumber = typeof args.cycle_number === "number" ? args.cycle_number : expectedCycleNumber;
       if (cycleNumber === void 0) {
         return errorResponse('cycle_number is required for mode "apply". Pass the cycle number from the prepare phase.');
       }
-      const expectedCycleNumber = lastPrepareCycleNumber2;
-      const contextBytes = lastPrepareContextBytes2;
-      lastPrepareCycleNumber2 = void 0;
-      lastPrepareContextBytes2 = void 0;
+      const force = args.force === true || prep?.force === true;
       if (expectedCycleNumber !== void 0 && cycleNumber !== expectedCycleNumber) {
         return errorResponse(
           `cycle_number mismatch: prepare phase returned cycle ${expectedCycleNumber} but apply received ${cycleNumber}.`
         );
       }
-      const result = await applyHandoffs(adapter2, llmResponse, cycleNumber);
+      const result = await applyHandoffs(adapter2, llmResponse, cycleNumber, force);
       const lines = [];
       lines.push(`**Handoff Generation \u2014 Cycle ${result.cycleNumber}**`);
       lines.push(`${result.handoffsWritten} handoff(s) written: ${result.taskIds.join(", ")}`);
@@ -24209,9 +25073,13 @@ async function handleHandoffGenerate(adapter2, config2, args) {
     }
     {
       const taskIds = Array.isArray(args.task_ids) ? args.task_ids.filter((id) => typeof id === "string") : void 0;
-      const result = await prepareHandoffs(adapter2, config2, taskIds);
-      lastPrepareCycleNumber2 = result.cycleNumber;
-      lastPrepareContextBytes2 = result.contextBytes;
+      const force = args.force === true;
+      const result = await prepareHandoffs(adapter2, config2, taskIds, force);
+      handoffPrepareCache.set(callerKey, {
+        cycleNumber: result.cycleNumber,
+        contextBytes: result.contextBytes,
+        force
+      });
       return textResponse(
         `## PAPI Handoff Generation \u2014 Prepare Phase (Cycle ${result.cycleNumber})
 
@@ -24617,6 +25485,60 @@ async function handleDiscoveredIssueResolve(adapter2, args) {
 
 // src/tools/project.ts
 import path6 from "path";
+
+// src/services/entitlements.ts
+var FREE_PROJECT_CAP = 3;
+var PAID_TIERS = /* @__PURE__ */ new Set(["pro", "team"]);
+var PRICING_URL = "https://getpapi.ai/pricing";
+async function resolveTier(adapter2) {
+  if (typeof adapter2.getMeteredUsage !== "function") return null;
+  try {
+    const usage = await adapter2.getMeteredUsage();
+    return usage?.tier ?? null;
+  } catch {
+    return null;
+  }
+}
+function isPaidTier(tier) {
+  return tier !== null && PAID_TIERS.has(tier);
+}
+async function enforceProjectCap(adapter2, target) {
+  const tier = await resolveTier(adapter2);
+  if (tier === null || isPaidTier(tier)) return null;
+  if (typeof adapter2.listUserProjects !== "function") return null;
+  let projects;
+  try {
+    projects = await adapter2.listUserProjects();
+  } catch {
+    return null;
+  }
+  const matchesExisting = projects.some(
+    (p) => target.papiDir && p.papi_dir && p.papi_dir === target.papiDir || target.name && p.name && p.name.trim().toLowerCase() === target.name.trim().toLowerCase()
+  );
+  if (matchesExisting) return null;
+  if (projects.length >= FREE_PROJECT_CAP) return projectCapMessage(projects.length);
+  return null;
+}
+async function enforceContributorGate(adapter2) {
+  const tier = await resolveTier(adapter2);
+  if (tier === null) return null;
+  if (tier === "team") return null;
+  return contributorTeamMessage(tier);
+}
+function projectCapMessage(currentCount) {
+  return `**You're on the Free plan (${currentCount} of ${FREE_PROJECT_CAP} projects).**
+
+Free covers up to ${FREE_PROJECT_CAP} projects. To run more, upgrade to Pro for unlimited projects at a flat monthly price (no usage bills): ${PRICING_URL}
+
+Your existing projects are untouched, and you can keep working in any of them.`;
+}
+function contributorTeamMessage(tier) {
+  return `**Adding people to a project is a Team feature.**
+
+You're on the ${tier} plan. Shared projects, roles, and the Quality Gate come with Team. Read-only viewer seats are free, so you only pay for who is actually building: ${PRICING_URL}`;
+}
+
+// src/tools/project.ts
 function workspacePapiDir(config2) {
   if (!hasLocalWorkspace()) return void 0;
   return config2.papiDir;
@@ -24649,6 +25571,8 @@ async function handleProjectCreate(adapter2, config2, args) {
     if (papiDir) name = path6.basename(config2.projectRoot) || "My Project";
     else return errorResponse("name is required \u2014 there is no local workspace to derive it from on the remote transport.");
   }
+  const capDenied = await enforceProjectCap(adapter2, { papiDir, name });
+  if (capDenied) return errorResponse(capDenied);
   const result = await adapter2.createUserProject({
     name,
     papiDir,
@@ -24790,6 +25714,8 @@ function requireEmail(args) {
 async function handleContributorAdd(adapter2, config2, args) {
   const denied = await denyUnlessOwner(adapter2, config2);
   if (denied) return errorResponse(denied);
+  const tierDenied = await enforceContributorGate(adapter2);
+  if (tierDenied) return errorResponse(tierDenied);
   const email = requireEmail(args);
   if (!email) return errorResponse('A valid email is required. Example: contributor_add email="wes@example.com"');
   try {
@@ -24843,6 +25769,155 @@ async function handleContributorList(adapter2, config2, _args) {
   }
 }
 
+// src/tools/task-claim.ts
+var taskClaimTool = {
+  name: "task_claim",
+  description: "Claim a task from the shared org Pool into your personal backlog (assignee = you). Atomic first-claim-wins \u2014 a concurrent double-claim is impossible. Cascades the DEPENDS ON chain: claiming a task also claims its not-Done prerequisites; if any prerequisite is already claimed by another member the whole claim is refused (a build unit is never split across owners). Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      task_id: { type: "string", description: 'The task to claim, e.g. "task-2071".' }
+    },
+    required: ["task_id"]
+  }
+};
+var taskUnclaimTool = {
+  name: "task_unclaim",
+  description: "Release a task you claimed back to the shared Pool (clears assignee). Claimer-only and pre-review \u2014 you cannot unclaim another member's task or one that has reached In Review/Done. Does not cascade. Does not call the Anthropic API.",
+  annotations: { readOnlyHint: false, destructiveHint: true },
+  inputSchema: {
+    type: "object",
+    properties: {
+      task_id: { type: "string", description: 'The task to unclaim, e.g. "task-2071".' }
+    },
+    required: ["task_id"]
+  }
+};
+var DONE_STATUSES = /* @__PURE__ */ new Set(["Done", "Cancelled", "Archived"]);
+function requireTaskId(args) {
+  const id = typeof args.task_id === "string" ? args.task_id.trim() : "";
+  return id.length > 0 ? id : null;
+}
+async function resolveClaimerIdentity(adapter2, config2) {
+  if (typeof adapter2.claimTask !== "function") {
+    return { error: "Claiming is not available on this adapter." };
+  }
+  const gate = await resolveOwnerGate(adapter2, config2);
+  const callerUserId = gate.callerUserId;
+  if (!callerUserId) {
+    const note = gate.resolutionError ? ` (${gate.resolutionError})` : "";
+    return {
+      error: "Claiming requires a resolvable user identity, but none was found" + note + ". Set PAPI_USER_ID to your account UUID (local) \u2014 hosted sessions derive it from your bearer token."
+    };
+  }
+  if (!gate.callerIsOwner && typeof adapter2.listContributors === "function") {
+    try {
+      const members = await adapter2.listContributors();
+      if (!members.some((m) => m.userId === callerUserId)) {
+        return { error: "Only the project owner or an active contributor can claim tasks on this project." };
+      }
+    } catch (err) {
+      return { error: `Could not verify membership: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  return { callerUserId };
+}
+async function collectClaimChain(adapter2, root) {
+  const byId = /* @__PURE__ */ new Map([[root.id, root]]);
+  const queue = [root];
+  while (queue.length > 0) {
+    const t = queue.shift();
+    if (!t.dependsOn) continue;
+    const depIds = t.dependsOn.split(",").map((d) => d.trim()).filter(Boolean).filter((d) => !byId.has(d));
+    if (depIds.length === 0) continue;
+    const deps = await adapter2.getTasks(depIds);
+    for (const dep of deps) {
+      if (byId.has(dep.id)) continue;
+      byId.set(dep.id, dep);
+      if (!DONE_STATUSES.has(dep.status)) queue.push(dep);
+    }
+  }
+  return [...byId.values()].filter((t) => !DONE_STATUSES.has(t.status));
+}
+async function handleTaskClaim(adapter2, config2, args) {
+  const taskId = requireTaskId(args);
+  if (!taskId) return errorResponse('A task_id is required. Example: task_claim task_id="task-2071"');
+  const identity = await resolveClaimerIdentity(adapter2, config2);
+  if ("error" in identity) return errorResponse(identity.error);
+  const me = identity.callerUserId;
+  const root = await adapter2.getTask(taskId);
+  if (!root) return errorResponse(`Task "${taskId}" not found on the board.`);
+  if (DONE_STATUSES.has(root.status)) {
+    return errorResponse(`Task "${taskId}" is ${root.status} \u2014 nothing to claim.`);
+  }
+  const chain = await collectClaimChain(adapter2, root);
+  const blockedByOther = chain.filter((t) => t.assigneeId && t.assigneeId !== me);
+  const inOthersCycle = chain.filter((t) => !t.assigneeId && t.cycle != null);
+  if (blockedByOther.length > 0 || inOthersCycle.length > 0) {
+    const lines = [];
+    for (const t of blockedByOther) lines.push(`- ${t.id} (${t.title}) \u2014 already claimed by another member`);
+    for (const t of inOthersCycle) lines.push(`- ${t.id} (${t.title}) \u2014 already pulled into a cycle (not in the pool)`);
+    return errorResponse(
+      `Cannot claim "${taskId}" \u2014 it shares a DEPENDS ON build unit with task(s) you cannot take:
+${lines.join("\n")}
+
+A build unit is never split across owners. Ask the current owner to unclaim, or pick a different task.`
+    );
+  }
+  const alreadyMine = chain.filter((t) => t.assigneeId === me);
+  const toClaim = chain.filter((t) => !t.assigneeId && t.cycle == null);
+  const claimed = [];
+  const raced = [];
+  for (const t of toClaim) {
+    const result = await adapter2.claimTask(t.id, me);
+    if (result) claimed.push(result);
+    else raced.push(t.id);
+  }
+  if (claimed.length === 0 && alreadyMine.length > 0 && raced.length === 0) {
+    return textResponse(`Task "${taskId}" and its prerequisites are already in your backlog \u2014 nothing to do.`);
+  }
+  const parts = [];
+  const claimedList = claimed.map((t) => `- ${t.id} (${t.title})`).join("\n");
+  parts.push(
+    `\u2705 Claimed **${claimed.length}** task(s) into your backlog (assignee = you, not yet in a cycle):
+${claimedList}`
+  );
+  if (alreadyMine.length > 0) {
+    parts.push(`Already yours: ${alreadyMine.map((t) => t.id).join(", ")}.`);
+  }
+  if (raced.length > 0) {
+    parts.push(
+      `\u26A0\uFE0F ${raced.length} task(s) were claimed by someone else just now and were skipped: ${raced.join(", ")}. Re-run task_claim to see the current state.`
+    );
+  }
+  parts.push("Next: run `plan` to draw a cycle from your backlog, or `task_unclaim` to release.");
+  return textResponse(parts.join("\n\n"));
+}
+async function handleTaskUnclaim(adapter2, config2, args) {
+  const taskId = requireTaskId(args);
+  if (!taskId) return errorResponse('A task_id is required. Example: task_unclaim task_id="task-2071"');
+  if (typeof adapter2.unclaimTask !== "function") {
+    return errorResponse("Unclaiming is not available on this adapter.");
+  }
+  const identity = await resolveClaimerIdentity(adapter2, config2);
+  if ("error" in identity) return errorResponse(identity.error);
+  const me = identity.callerUserId;
+  const result = await adapter2.unclaimTask(taskId, me);
+  if (!result) {
+    const task = await adapter2.getTask(taskId);
+    if (!task) return errorResponse(`Task "${taskId}" not found on the board.`);
+    if (task.assigneeId && task.assigneeId !== me) {
+      return errorResponse(`Task "${taskId}" is claimed by another member \u2014 only the claimer can unclaim it.`);
+    }
+    if (task.status === "In Review" || task.status === "Done") {
+      return errorResponse(`Task "${taskId}" is ${task.status} \u2014 it has passed the pre-review window and cannot be unclaimed.`);
+    }
+    return errorResponse(`Task "${taskId}" is not currently claimed by you \u2014 nothing to unclaim.`);
+  }
+  return textResponse(`\u2705 Released **${result.id}** (${result.title}) back to the shared Pool.`);
+}
+
 // src/services/harness-inventory.ts
 import { readdir as readdir3, readFile as readFile8, stat as stat3 } from "fs/promises";
 import { join as join16 } from "path";
@@ -24944,8 +26019,8 @@ async function syncHarnessInventory(adapter2, config2, opts) {
   }
   const fingerprint = await computeFingerprint(config2.projectRoot);
   if (!opts?.force) {
-    const state2 = await adapter2.getHarnessState();
-    if (state2 && state2.fingerprint === fingerprint) return { changed: false };
+    const state = await adapter2.getHarnessState();
+    if (state && state.fingerprint === fingerprint) return { changed: false };
   }
   const entries = await scanInventory(config2.projectRoot, opts?.toolDefs);
   await adapter2.replaceHarnessInventory(entries);
@@ -25077,6 +26152,7 @@ If this is legitimate, reach out at https://getpapi.ai and we'll lift it \u2014
 // src/server.ts
 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")));
 var LONG_RUNNING_TOOLS = /* @__PURE__ */ new Set([
   "plan",
   "strategy_review",
@@ -25093,6 +26169,31 @@ function toolTimeoutMs(name) {
 }
 var wedgeRecoveryStats = { count: 0 };
 var inflightWork = /* @__PURE__ */ new Map();
+var ToolTimeoutError = class extends Error {
+  constructor(toolName, expectedMs, actualMs, wedged, pendingNote) {
+    super(
+      wedged ? `Tool '${toolName}' timed out after ${actualMs}ms (budget ${expectedMs}ms). A database operation ran the entire time without returning \u2014 the connection is likely wedged or contended (SUP-2026-012); a second PAPI session open against the same database is a common cause.${pendingNote} The MCP server is restarting; reconnect with /mcp in Claude Code (or restart your MCP host), and close any other open PAPI session, before the next call.` : `Tool '${toolName}' timed out after ${actualMs}ms (budget ${expectedMs}ms). No single operation was stuck \u2014 this is cumulative query load exceeding the budget, not a wedged pool, and the database is healthy.${pendingNote} Retry the call; \`orient\` runs a lean path by default (heavy enrichment is opt-in via \`full: true\`).`
+    );
+    this.toolName = toolName;
+    this.expectedMs = expectedMs;
+    this.actualMs = actualMs;
+    this.wedged = wedged;
+    this.pendingNote = pendingNote;
+    this.name = "ToolTimeoutError";
+  }
+};
+function classifyTimeout(start, actualMs, budgetMs) {
+  const now = start + actualMs;
+  let oldestPendingMs = 0;
+  const parts = Array.from(inflightWork.entries()).map(([slot, slotStart]) => {
+    const age = now - slotStart;
+    if (age > oldestPendingMs) oldestPendingMs = age;
+    return `${slot}(${age}ms)`;
+  });
+  const pendingNote = parts.length ? ` Pending work at timeout: ${parts.join(", ")}.` : " No pending work registered.";
+  const wedged = oldestPendingMs >= budgetMs * WEDGE_PENDING_FRACTION;
+  return { wedged, pendingNote };
+}
 async function withToolTimeout(name, fn) {
   const ms = toolTimeoutMs(name);
   const start = Date.now();
@@ -25100,15 +26201,18 @@ async function withToolTimeout(name, fn) {
   const timeoutPromise = new Promise((_, reject) => {
     timer2 = setTimeout(() => {
       const actualMs = Date.now() - start;
-      wedgeRecoveryStats.count += 1;
-      const pending = Array.from(inflightWork.entries()).map(([slot, slotStart]) => `${slot}(${actualMs - (slotStart - start)}ms)`).join(", ");
-      const pendingNote = pending ? ` Pending work at timeout: ${pending}.` : " No pending work registered.";
-      console.error(
-        `[papi] Wedge-recovery #${wedgeRecoveryStats.count}: tool '${name}' fired (expected=${ms}ms, actual=${actualMs}ms) (SUP-2026-012).${pendingNote}`
-      );
-      reject(new Error(
-        `Tool '${name}' timed out after ${actualMs}ms (timer set for ${ms}ms). The database pool likely wedged after an interrupted prior call (SUP-2026-012).${pendingNote} The MCP server is exiting now; reconnect with /mcp in Claude Code (or restart your MCP host) before the next call.`
-      ));
+      const { wedged, pendingNote } = classifyTimeout(start, actualMs, ms);
+      if (wedged) {
+        wedgeRecoveryStats.count += 1;
+        console.error(
+          `[papi] Wedge-recovery #${wedgeRecoveryStats.count}: tool '${name}' timed out with a stuck operation (expected=${ms}ms, actual=${actualMs}ms) (SUP-2026-012).${pendingNote}`
+        );
+      } else {
+        console.error(
+          `[papi] Slow timeout (DB healthy, not a wedge): tool '${name}' exceeded its ${ms}ms budget (actual=${actualMs}ms) via cumulative load.${pendingNote}`
+        );
+      }
+      reject(new ToolTimeoutError(name, ms, actualMs, wedged, pendingNote));
     }, ms);
     timer2.unref();
   });
@@ -25166,6 +26270,7 @@ var PAPI_TOOLS = [
   releaseTool,
   reviewListTool,
   reviewSubmitTool,
+  reviewClaimTool,
   initTool,
   orientTool,
   hierarchyUpdateTool,
@@ -25187,6 +26292,8 @@ var PAPI_TOOLS = [
   contributorAddTool,
   contributorRemoveTool,
   contributorListTool,
+  taskClaimTool,
+  taskUnclaimTool,
   inventorySyncTool
 ];
 function getToolMetadata() {
@@ -25290,7 +26397,8 @@ function createServer(adapter2, config2) {
       }
     }
     const timer2 = startTimer();
-    recordToolCall(name);
+    const callerKey = callerKeyFromConfig(config2);
+    recordToolCall(name, callerKey);
     const runHandler = async () => {
       switch (name) {
         case "plan":
@@ -25333,6 +26441,8 @@ function createServer(adapter2, config2) {
           return handleReviewList(adapter2, config2);
         case "review_submit":
           return handleReviewSubmit(adapter2, config2, safeArgs);
+        case "review_claim":
+          return handleReviewClaim(adapter2, config2, safeArgs);
         case "init":
           return handleInit(config2, safeArgs);
         case "orient":
@@ -25375,6 +26485,10 @@ function createServer(adapter2, config2) {
           return handleContributorRemove(adapter2, config2, safeArgs);
         case "contributor_list":
           return handleContributorList(adapter2, config2, safeArgs);
+        case "task_claim":
+          return handleTaskClaim(adapter2, config2, safeArgs);
+        case "task_unclaim":
+          return handleTaskUnclaim(adapter2, config2, safeArgs);
         case "inventory_sync":
           return handleInventorySync(adapter2, config2, safeArgs, getToolMetadata());
         default:
@@ -25383,7 +26497,7 @@ function createServer(adapter2, config2) {
     };
     const meterDecision = await checkMeter(adapter2, name, config2.projectId ?? "session");
     if (meterDecision.blocked && meterDecision.usage) {
-      recordToolOutcome(true);
+      recordToolOutcome(true, callerKey);
       return {
         content: [{ type: "text", text: allowanceExceededMessage(name, meterDecision.usage) }]
       };
@@ -25392,14 +26506,15 @@ function createServer(adapter2, config2) {
     try {
       result = await withToolTimeout(name, runHandler);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (msg.includes("timed out after")) {
-        setImmediate(() => {
-          console.error(`[papi] Exiting after '${name}' timeout (wedge-recovery #${wedgeRecoveryStats.count}); user must reconnect with /mcp before the next call.`);
-          process.exit(2);
-        });
-        recordToolOutcome(false);
-        return { content: [{ type: "text", text: `Error: ${msg}` }] };
+      if (err instanceof ToolTimeoutError) {
+        recordToolOutcome(false, callerKey);
+        if (err.wedged) {
+          setImmediate(() => {
+            console.error(`[papi] Exiting after '${name}' wedge timeout (wedge-recovery #${wedgeRecoveryStats.count}); user must reconnect with /mcp before the next call.`);
+            process.exit(2);
+          });
+        }
+        return { content: [{ type: "text", text: `Error: ${err.message}` }] };
       }
       throw err;
     }
@@ -25425,7 +26540,7 @@ ${usageLine(decision.usage)}`;
     delete result._contextBytes;
     delete result._contextUtilisation;
     const isError = result.content.some((c) => c.text.startsWith("Error:") || c.text.startsWith("\u274C"));
-    recordToolOutcome(!isError);
+    recordToolOutcome(!isError, callerKey);
     try {
       const clientName = server2.getClientVersion()?.name;
       const metric = buildMetric(name, elapsed, usage, void 0, contextBytes, contextUtilisation, clientName);
@@ -25473,6 +26588,28 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 var BEARER_PREFIX = "papi_";
 var BEARER_REGEX = /^(papi_|papi_oauth_)[a-f0-9]{64}$/;
 var RESOURCE_METADATA_URL = process.env["PAPI_RESOURCE_METADATA_URL"] ?? "https://getpapi.ai/.well-known/oauth-protected-resource";
+var FRIENDLY_GET_HTML = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>PAPI MCP server</title>
+<style>
+  body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+    background:#faf6f0;color:#15171c;font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
+  .card{max-width:520px;padding:40px 36px;text-align:center}
+  h1{font-size:22px;margin:0 0 12px;letter-spacing:.2px}
+  p{margin:10px 0;color:#394048}
+  a.btn{display:inline-block;margin-top:18px;padding:11px 20px;border-radius:10px;
+    background:#15171c;color:#faf6f0;text-decoration:none;font-weight:600}
+  code{background:#efe9e0;padding:2px 6px;border-radius:5px;font-size:13px}
+</style></head>
+<body><div class="card">
+  <h1>This is the PAPI MCP server \u{1F44B}</h1>
+  <p>You've reached it in a browser \u2014 that's expected to look empty. This endpoint
+     is meant to be added to your AI tool as a connector, not opened directly.</p>
+  <p>Add it in Claude, Cursor, or any MCP client as a custom connector pointing at
+     <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 MAX_BODY_BYTES = 1 * 1024 * 1024;
 var IP_RATE_WINDOW_MS = 6e4;
 var IP_RATE_MAX = 60;
@@ -25594,6 +26731,13 @@ function startHttpTransport(opts) {
     }
     const bearer = extractBearer(req.headers.authorization);
     if (!bearer) {
+      const accept = req.headers["accept"] ?? "";
+      if (req.method === "GET" && accept.includes("text/html")) {
+        logEvent({ level: "info", msg: "friendly_get", ip, status: 200 });
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", ...cors });
+        res.end(FRIENDLY_GET_HTML);
+        return;
+      }
       const hasHeader = Boolean(req.headers.authorization);
       logEvent({
         level: "warn",
@@ -25707,6 +26851,37 @@ function extractProjectOverride(body) {
   const p = args.project;
   return typeof p === "string" && p.trim().length > 0 ? p.trim() : void 0;
 }
+var PROJECT_OPTIONAL_TOOLS = /* @__PURE__ */ new Set([
+  "init",
+  "setup",
+  "project_list",
+  "project_create",
+  "project_switch"
+]);
+function extractToolName(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const b2 = body;
+  if (b2.method !== "tools/call") return void 0;
+  const name = b2.params?.name;
+  return typeof name === "string" && name.length > 0 ? name : void 0;
+}
+function sendProjectChoice(res, origin, body, projects) {
+  if (res.headersSent) return;
+  const id = (body && typeof body === "object" ? body.id : null) ?? null;
+  const list = projects.map((p) => `  \u2022 ${p.slug}${p.name ? ` \u2014 ${p.name}` : ""}`).join("\n");
+  const text = `You have ${projects.length} PAPI projects, so PAPI can't tell which one this call is for. Pick one and call again with \`project="<slug>"\` (or set the x-papi-project-id header):
+
+${list}
+
+Example: add \`project="${projects[0].slug}"\` to the tool arguments.`;
+  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 {
@@ -25718,7 +26893,37 @@ function resolveEffectiveProjectId(body, headerProjectId) {
 }
 async function dispatchRequest(args) {
   const { req, res, body, bearer, projectId, ip, baseConfig, dataEndpoint } = args;
-  const effectiveProjectId = resolveEffectiveProjectId(body, projectId);
+  let effectiveProjectId = resolveEffectiveProjectId(body, projectId);
+  if (effectiveProjectId === void 0) {
+    const toolName = extractToolName(body);
+    if (toolName && !PROJECT_OPTIONAL_TOOLS.has(toolName)) {
+      let projects = [];
+      try {
+        const probe = new ProxyPapiAdapter({ endpoint: dataEndpoint, apiKey: bearer });
+        projects = await probe.listUserProjects();
+      } catch {
+      }
+      if (projects.length === 1) {
+        effectiveProjectId = projects[0].id;
+        logEvent({
+          level: "info",
+          msg: "project_autobound",
+          ip,
+          bearer_prefix: bearerPrefix(bearer),
+          project_id: effectiveProjectId
+        });
+      } else if (projects.length > 1) {
+        logEvent({
+          level: "info",
+          msg: "project_choice_returned",
+          ip,
+          bearer_prefix: bearerPrefix(bearer)
+        });
+        sendProjectChoice(res, req.headers.origin, body, projects);
+        return;
+      }
+    }
+  }
   const adapter2 = new ProxyPapiAdapter({
     endpoint: dataEndpoint,
     apiKey: bearer,