@papi-ai/server 0.7.67 → 0.7.70

package/dist/index.js

@@ -5210,6 +5210,7 @@ function loadConfig() {
   const baseBranch = process.env.PAPI_BASE_BRANCH ?? "main";
   const autoPR = process.env.PAPI_AUTO_PR !== "false";
   const lightMode = process.env.PAPI_LIGHT_MODE === "true";
+  const autoWorktree = process.env.PAPI_AUTO_WORKTREE === "true";
   const projectOwner = process.env.PAPI_OWNER ?? "Cathal";
   const skipProjectSpecificRules = process.env.PAPI_SKIP_PROJECT_RULES === "true";
   const userId = process.env.PAPI_USER_ID || void 0;
@@ -5283,8 +5284,13 @@ Already have an account? Make sure PAPI_USER_ID is set in your .mcp.json env con
     baseBranch,
     autoPR,
     adapterType,
+    // Local stdio boot: the server runs on the user's machine, so the client
+    // shares its filesystem. The HTTP transport overrides this to false per
+    // request (task-2906).
+    localFilesystem: true,
     papiEndpoint,
     lightMode,
+    autoWorktree,
     projectOwner,
     skipProjectSpecificRules,
     userId,
@@ -9475,11 +9481,16 @@ function buildPlanUserMessage(ctx) {
         ""
       );
     }
-    if (ctx.buildPatterns) {
-      parts.push("### Build Patterns", "", ctx.buildPatterns, "");
+    const enrichment = [];
+    const addEnrichment = (label, ...lines) => {
+      enrichment.push({ label, block: lines.join("\n") });
+    };
+    if (ctx.strategyRecommendations) {
+      addEnrichment("Strategy Recommendations (Pending)", "### Strategy Recommendations (Pending)", "", ctx.strategyRecommendations, "");
     }
     if (ctx.learningPatterns) {
-      parts.push(
+      addEnrichment(
+        "Recurring Learning Patterns",
         "### Recurring Learning Patterns (cross-cycle)",
         "",
         "Tags from cycle learnings (surprises, issues, dead-ends, estimation misses) that keep recurring. Treat a module/theme that recurs across many cycles as a signal: size its tasks up and write a sharper pre-mortem.",
@@ -9489,7 +9500,8 @@ function buildPlanUserMessage(ctx) {
       );
     }
     if (ctx.decisionScorePatterns) {
-      parts.push(
+      addEnrichment(
+        "Decision Risk Scores",
         "### Decision Risk Scores (high-risk + movement)",
         "",
         "Per-decision risk scores (effort+risk+reversibility+scaleCost+lockIn, /25; lower = safer). Decisions flagged \u26A0 high-risk (>15/25) or whose score moved since the last scoring. When a task depends on or advances a \u26A0 high-risk or \u2191 riskier decision, name that decision in the BUILD HANDOFF pre-mortem and lean toward the larger estimate. Do NOT re-score decisions here \u2014 this is read-only input.",
@@ -9498,38 +9510,39 @@ function buildPlanUserMessage(ctx) {
         ""
       );
     }
+    if (ctx.estimationCalibration) {
+      addEnrichment("Estimation Calibration", "### Estimation Calibration (Historical)", "", ctx.estimationCalibration, "");
+    }
     if (ctx.reviewPatterns) {
-      parts.push("### Review Patterns", "", ctx.reviewPatterns, "");
+      addEnrichment("Review Patterns", "### Review Patterns", "", ctx.reviewPatterns, "");
     }
     if (ctx.methodologyMetrics) {
-      parts.push("### Methodology Trends", "", ctx.methodologyMetrics, "");
-    }
-    if (ctx.estimationCalibration) {
-      parts.push("### Estimation Calibration (Historical)", "", ctx.estimationCalibration, "");
+      addEnrichment("Methodology Trends", "### Methodology Trends", "", ctx.methodologyMetrics, "");
     }
     if (ctx.horizonContext) {
-      parts.push("### Forward Horizon", "", ctx.horizonContext, "");
-    }
-    if (ctx.strategyRecommendations) {
-      parts.push("### Strategy Recommendations (Pending)", "", ctx.strategyRecommendations, "");
+      addEnrichment("Forward Horizon", "### Forward Horizon", "", ctx.horizonContext, "");
     }
-    if (ctx.dogfoodEntries) {
-      parts.push("### Dogfood Observations (Recent)", "", ctx.dogfoodEntries, "");
+    if (ctx.buildPatterns) {
+      addEnrichment("Build Patterns", "### Build Patterns", "", ctx.buildPatterns, "");
     }
     if (ctx.taskComments) {
-      parts.push("### Task Discussion Threads", "", ctx.taskComments, "");
+      addEnrichment("Task Discussion Threads", "### Task Discussion Threads", "", ctx.taskComments, "");
     }
     if (ctx.recentReviews) {
-      parts.push("### Human Reviews", "", ctx.recentReviews, "");
+      addEnrichment("Human Reviews", "### Human Reviews", "", ctx.recentReviews, "");
+    }
+    if (ctx.dogfoodEntries) {
+      addEnrichment("Dogfood Observations", "### Dogfood Observations (Recent)", "", ctx.dogfoodEntries, "");
     }
     if (ctx.discoveryCanvas) {
-      parts.push("### Discovery Canvas", "", ctx.discoveryCanvas, "");
+      addEnrichment("Discovery Canvas", "### Discovery Canvas", "", ctx.discoveryCanvas, "");
     }
     if (ctx.registeredDocs) {
-      parts.push("### Relevant Research Docs", "", ctx.registeredDocs, "");
+      addEnrichment("Relevant Research Docs", "### Relevant Research Docs", "", ctx.registeredDocs, "");
     }
     if (ctx.unactionedDocs) {
-      parts.push(
+      addEnrichment(
+        "Unactioned Research",
         "### Unactioned Research (soft-warn)",
         "",
         "These registered docs still have pending actions. Before adding net-new tasks, consider whether one of these unactioned items should be promoted into this cycle via `doc_action_promote`. Surface this in your plan output so the user can decide.",
@@ -9539,7 +9552,31 @@ function buildPlanUserMessage(ctx) {
       );
     }
     if (ctx.carryForwardStaleness) {
-      parts.push("### Carry-Forward Staleness", "", ctx.carryForwardStaleness, "");
+      addEnrichment("Carry-Forward Staleness", "### Carry-Forward Staleness", "", ctx.carryForwardStaleness, "");
+    }
+    const contextBudget = Number(process.env.PAPI_PLAN_CONTEXT_BUDGET) || 9e4;
+    const coreBytes = Buffer.byteLength(parts.join("\n"), "utf-8");
+    let enrichmentSpent = 0;
+    const elidedLabels = [];
+    for (const { label, block } of enrichment) {
+      const cost = Buffer.byteLength(`
+${block}`, "utf-8");
+      if (coreBytes + enrichmentSpent + cost > contextBudget) {
+        elidedLabels.push(label);
+        continue;
+      }
+      parts.push(block);
+      enrichmentSpent += cost;
+    }
+    if (elidedLabels.length > 0) {
+      parts.push(
+        "### Context Budget \u2014 enrichment sections trimmed",
+        "",
+        `${elidedLabels.length} non-essential context section(s) were omitted to keep this plan payload under ${Math.round(contextBudget / 1024)} KB \u2014 a mature board otherwise overflows the client's tool-result ceiling and the plan output is spilled to a file. Trimmed (lowest-value first): ${elidedLabels.join(", ")}.`,
+        "",
+        "These are cross-cycle analytics/enrichment, NOT task-selection inputs \u2014 the Board, Active Decisions, Product Brief, Full Notes, and Recent Build Reports above are complete and untrimmed. Plan normally. If you specifically need one of the trimmed sections, raise `PAPI_PLAN_CONTEXT_BUDGET` in the MCP server env and re-run.",
+        ""
+      );
     }
   }
   return parts.join("\n");
@@ -9928,6 +9965,19 @@ function buildReviewUserMessage(ctx) {
   } else {
     parts.push("(Showing build reports and cycle log entries since last strategy review.)");
   }
+  if (ctx.earnedPushback) {
+    parts.push(
+      "",
+      "---",
+      "",
+      "## \u26A0\uFE0F EARNED ADVERSARIAL PUSHBACK",
+      "",
+      "This section appears ONLY because concrete signals crossed a threshold this window. Address each item in your review with a clearly-labelled pushback callout: verify the claim against the actual build reports / code / decisions before accepting it, and push back proportionally to the stakes. If verification shows a signal is benign, say so and move on. Do NOT manufacture additional pushback beyond what these signals support.",
+      "",
+      ctx.earnedPushback,
+      ""
+    );
+  }
   parts.push(
     "",
     "---",
@@ -10679,6 +10729,14 @@ function validateHandoffScope(handoff) {
   if (!isMeaningful(handoff.scopeBoundary)) invalid.push("scopeBoundary");
   return invalid;
 }
+function assertHandoffApplyPayloadNonEmpty(data, cycleNumber) {
+  const handoffCount = data.cycleHandoffs?.length ?? 0;
+  if (handoffCount === 0) {
+    throw new Error(
+      `Handoff apply rejected: trimmed/empty apply payload \u2014 nothing persisted. The parsed output for Cycle ${cycleNumber} carries NO handoffs (cycleHandoffs is empty), but handoff prepare only runs when at least one task needs a handoff \u2014 so the handoffs were dropped. The most likely cause is a truncated apply JSON: the output overflowed the client tool-result ceiling (see task-2905/2906). Re-run handoff_generate and resend the COMPLETE structured output \u2014 ensure the JSON after the <!-- PAPI_STRUCTURED_OUTPUT --> marker includes the full cycleHandoffs array.`
+    );
+  }
+}
 async function prepareHandoffs(adapter2, _config, taskIds, force = false) {
   const timer2 = startTimer();
   const cycles = await adapter2.readCycles();
@@ -10735,10 +10793,8 @@ async function applyHandoffs(adapter2, rawLlmOutput, cycleNumber, force = false)
   if (!data) {
     throw new Error("Could not parse structured output. Ensure your output includes <!-- PAPI_STRUCTURED_OUTPUT --> with valid JSON.");
   }
+  assertHandoffApplyPayloadNonEmpty(data, cycleNumber);
   const handoffs = data.cycleHandoffs ?? [];
-  if (handoffs.length === 0) {
-    throw new Error("No cycleHandoffs found in structured output. Ensure your output includes handoffs in the cycleHandoffs array.");
-  }
   const taskIdsToWrite = handoffs.map((h) => h.taskId);
   const existingHandoffSet = /* @__PURE__ */ new Set();
   try {
@@ -12794,11 +12850,24 @@ Run \`strategy_review\` first, or pass \`force: true\` to bypass this gate.`
   }
   return { mode, cycleNumber, strategyReviewWarning };
 }
+function assertApplyPayloadNonEmpty(data, cycleNumber) {
+  const handoffCount = data.cycleHandoffs?.length ?? 0;
+  const taskIdCount = data.cycleTaskIds?.length ?? 0;
+  const newTaskCount = data.newTasks?.length ?? 0;
+  if (handoffCount + taskIdCount + newTaskCount === 0) {
+    throw new Error(
+      `Plan apply rejected: trimmed/partial apply payload \u2014 nothing persisted. The parsed plan for Cycle ${cycleNumber + 1} assigns NO tasks to the cycle (cycleHandoffs, cycleTaskIds and newTasks are all empty). Writing it would create a cycle row with zero task membership and no handoffs \u2014 the phantom-empty-cycle failure mode that renders an empty Team view. The most likely cause is a truncated apply JSON: the prepare payload overflowed the client tool-result ceiling (see task-2905/2906). Re-run the plan and resend the COMPLETE structured output \u2014 ensure the JSON after the <!-- PAPI_STRUCTURED_OUTPUT --> marker includes the full cycleHandoffs array (or cycleTaskIds when using skip_handoffs).`
+    );
+  }
+}
 async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber, contextHashes, planRunMeta) {
   const applyStartMs = Date.now();
   const applyScope = await resolvePlanScope(adapter2, config2);
   await assertSingleActiveCycle(adapter2, { allowNumber: cycleNumber + 1, userId: applyScope.callerUserId ?? void 0 });
   const { displayText, data } = parseStructuredOutput(rawOutput);
+  if (data) {
+    assertApplyPayloadNonEmpty(data, cycleNumber);
+  }
   let resolvedDisplayText = displayText;
   let autoCommitNote = "";
   let priorityLockNote = "";
@@ -13276,7 +13345,15 @@ function buildSubagentDispatchPrompt(input) {
 - "pass" = no blocking issues; "warn" = minor/non-blocking nits; "fail" = blocking issues that should send the build back. \`file\`/\`line\` are optional per finding. Empty \`findings\` is valid when clean.` : `- Read the system prompt and context exactly as the main agent would.
 - Produce the full structured output the system prompt requires (Part 1 markdown + Part 2 JSON after \`<!-- PAPI_STRUCTURED_OUTPUT -->\`, or whatever the system prompt specifies).
 - Return ONLY that output \u2014 no preamble, no commentary, no closing summary. The dispatching agent will pass your reply verbatim to the apply call.`;
-  const contextBlock = isReview ? `<review_rubric>
+  const contextBlock = input.contextFilePath ? isReview ? `The review rubric and the full build-under-review context have been written to a local file:
+
+${input.contextFilePath}
+
+Read that file IN FULL (it contains the rubric and the build report + diff) before you start. Do not skip it \u2014 it is your only source of context.` : `The system prompt and full planning context have been written to a local file:
+
+${input.contextFilePath}
+
+Read that file IN FULL before you produce anything \u2014 it contains the system prompt and all context you need. Do not skip it; it is your only source of context.` : isReview ? `<review_rubric>
 ${systemPrompt}
 </review_rubric>
 
@@ -13591,6 +13668,58 @@ async function buildSessionGuidance(callerKey) {
   return signals.slice(0, 3);
 }
 
+// src/services/onboarding-coaching.ts
+var ONBOARDING_EARLY_CYCLE_MAX = 2;
+var MAX_COACHING_LINES = 4;
+var COACH_CONNECT_REPO = "No repository is linked to this project yet. Link your repo from the dashboard Settings (or capture it during `setup`) so builds, reviews, and releases attach to the right codebase.";
+var COACH_ROOT_DIR = "Before building, confirm this session is running from your project root directory, so commits and builds land against the right files.";
+var COACH_CLICKABLE_TASKS = "Task cards on your dashboard expand on click. Open one to read its full build handoff, comments, and history.";
+var COACH_OFF_CYCLE = 'When a request falls outside the current cycle, keep it in the loop: `idea "<what you want>"` parks it in the backlog, or promote it into the cycle and generate a build handoff before you build.';
+var COACH_SESSION_START = 'Start of a session: skim your Active Decisions (the AD summary from `orient`, or `strategy_review`) to reload your project direction, and capture anything new with `idea "<what you want>"`.';
+var COACH_NO_DECISIONS = 'No Active Decisions recorded yet. Capture your first with `idea "<a direction or constraint>"` so your project starts steering itself.';
+var COACH_BACKLOG_IMPORT = "Already tracking a backlog elsewhere (Linear, a CSV, a markdown checklist)? Bring it over in one pass with `backlog_import` instead of retyping it.";
+var ONBOARDING_COACHING_HEADING = "## Getting Started";
+function buildOnboardingCoaching(state) {
+  const lines = [];
+  const isEarly = state.cycleNumber <= ONBOARDING_EARLY_CYCLE_MAX;
+  const { surface } = state;
+  if (state.repoConnected === false && (surface === "orient" || surface === "plan")) {
+    lines.push(COACH_CONNECT_REPO);
+  }
+  if (state.hasLocalWorkspace && (surface === "setup" || surface === "orient" && isEarly)) {
+    lines.push(COACH_ROOT_DIR);
+  }
+  if ((surface === "orient" || surface === "setup") && isEarly) {
+    lines.push(COACH_CLICKABLE_TASKS);
+  }
+  if ((surface === "orient" || surface === "plan") && state.hasActiveCycle && isEarly) {
+    lines.push(COACH_OFF_CYCLE);
+  }
+  if (surface === "orient" && isEarly) {
+    lines.push(state.hasActiveDecisions === false ? COACH_NO_DECISIONS : COACH_SESSION_START);
+  }
+  if (surface === "plan" && state.bootstrapPlan === true) {
+    lines.push(COACH_BACKLOG_IMPORT);
+  }
+  return lines.slice(0, MAX_COACHING_LINES);
+}
+function formatOnboardingCoachingBlock(state) {
+  const lines = buildOnboardingCoaching(state);
+  if (lines.length === 0) return "";
+  return `
+
+${ONBOARDING_COACHING_HEADING}
+${lines.map((l) => `- ${l}`).join("\n")}`;
+}
+
+// src/lib/hosted-mode.ts
+function isHostedTransport() {
+  return Boolean(process.env.PORT || process.env.PAPI_HTTP_PORT);
+}
+function hasLocalWorkspace() {
+  return !isHostedTransport();
+}
+
 // src/lib/per-caller-cache.ts
 var DEFAULT_CALLER_KEY2 = "__default__";
 var MAX_PER_CALLER_ENTRIES = 1e3;
@@ -13682,6 +13811,15 @@ function clearPrepareSpill(projectId, callerKey) {
   } catch {
   }
 }
+function contextPath(projectId, callerKey) {
+  const id = createHash2("sha256").update(`${projectId ?? "no-project"}|${callerKey ?? DEFAULT_CALLER_KEY3}`).digest("hex").slice(0, 16);
+  return join3(tmpdir(), `papi-plan-context-${id}.md`);
+}
+function savePrepareContextFile(projectId, callerKey, content) {
+  const path7 = contextPath(projectId, callerKey);
+  writeFileSync2(path7, content, { mode: 384 });
+  return path7;
+}
 
 // src/tools/plan.ts
 var planPrepareCache = new PerCallerCache();
@@ -13690,6 +13828,7 @@ var planTool = {
   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`.',
   annotations: { title: "Plan Cycle", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
     properties: {
       mode: {
@@ -13760,7 +13899,16 @@ var planTool = {
         description: 'Apply-mode confirmation guard for planner-initiated cancellations (task-1727). When false (default), any boardCorrection with status="Cancelled" is SKIPPED and listed in the response so the user can confirm before destructive writes. Set true to apply the cancellations. board_edit-direct cancellations are unaffected \u2014 this guard is plan-only.'
       }
     },
-    required: []
+    required: [],
+    // task-2802: mirror resolveLlmResponse — llm_response and llm_response_file are
+    // mutually exclusive, and an apply call must carry exactly one of them.
+    not: { required: ["llm_response", "llm_response_file"] },
+    allOf: [
+      {
+        if: { properties: { mode: { const: "apply" } }, required: ["mode"] },
+        then: { anyOf: [{ required: ["llm_response"] }, { required: ["llm_response_file"] }] }
+      }
+    ]
   }
 };
 function formatPlanResult(result) {
@@ -13815,6 +13963,10 @@ function formatPlanResult(result) {
   } else {
     lines.push("", `Next: run \`build_list\` to see your cycle tasks, then \`build_execute <task_id>\` to start building.`);
   }
+  if (result.onboardingCoaching && result.onboardingCoaching.length > 0) {
+    lines.push("", ONBOARDING_COACHING_HEADING);
+    for (const c of result.onboardingCoaching) lines.push(`- ${c}`);
+  }
   if (result.contextBytes !== void 0) {
     const kb = (result.contextBytes / 1024).toFixed(1);
     lines.push(`---`, `Context: ${kb}KB`);
@@ -13896,7 +14048,15 @@ async function handlePlan(adapter2, config2, args) {
       }, tracker);
       const planProjectInfo = adapter2.getProjectInfo ? await adapter2.getProjectInfo().catch(() => null) : null;
       const projectBanner = planProjectInfo ? getProjectConnectionBanner(planProjectInfo.name, planProjectInfo.slug) ?? void 0 : void 0;
-      const response = formatPlanResult({ ...result, contextUtilisation: utilisation, contextBytes, skipHandoffs, projectBanner });
+      const onboardingCoaching = buildOnboardingCoaching({
+        surface: "plan",
+        repoConnected: planProjectInfo ? !!planProjectInfo.repo_url : void 0,
+        hasLocalWorkspace: hasLocalWorkspace(),
+        cycleNumber: result.cycleNumber + 1,
+        hasActiveCycle: true,
+        bootstrapPlan: result.mode === "bootstrap"
+      });
+      const response = formatPlanResult({ ...result, contextUtilisation: utilisation, contextBytes, skipHandoffs, projectBanner, onboardingCoaching });
       return {
         ...response,
         ...contextBytes !== void 0 ? { _contextBytes: contextBytes } : {},
@@ -13929,6 +14089,27 @@ async function handlePlan(adapter2, config2, args) {
       } else {
         dispatch = "inline";
       }
+      const modeLabel = result.mode === "bootstrap" ? "Bootstrap" : "Full";
+      const header = result.strategyReviewWarning ? `${result.strategyReviewWarning}
+` : "";
+      let contextFilePath;
+      if (config2.localFilesystem) {
+        const contextDoc = `### System Prompt
+
+${result.systemPrompt}
+
+---
+
+### Context
+
+${result.userMessage}
+`;
+        try {
+          contextFilePath = savePrepareContextFile(adapter2.getProjectId?.(), callerKey, contextDoc);
+        } catch {
+          contextFilePath = void 0;
+        }
+      }
       if (dispatch === "subagent") {
         const dispatchPrompt = buildSubagentDispatchPrompt({
           tool: "plan",
@@ -13937,16 +14118,34 @@ async function handlePlan(adapter2, config2, args) {
           strategyReviewWarning: result.strategyReviewWarning,
           systemPrompt: result.systemPrompt,
           userMessage: result.userMessage,
-          contextBytes: result.contextBytes
+          contextBytes: result.contextBytes,
+          contextFilePath
         });
-        const header2 = result.strategyReviewWarning ? `${result.strategyReviewWarning}
+        const dispatchHeader = result.strategyReviewWarning ? `${result.strategyReviewWarning}
 
 ` : "";
-        return { ...textResponse(`${header2}${dispatchPrompt}`), _contextBytes: result.contextBytes };
+        return { ...textResponse(`${dispatchHeader}${dispatchPrompt}`), _contextBytes: result.contextBytes };
+      }
+      if (contextFilePath) {
+        const kb = result.contextBytes !== void 0 ? ` (~${(result.contextBytes / 1024).toFixed(0)} KB)` : "";
+        const pathResponse = textResponse(
+          `${header}## PAPI Cycle Plan \u2014 Prepare Phase (${modeLabel} Mode, Cycle ${result.cycleNumber + 1})
+
+The full planning brief \u2014 system prompt + all context${kb} \u2014 has been written to a local file to keep it off the tool-result channel (it overflows the client ceiling on a mature board):
+
+\`${contextFilePath}\`
+
+**Do this:**
+1. **Read that file in full** \u2014 it is the system prompt and the entire planning context.
+2. Produce the complete plan output in TWO parts: Part 1 markdown with BUILD HANDOFF blocks, then after \`<!-- PAPI_STRUCTURED_OUTPUT -->\` a Part 2 JSON block.
+3. **Write your output to a local file**, then call \`plan\` again with:
+   - \`mode\`: "apply"
+   - \`llm_response_file\`: the absolute path to YOUR output file
+   - \`cycle_number\`: ${result.cycleNumber + 1}
+   - \`strategy_review_warning\`: "${result.strategyReviewWarning.replace(/"/g, '\\"')}"`
+        );
+        return { ...pathResponse, _contextBytes: result.contextBytes };
       }
-      const modeLabel = result.mode === "bootstrap" ? "Bootstrap" : "Full";
-      const header = result.strategyReviewWarning ? `${result.strategyReviewWarning}
-` : "";
       const response = textResponse(
         `${header}## PAPI Cycle Plan \u2014 Prepare Phase (${modeLabel} Mode, Cycle ${result.cycleNumber + 1})
 
@@ -14009,14 +14208,6 @@ import { existsSync as existsSync2, readdirSync, statSync as statSync2 } from "f
 import { join as join4 } from "path";
 import { homedir as homedir2 } from "os";
 
-// src/lib/hosted-mode.ts
-function isHostedTransport() {
-  return Boolean(process.env.PORT || process.env.PAPI_HTTP_PORT);
-}
-function hasLocalWorkspace() {
-  return !isHostedTransport();
-}
-
 // src/services/idea.ts
 import { randomUUID as randomUUID9 } from "crypto";
 var OWNER_ACTION_PATTERNS = [
@@ -14564,6 +14755,55 @@ function generateValueReport(snapshots) {
   return lines.join("\n");
 }
 
+// src/lib/earned-pushback.ts
+var SIGNAL_MIN_COUNT = 3;
+var EFFORT_RANK = { XS: 0, S: 1, M: 2, L: 3, XL: 4 };
+function rankEffort(size2) {
+  if (!size2) return void 0;
+  return EFFORT_RANK[size2];
+}
+function computeEarnedPushback(inputs) {
+  const { reports, log: log2, doneTaskIds } = inputs;
+  const drifted = reports.filter(
+    (r) => r.scopeAccuracy && r.scopeAccuracy !== "accurate" || !!r.scopeDriftSignal
+  );
+  const crept = reports.filter((r) => {
+    const actual = rankEffort(r.actualEffort);
+    const estimated = rankEffort(r.estimatedEffort);
+    return actual !== void 0 && estimated !== void 0 && actual > estimated;
+  });
+  const staleness = computeCarryForwardStaleness(log2, doneTaskIds);
+  const driftFires = drifted.length >= SIGNAL_MIN_COUNT;
+  const creepFires = crept.length >= SIGNAL_MIN_COUNT;
+  const deferralFires = staleness !== void 0;
+  if (!driftFires && !creepFires && !deferralFires) return void 0;
+  const sections = [
+    "The following signals crossed a threshold this window and warrant adversarial scrutiny. For each, verify the claim against the actual reports/code before accepting it, and push back proportionally to the stakes \u2014 do NOT wave it through, and do NOT invent pushback beyond what these signals support."
+  ];
+  if (driftFires) {
+    const named = drifted.slice(0, 8).map((r) => {
+      const why = r.scopeDriftSignal ? `files diverged from handoff` : `scope ${r.scopeAccuracy}`;
+      return `  - **${r.displayId ?? r.taskId}** (${r.taskName}) \u2014 ${why}`;
+    }).join("\n");
+    sections.push(
+      `**Scope drift (${drifted.length} build${drifted.length === 1 ? "" : "s"}):** handoff scope did not match what was actually built. Verify whether the plan or the execution was wrong, and whether an Active Decision or planning heuristic needs to change.
+${named}`
+    );
+  }
+  if (creepFires) {
+    const named = crept.slice(0, 8).map((r) => `  - **${r.displayId ?? r.taskId}** (${r.taskName}) \u2014 estimated ${r.estimatedEffort}, actual ${r.actualEffort}`).join("\n");
+    sections.push(
+      `**Scope creep (${crept.length} task${crept.length === 1 ? "" : "s"}):** actual effort exceeded the estimate. Check whether these were under-scoped at plan time or grew mid-build, and whether cycle sizing is drifting.
+${named}`
+    );
+  }
+  if (deferralFires) {
+    sections.push(`**Repeat deferral (3+ consecutive cycles):**
+${staleness}`);
+  }
+  return sections.join("\n\n");
+}
+
 // src/services/strategy.ts
 var STRATEGY_DUPE_COVERAGE_THRESHOLD = 0.6;
 function taskStatusLabel(task) {
@@ -15071,10 +15311,10 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
   try {
     const comments = await adapter2.getRecentTaskComments?.(50);
     if (comments && comments.length > 0) {
-      const doneTaskIds = new Set(recentDoneTasks.map((t) => t.id));
+      const doneTaskIds2 = new Set(recentDoneTasks.map((t) => t.id));
       const inReviewTasks = activeTasks.filter((t) => t.status === "In Review");
       const reviewWindowTaskIds = /* @__PURE__ */ new Set([
-        ...doneTaskIds,
+        ...doneTaskIds2,
         ...inReviewTasks.map((t) => t.id)
       ]);
       const filtered = comments.filter((c) => reviewWindowTaskIds.has(c.taskId));
@@ -15104,7 +15344,7 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
   try {
     if (docsWithPendingActions && docsWithPendingActions.length > 0) {
       const STALE_THRESHOLD = 20;
-      const doneTaskIds = new Set(recentDoneTasks.map((t) => t.displayId ?? t.id));
+      const doneTaskIds2 = new Set(recentDoneTasks.map((t) => t.displayId ?? t.id));
       const completed = [];
       const deferred = [];
       const stale = [];
@@ -15114,7 +15354,7 @@ ${unregistered.slice(0, 10).map((f) => `- ${f}`).join("\n")}`;
         const ageInCycles = cycleNumber - (doc.cycleCreated ?? cycleNumber);
         for (const action of pendingActions) {
           const line = `  - **${doc.title}** (C${doc.cycleCreated ?? "?"}): ${action.description}${action.linkedTaskId ? ` [\u2192${action.linkedTaskId}]` : ""}`;
-          if (action.linkedTaskId && doneTaskIds.has(action.linkedTaskId)) {
+          if (action.linkedTaskId && doneTaskIds2.has(action.linkedTaskId)) {
             completed.push(line);
           } else if (ageInCycles > STALE_THRESHOLD) {
             stale.push(line);
@@ -15161,6 +15401,10 @@ ${lines.join("\n")}`;
     { label: "taskComments", hasData: taskCommentsText !== void 0 },
     { label: "docActionStaleness", hasData: docActionStalenessText !== void 0 }
   ]);
+  const doneTaskIds = new Set(
+    recentDoneTasks.map((t) => t.displayId ?? t.id).filter((id) => !!id)
+  );
+  const earnedPushback = computeEarnedPushback({ reports, log: recentLog, doneTaskIds });
   const context = {
     sessionNumber: cycleNumber,
     lastReviewCycle: lastReviewCycleNum,
@@ -15169,6 +15413,7 @@ ${lines.join("\n")}`;
     allBuildReports: buildReportsText,
     sessionLog: formatCycleLog(recentLog),
     board: smartBoard,
+    earnedPushback,
     humanReviews: formatReviews(reviews),
     buildPatterns: buildPatternsText,
     reviewPatterns: reviewPatternsText,
@@ -15419,6 +15664,13 @@ ${cleanContent}`;
     } catch {
     }
   }
+  if (data.hierarchyUpdates && data.hierarchyUpdates.length > 0) {
+    try {
+      await applyHierarchyUpdates(adapter2, data.hierarchyUpdates);
+    } catch (err) {
+      console.error("[strategy] applyHierarchyUpdates failed:", err instanceof Error ? err.message : String(err));
+    }
+  }
   const compressionThreshold = cycleNumber - 5;
   if (compressionThreshold > 0 && data.sessionLogCompressionSummary) {
     await adapter2.compressCycleLog(compressionThreshold, data.sessionLogCompressionSummary);
@@ -15696,6 +15948,79 @@ function buildPhaseLabel(phase) {
   if (!numMatch) return phase.label;
   return `Phase ${numMatch[1]}: ${phase.label}`;
 }
+function nextHierarchySort(existing) {
+  return existing.length === 0 ? 10 : Math.max(...existing.map((e) => e.sortOrder)) + 10;
+}
+async function applyHierarchyUpdates(adapter2, updates) {
+  if (!adapter2.readStages || !adapter2.readHorizons) return;
+  const findHorizon = async (ref) => (await adapter2.readHorizons()).find(
+    (h) => h.slug === ref || h.id === ref || h.label.toLowerCase() === ref.toLowerCase()
+  );
+  const findStage = async (ref) => (await adapter2.readStages()).find(
+    (s) => s.slug === ref || s.id === ref || s.label.toLowerCase() === ref.toLowerCase()
+  );
+  for (const u of updates) {
+    if (u.level === "horizon") {
+      if (u.action === "create") {
+        if (!await findHorizon(u.slug) && adapter2.createHorizon) {
+          const horizons = await adapter2.readHorizons();
+          await adapter2.createHorizon({
+            slug: u.slug,
+            label: u.label ?? u.slug,
+            status: u.status ?? "In Progress",
+            sortOrder: u.sortOrder ?? nextHierarchySort(horizons)
+          });
+        }
+      } else if (u.action === "update_status" && u.status && adapter2.updateHorizonStatus) {
+        const h = await findHorizon(u.slug);
+        if (h) await adapter2.updateHorizonStatus(h.id, u.status);
+      }
+      continue;
+    }
+    if (u.action === "update_criterion" && u.criterionId && typeof u.met === "boolean" && adapter2.setCriterionMet) {
+      const s = await findStage(u.slug);
+      if (s) await adapter2.setCriterionMet(s.id, u.criterionId, u.met, u.evidence ?? null);
+    } else if (u.action === "update_status" && u.status && adapter2.updateStageStatus) {
+      const s = await findStage(u.slug);
+      if (s) await adapter2.updateStageStatus(s.id, u.status);
+    } else if (u.action === "create") {
+      await createStageFromUpdate(adapter2, u, findStage, findHorizon);
+    } else if (u.action === "advance" && adapter2.updateStageStatus) {
+      const current = await findStage(u.slug);
+      if (current) await adapter2.updateStageStatus(current.id, "Done");
+      const newRef = u.newStageSlug ?? u.slug;
+      const existingNext = await findStage(newRef);
+      if (existingNext) {
+        await adapter2.updateStageStatus(existingNext.id, "In Progress");
+      } else if (u.newStageLabel) {
+        await createStageFromUpdate(
+          adapter2,
+          { ...u, slug: newRef, label: u.newStageLabel, status: "In Progress", horizon: u.horizon ?? current?.horizonId },
+          findStage,
+          findHorizon
+        );
+      }
+    }
+  }
+}
+async function createStageFromUpdate(adapter2, u, findStage, findHorizon) {
+  if (!adapter2.createStage || !adapter2.readStages || !adapter2.readHorizons) return;
+  if (await findStage(u.slug)) return;
+  const horizons = await adapter2.readHorizons();
+  const parent = u.horizon ? await findHorizon(u.horizon) : horizons.length === 1 ? horizons[0] : horizons.find((h) => h.status === "In Progress");
+  if (!parent) return;
+  const stagesInHorizon = (await adapter2.readStages()).filter((s) => s.horizonId === parent.id);
+  const id = await adapter2.createStage({
+    slug: u.slug,
+    label: u.label ?? u.slug,
+    status: u.status ?? "Not Started",
+    sortOrder: u.sortOrder ?? nextHierarchySort(stagesInHorizon),
+    horizonId: parent.id
+  });
+  if (id && u.exitCriteria?.length && adapter2.updateStageExitCriteria) {
+    await adapter2.updateStageExitCriteria(id, u.exitCriteria);
+  }
+}
 async function applyPhaseUpdates(adapter2, currentPhases, updates) {
   const phasesById = new Map(currentPhases.map((p) => [p.id, p]));
   const labelMigrations = [];
@@ -16644,6 +16969,7 @@ var boardViewTool = {
   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: { title: "View Board", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
     properties: {
       task_id: {
@@ -16668,10 +16994,14 @@ var boardViewTool = {
       },
       limit: {
         type: "number",
+        minimum: 1,
+        default: 50,
         description: "Max tasks to return (default: 50)."
       },
       offset: {
         type: "number",
+        minimum: 0,
+        default: 0,
         description: "Skip first N tasks for pagination (default: 0)."
       },
       mode: {
@@ -16688,6 +17018,7 @@ var boardDeprioritiseTool = {
   description: `Remove a task from the current cycle. Four actions: "backlog" (not now, maybe later \u2014 preserves handoff), "defer" (valid but premature \u2014 hidden from planner), "block" (waiting on external dependency \u2014 visible on board but skipped by planner), "cancel" (don't want this \u2014 permanently closed with reason). When a user rejects a task, ALWAYS ask which action they want. Does not call the Anthropic API.`,
   annotations: { title: "Deprioritise Task", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
     properties: {
       task_id: {
@@ -16725,7 +17056,21 @@ var boardDeprioritiseTool = {
         description: 'Optional new phase (only applies to "backlog" and "defer" actions).'
       }
     },
-    required: ["task_id"]
+    required: ["task_id"],
+    // task-2802: mirror the handler's guards so the agent sees the dependency up
+    // front. handleBoardDeprioritise requires `reason` for both block and cancel,
+    // and requires `blocker_ref` whenever `blocker_type` is set. Keyed on explicit
+    // values — an omitted action defaults to "backlog" and triggers neither.
+    allOf: [
+      {
+        if: { properties: { action: { enum: ["block", "cancel"] } }, required: ["action"] },
+        then: { required: ["reason"] }
+      },
+      {
+        if: { required: ["blocker_type"] },
+        then: { required: ["blocker_ref"] }
+      }
+    ]
   }
 };
 var boardArchiveTool = {
@@ -16752,7 +17097,15 @@ var boardEditTool = {
   description: "Edit fields on an existing task. Supports title, priority, complexity, module, epic, phase, notes (with notes_mode for append/replace/clear), status, maturity, and cycle (number or null). Pass task_id plus any fields to update. Does not call the Anthropic API.",
   annotations: { title: "Edit Task", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
+    // task-2802: shared effort-size enum referenced by estimated_effort/actual_effort.
+    $defs: {
+      effortSize: {
+        type: "string",
+        enum: ["XS", "S", "M", "L", "XL"]
+      }
+    },
     properties: {
       task_id: {
         type: "string",
@@ -16808,13 +17161,11 @@ var boardEditTool = {
         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."
       },
       estimated_effort: {
-        type: "string",
-        enum: ["XS", "S", "M", "L", "XL"],
+        $ref: "#/$defs/effortSize",
         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"],
+        $ref: "#/$defs/effortSize",
         description: "task-2182: correct the actual effort on this task's LATEST build report (fixes a mis-recorded actual)."
       }
     },
@@ -17246,6 +17597,9 @@ var PROJECT_BUNDLE_REL = join6(".agents", "skills", "papi-cycle");
 function bundleDestRel(rel) {
   return rel === "AGENTS.md" ? "AGENTS.md" : join6(PROJECT_BUNDLE_REL, rel);
 }
+function claudeSkillDestRel(rel) {
+  return rel === "AGENTS.md" ? void 0 : join6(".claude", "skills", rel);
+}
 function resolveBundleDir() {
   let dir = dirname(fileURLToPath(import.meta.url));
   for (let i = 0; i < 5; i++) {
@@ -17274,10 +17628,13 @@ function readBundleFiles(bundleDir = resolveBundleDir()) {
 function planBundleInstall(projectRoot, projectName, opts = {}) {
   const out = {};
   for (const f of readBundleFiles()) {
-    const dest = join6(projectRoot, bundleDestRel(f.rel));
-    if (opts.skipExisting && existsSync4(dest) && statSync4(dest).isFile()) continue;
     const content = f.rel === "AGENTS.md" ? f.content.replace(/\{\{project_name\}\}/g, projectName) : f.content;
-    out[dest] = content;
+    for (const rel of [bundleDestRel(f.rel), claudeSkillDestRel(f.rel)]) {
+      if (!rel) continue;
+      const dest = join6(projectRoot, rel);
+      if (opts.skipExisting && existsSync4(dest) && statSync4(dest).isFile()) continue;
+      out[dest] = content;
+    }
   }
   return out;
 }
@@ -17565,7 +17922,7 @@ var CLAUDE_MD_ENRICHMENT_SENTINEL_T1 = "<!-- PAPI_ENRICHMENT_TIER_1 -->";
 var CLAUDE_MD_ENRICHMENT_SENTINEL_T2 = "<!-- PAPI_ENRICHMENT_TIER_2 -->";
 var CLAUDE_MD_STUB = `# {{project_name}}
 
-This project is managed with **PAPI**. The agent harness \u2014 session workflow, the plan \u2192 build \u2192 review cycle, branching, and conventions \u2014 lives in **\`AGENTS.md\`** (always loaded) plus lazy-loaded phase skills under \`.agents/skills/papi-cycle/\`.
+This project is managed with **PAPI**. The agent harness \u2014 session workflow, the plan \u2192 build \u2192 review cycle, branching, and conventions \u2014 lives in **\`AGENTS.md\`** (always loaded) plus lazy-loaded phase skills under \`.agents/skills/papi-cycle/\` (Claude Code loads the same phase skills natively from \`.claude/skills/papi-*\`).
 
 **At session start: read \`AGENTS.md\`, then run \`orient\`.** Phase mechanics (planning, building, strategy, ideas) load on demand from the skills bundle. Add project-specific notes below this line \u2014 they will not be overwritten.
 
@@ -18896,8 +19253,14 @@ ${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
 **Important:** This is a remote PAPI connection, so the server could not write to your project directory. Setup prepared your files (${harnessFiles}, .claude/settings.json, docs/) and returned them in the scaffolding section below \u2014 **write each one to disk, then commit** before running \`build_execute\` (it requires a clean working directory).` : `
 
 **Important:** Setup created/modified files (${harnessFiles}, .claude/settings.json, docs/). Commit these changes before running \`build_execute\` \u2014 it requires a clean working directory.`;
+  const coachingNote = formatOnboardingCoachingBlock({
+    surface: "setup",
+    hasLocalWorkspace: hasLocalWorkspace(),
+    cycleNumber: 0,
+    hasActiveCycle: false
+  });
   return textResponse(
-    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}${filesNote}
+    `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${northStarNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}${filesNote}${coachingNote}
 
 Tip: See \`docs/templates/example-project-brief.md\` for an example of a well-written brief.
 
@@ -19268,8 +19631,8 @@ function buildPapiMetaFramingDirective(caps, inner) {
 
 // src/services/build.ts
 import { randomUUID as randomUUID11 } from "crypto";
-import { readdirSync as readdirSync5, existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync3, unlinkSync as unlinkSync2, mkdirSync as mkdirSync2 } from "fs";
-import { join as join11 } from "path";
+import { readdirSync as readdirSync5, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, mkdirSync as mkdirSync3 } from "fs";
+import { join as join12 } from "path";
 
 // src/lib/db-only-notices.ts
 var DB_ONLY_START_NOTICE = "No git repo detected \u2014 running this cycle in your project database only. Your work stays in the working tree; run `git init` (and add a remote) to enable branches, commits and PR review.";
@@ -20187,6 +20550,38 @@ async function postReleaseToX(version, cycleClosed) {
     return false;
   }
 }
+function buildHostedReleaseOutput(params) {
+  const { version, branch, cyclePart, warningsBlock, skipVersion } = params;
+  const tagAnnotation = `Release ${version}`;
+  const titleSuffix = skipVersion ? " (skip version)" : "";
+  const gitHalf = skipVersion ? "the git half of the release (the CHANGELOG.md commit and the branch push) must run on your own machine" : "the git half of the release (tag, push, CHANGELOG.md) must run on your own machine";
+  const commands = skipVersion ? `git checkout ${branch}
+git pull
+git push origin ${branch}
+` : `git checkout ${branch}
+git pull
+git tag -a ${version} -m "${tagAnnotation}"
+git push origin ${branch}
+git push origin ${version}
+`;
+  const identityBlock = skipVersion ? "" : `If git reports "Author identity unknown" or "Committer identity unknown" (no global git identity configured), pass your identity inline instead of writing global config:
+\`\`\`
+git -c user.name="Your Name" -c user.email="you@example.com" tag -a ${version} -m "${tagAnnotation}"
+\`\`\`
+
+`;
+  return `## Release ${version}${titleSuffix} \u2014 cycle closed in the DB
+
+${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 ${gitHalf}.
+
+Finish the release locally:
+\`\`\`
+` + commands + `\`\`\`
+
+` + identityBlock + `Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`;
+}
 var releaseTool = {
   name: "release",
   description: "Cut a versioned release \u2014 creates a git tag, generates CHANGELOG.md, and pushes to remote. Pass skipVersion=true to update CHANGELOG and close the cycle without creating a tag or bumping version numbers.",
@@ -20364,33 +20759,12 @@ Next: run \`plan\` to start your next cycle.`
         branchMerges: [],
         changelogEmitted: false
       });
-      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
-
-${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.
-
-Finish the release locally:
-\`\`\`
-git checkout ${branch}
-git pull
-git tag -a ${version} -m "${tagAnnotation}"
-git push origin ${branch}
-git push origin ${version}
-\`\`\`
-
-If git reports "Author identity unknown" or "Committer identity unknown" (no global git identity configured), pass your identity inline instead of writing global config:
-\`\`\`
-git -c user.name="Your Name" -c user.email="you@example.com" tag -a ${version} -m "${tagAnnotation}"
-\`\`\`
-
-Next: cycle closed! Run \`plan\` to start your next cycle, or \`idea "<what's next>"\` first if your backlog is thin.`
+        buildHostedReleaseOutput({ version, branch, cyclePart, warningsBlock, skipVersion: skipVersion ?? false })
       );
     }
     tracker.mark("remote-project-guard");
@@ -20618,59 +20992,174 @@ async function ownsLocalWorkspace(adapter2, cwd) {
   return storedOwner === remoteOwner;
 }
 
+// src/lib/worktree-collision.ts
+var WORKTREE_DIR = ".claude/worktrees";
+function detectWorktreeCollision(input) {
+  const target = input.targetBranch.trim();
+  if (!target) return null;
+  const conflicts = input.inProgress.filter((b2) => {
+    const branch = b2.branch?.trim();
+    return !!branch && branch !== target && b2.taskId !== input.taskId;
+  });
+  if (conflicts.length === 0) return null;
+  const worktreePath = `${WORKTREE_DIR}/${input.taskId}`;
+  const worktreeCommand = `git worktree add ${worktreePath} ${target}`;
+  const others = conflicts.map((c) => `${c.taskId} (on '${c.branch.trim()}')`).join(", ");
+  const isAre = conflicts.length === 1 ? "is" : "are";
+  const warning = `\u26A0\uFE0F  Concurrent build detected: ${others} ${isAre} In Progress on a different branch, but this build targets '${target}'. Switching HEAD on the shared checkout would revert that session's working tree (the task-2346 data-loss incident). Isolate this build into its own worktree instead of switching branches here.`;
+  const setupHint = `Then run \`npm run worktree:setup\` inside ${worktreePath} \u2014 node_modules only exists in the main worktree, so the symlink step is required before tsup/builds work there (task-1419).`;
+  return {
+    warning,
+    worktreeCommand,
+    setupHint,
+    worktreePath,
+    auto: input.autoWorktree,
+    conflicts
+  };
+}
+
 // src/services/build.ts
 init_git();
 
-// src/lib/diff-inspector.ts
-import { execFileSync as execFileSync5 } from "child_process";
-var TRIGGER_SURFACE_GLOBS = [
-  "lib/install-snippets.ts",
-  "packages/server/src/transport-http.ts",
-  "packages/server/src/index.ts",
-  "app/well-known/**",
-  "app/api/auth/oauth/**",
-  "app/proxy.ts",
-  "app/middleware.ts",
-  "lib/auth*",
-  "next.config.ts",
-  "vercel.json",
-  "**/railway.toml",
-  "**/Dockerfile",
-  "**/Procfile",
-  "supabase/functions/**",
-  "lib/env*.ts"
-];
-function globToRegex(glob) {
-  let out = "";
-  let i = 0;
-  while (i < glob.length) {
-    const ch = glob[i];
-    if (ch === "*") {
-      if (glob[i + 1] === "*") {
-        if (glob[i + 2] === "/") {
-          out += "(?:.*/)?";
-          i += 3;
-        } else {
-          out += ".*";
-          i += 2;
-        }
-      } else {
-        out += "[^/]*";
-        i += 1;
-      }
-    } else if (ch === "." || ch === "+" || ch === "?" || ch === "(" || ch === ")" || ch === "|" || ch === "[" || ch === "]" || ch === "{" || ch === "}" || ch === "^" || ch === "$" || ch === "\\") {
-      out += "\\" + ch;
-      i += 1;
-    } else {
-      out += ch;
-      i += 1;
-    }
-  }
-  return new RegExp("^" + out + "$");
-}
-function isTriggerSurfacePath(path7, globs = TRIGGER_SURFACE_GLOBS) {
-  for (const g of globs) {
-    if (globToRegex(g).test(path7)) return true;
+// src/lib/build-checkpoint.ts
+import { createHash as createHash4 } from "crypto";
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join11 } from "path";
+var BUILD_CHECKPOINT_VERSION = 1;
+function cwdHash(cwd) {
+  return createHash4("sha256").update(realpathOrSelf(cwd)).digest("hex").slice(0, 12);
+}
+function safeTaskId(taskId) {
+  return taskId.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function checkpointDir(cwd) {
+  return join11(cwd, ".papi", "state");
+}
+function checkpointPath(cwd, taskId) {
+  return join11(checkpointDir(cwd), `build-${safeTaskId(taskId)}.${cwdHash(cwd)}.json`);
+}
+function writeBuildCheckpoint(input) {
+  try {
+    const dir = checkpointDir(input.cwd);
+    if (!existsSync7(dir)) {
+      mkdirSync2(dir, { recursive: true });
+    }
+    const checkpoint = {
+      version: BUILD_CHECKPOINT_VERSION,
+      taskId: input.taskId,
+      branch: input.branch,
+      step: input.step,
+      lastCommitSha: input.lastCommitSha,
+      modifiedFiles: input.modifiedFiles,
+      cwd: realpathOrSelf(input.cwd),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeFileSync3(checkpointPath(input.cwd, input.taskId), JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
+  } catch {
+  }
+}
+function readBuildCheckpoint(key) {
+  try {
+    const path7 = checkpointPath(key.cwd, key.taskId);
+    if (!existsSync7(path7)) return null;
+    const parsed = JSON.parse(readFileSync6(path7, "utf-8"));
+    if (!parsed || parsed.version !== BUILD_CHECKPOINT_VERSION || parsed.taskId !== key.taskId) {
+      return null;
+    }
+    return {
+      version: BUILD_CHECKPOINT_VERSION,
+      taskId: parsed.taskId,
+      branch: parsed.branch ?? null,
+      step: "branch_ready",
+      lastCommitSha: parsed.lastCommitSha ?? null,
+      modifiedFiles: Array.isArray(parsed.modifiedFiles) ? parsed.modifiedFiles : [],
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : realpathOrSelf(key.cwd),
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : ""
+    };
+  } catch {
+    return null;
+  }
+}
+function clearBuildCheckpoint(key) {
+  try {
+    const path7 = checkpointPath(key.cwd, key.taskId);
+    if (existsSync7(path7)) {
+      unlinkSync2(path7);
+    }
+  } catch {
+  }
+}
+function formatResumeNote(cp) {
+  const files = cp.modifiedFiles.filter((f) => f && f.trim());
+  const fileList = files.length > 0 ? files.slice(0, 12).map((f) => `  - ${f}`).join("\n") + (files.length > 12 ? `
+  - \u2026+${files.length - 12} more` : "") : "  _(none recorded)_";
+  const lines = [
+    "> **\u21BB Resuming from checkpoint** \u2014 this task is already In Progress; you are NOT starting clean.",
+    `> - Branch: \`${cp.branch ?? "unknown"}\``,
+    "> - Last step: branch ready",
+    `> - Last commit: ${cp.lastCommitSha ? cp.lastCommitSha.slice(0, 8) : "none"}`,
+    `> - Checkpoint saved: ${cp.updatedAt || "unknown"}`,
+    ">",
+    "> Modified files at last checkpoint:",
+    ...fileList.split("\n").map((l) => `> ${l}`),
+    ">",
+    "> Review the existing branch and changes above before writing new code \u2014 do not re-do work already committed.",
+    "",
+    ""
+  ];
+  return lines.join("\n");
+}
+
+// src/lib/diff-inspector.ts
+import { execFileSync as execFileSync5 } from "child_process";
+var TRIGGER_SURFACE_GLOBS = [
+  "lib/install-snippets.ts",
+  "packages/server/src/transport-http.ts",
+  "packages/server/src/index.ts",
+  "app/well-known/**",
+  "app/api/auth/oauth/**",
+  "app/proxy.ts",
+  "app/middleware.ts",
+  "lib/auth*",
+  "next.config.ts",
+  "vercel.json",
+  "**/railway.toml",
+  "**/Dockerfile",
+  "**/Procfile",
+  "supabase/functions/**",
+  "lib/env*.ts"
+];
+function globToRegex(glob) {
+  let out = "";
+  let i = 0;
+  while (i < glob.length) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") {
+          out += "(?:.*/)?";
+          i += 3;
+        } else {
+          out += ".*";
+          i += 2;
+        }
+      } else {
+        out += "[^/]*";
+        i += 1;
+      }
+    } else if (ch === "." || ch === "+" || ch === "?" || ch === "(" || ch === ")" || ch === "|" || ch === "[" || ch === "]" || ch === "{" || ch === "}" || ch === "^" || ch === "$" || ch === "\\") {
+      out += "\\" + ch;
+      i += 1;
+    } else {
+      out += ch;
+      i += 1;
+    }
+  }
+  return new RegExp("^" + out + "$");
+}
+function isTriggerSurfacePath(path7, globs = TRIGGER_SURFACE_GLOBS) {
+  for (const g of globs) {
+    if (globToRegex(g).test(path7)) return true;
   }
   return false;
 }
@@ -20856,51 +21345,22 @@ function autoCommit(config2, taskId, taskTitle, predictedFiles) {
   if (staged.length > 0) {
     return safeRun(() => commitStagedOnly(cwd, message)) + ` (selective staging respected: ${staged.length} file(s)).`;
   }
+  const modified = getModifiedFiles(cwd);
+  if (modified.length === 0) {
+    return "Auto-commit: skipped (no working-tree changes).";
+  }
+  const commitResult = safeRun(() => stageAllAndCommit(cwd, message));
   if (predictedFiles && predictedFiles.length > 0) {
-    const modified = getModifiedFiles(cwd);
-    if (modified.length === 0) {
-      return "Auto-commit: skipped (no working-tree changes).";
-    }
-    const dirname7 = (p) => {
-      const idx = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
-      return idx > 0 ? p.slice(0, idx) : "";
-    };
     const cleanedPredicted = sanitisePredictedFiles(predictedFiles);
-    const scoped = modified.filter((p) => isPathInPredictedScope(p, cleanedPredicted));
-    const untracked = getUntrackedFiles(cwd);
-    const scopedSet = new Set(scoped);
-    const untrackedInScope = untracked.filter(
-      (p) => !scopedSet.has(p) && isPathInPredictedScope(p, cleanedPredicted)
-    );
-    if (scoped.length === 0 && untrackedInScope.length === 0) {
-      const modSample = modified.slice(0, 5).join(", ");
-      const predSample = cleanedPredicted.slice(0, 5).join(", ");
-      return `Auto-commit: refused \u2014 none of the ${modified.length} modified file(s) intersect FILES LIKELY TOUCHED. Modified: ${modSample}. Expected: ${predSample}. Stage the intended files manually (\`git add <paths>\`) then re-run, or set PAPI_AUTO_COMMIT=false.`;
-    }
-    const scopedDirs = [...new Set(scoped.map(dirname7).filter((d) => d.length > 0))];
-    const isUnderScopedDir = (p) => scopedDirs.some((d) => p === d || p.startsWith(`${d}/`) || p.startsWith(`${d}\\`));
-    const inScopeSet = /* @__PURE__ */ new Set([...scoped, ...untrackedInScope]);
-    const adjacentUntracked = untracked.filter(
-      (p) => !inScopeSet.has(p) && isUnderScopedDir(p)
-    );
-    const toStage = [...scoped, ...untrackedInScope, ...adjacentUntracked];
-    const toStageSet = new Set(toStage);
-    const droppedUntracked = untracked.filter((p) => !toStageSet.has(p));
-    const droppedModified = modified.filter((p) => !scopedSet.has(p));
-    let line = safeRun(() => stagePathsAndCommit(cwd, toStage, message)) + ` (scoped to ${scoped.length}/${modified.length} files via FILES LIKELY TOUCHED` + (untrackedInScope.length > 0 ? ` + ${untrackedInScope.length} new file(s) named in the handoff` : "") + (adjacentUntracked.length > 0 ? ` + ${adjacentUntracked.length} untracked under scoped dir(s)` : "") + `).`;
-    if (droppedModified.length > 0) {
-      const sample = droppedModified.slice(0, 10).join(", ");
-      const more = droppedModified.length > 10 ? ` (+${droppedModified.length - 10} more)` : "";
-      line += ` \u26A0\uFE0F ${droppedModified.length} modified file(s) outside FILES LIKELY TOUCHED were NOT staged: ${sample}${more}. If they belong to this task, stage them manually (\`git add <paths>\`) and re-run, or set PAPI_AUTO_COMMIT=false.`;
-    }
-    if (droppedUntracked.length > 0) {
-      const sample = droppedUntracked.slice(0, 10).join(", ");
-      const more = droppedUntracked.length > 10 ? ` (+${droppedUntracked.length - 10} more)` : "";
-      line += ` \u26A0\uFE0F ${droppedUntracked.length} untracked file(s) were NOT committed: ${sample}${more}. If they belong to this task, run \`git add <paths> && git commit --amend --no-edit\` before pushing \u2014 otherwise the committed tree may not build on checkout/CI.`;
+    const outOfScope = modified.filter((p) => !isPathInPredictedScope(p, cleanedPredicted));
+    if (outOfScope.length > 0) {
+      const sample = outOfScope.slice(0, 10).join(", ");
+      const more = outOfScope.length > 10 ? ` (+${outOfScope.length - 10} more)` : "";
+      return `${commitResult} (staged all ${modified.length} changed file(s)). \u2139\uFE0F Scope drift: ${outOfScope.length} committed file(s) were outside the handoff's FILES LIKELY TOUCHED \u2014 handoff under-predicted: ${sample}${more}.`;
     }
-    return line;
+    return `${commitResult} (staged all ${modified.length} changed file(s), all within FILES LIKELY TOUCHED).`;
   }
-  return safeRun(() => stageAllAndCommit(cwd, message));
+  return `${commitResult} (staged all ${modified.length} changed file(s)).`;
 }
 function pushAndCreatePR(config2, taskId, taskTitle, clientName, module, cycleNumber) {
   const lines = [];
@@ -21221,7 +21681,46 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
     }
     taskBranchMap.set(taskId, featureBranch);
     const currentBranch = getCurrentBranch(config2.projectRoot);
-    if (currentBranch === featureBranch) {
+    let isolatedIntoWorktree = false;
+    if (currentBranch !== featureBranch) {
+      const otherInProgress = allTasks.filter((t) => t.status === "In Progress" && t.id !== taskId && t.displayId !== taskId).map((t) => ({
+        taskId: t.displayId || t.id,
+        branch: (t.branchName ?? taskBranchMap.get(t.id) ?? taskBranchMap.get(t.displayId) ?? "").trim()
+      })).filter((t) => t.branch.length > 0);
+      const collision = detectWorktreeCollision({
+        taskId,
+        targetBranch: featureBranch,
+        inProgress: otherInProgress,
+        autoWorktree: config2.autoWorktree
+      });
+      if (collision) {
+        branchLines.push(collision.warning);
+        if (collision.auto) {
+          try {
+            const { execFileSync: execFileSync7 } = await import("child_process");
+            const baseForWorktree = resolveBaseBranch(config2.projectRoot, config2.baseBranch);
+            const wtArgs = branchExists(config2.projectRoot, featureBranch) ? ["worktree", "add", collision.worktreePath, featureBranch] : ["worktree", "add", "-b", featureBranch, collision.worktreePath, baseForWorktree];
+            execFileSync7("git", wtArgs, { cwd: config2.projectRoot, encoding: "utf-8" });
+            isolatedIntoWorktree = true;
+            branchLines.push(
+              `Auto-isolated (PAPI_AUTO_WORKTREE): created worktree at ${collision.worktreePath} on '${featureBranch}'. The shared checkout stays on '${currentBranch}' \u2014 continue this build from inside the worktree.`
+            );
+            branchLines.push(collision.setupHint);
+          } catch (err) {
+            branchLines.push(
+              `Auto-worktree attempt failed (${err instanceof Error ? err.message : String(err)}) \u2014 isolate manually instead:`
+            );
+            branchLines.push(`  ${collision.worktreeCommand}`);
+            branchLines.push(collision.setupHint);
+          }
+        } else {
+          branchLines.push(`  ${collision.worktreeCommand}`);
+          branchLines.push(collision.setupHint);
+        }
+      }
+    }
+    if (isolatedIntoWorktree) {
+    } else if (currentBranch === featureBranch) {
       branchLines.push(`Already on branch '${featureBranch}'.`);
       if (useSharedBranch) {
         branchLines.push(`Reusing shared cycle branch for ${task.complexity} ${task.module} task.`);
@@ -21338,8 +21837,9 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
     await persistBranchName(adapter2, taskId, startedBranch);
   }
   buildStartTimes.set(taskId, (/* @__PURE__ */ new Date()).toISOString());
+  let startSha = null;
   if (isGitAvailable() && isGitRepo(config2.projectRoot)) {
-    const startSha = getHeadCommitSha(config2.projectRoot);
+    startSha = getHeadCommitSha(config2.projectRoot);
     if (startSha) taskStartShaMap.set(taskId, startSha);
   }
   let phaseChanges = [];
@@ -21358,6 +21858,14 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
     );
   } catch {
   }
+  writeBuildCheckpoint({
+    cwd: config2.projectRoot,
+    taskId,
+    branch: getCurrentBranch(config2.projectRoot),
+    step: "branch_ready",
+    lastCommitSha: startSha,
+    modifiedFiles: getModifiedFiles(config2.projectRoot)
+  });
   return {
     task,
     branchLines,
@@ -21372,17 +21880,17 @@ function writeActiveTaskScope(projectRoot, taskId, filesLikelyTouched, adapterTy
     collector.add({ path: ".papi/active-task-scope.txt", content, mode: "overwrite" });
     return;
   }
-  const papiDir = join11(projectRoot, ".papi");
-  if (!existsSync7(papiDir)) {
-    mkdirSync2(papiDir, { recursive: true });
+  const papiDir = join12(projectRoot, ".papi");
+  if (!existsSync8(papiDir)) {
+    mkdirSync3(papiDir, { recursive: true });
   }
-  const scopePath = join11(papiDir, "active-task-scope.txt");
-  writeFileSync3(scopePath, content, "utf-8");
+  const scopePath = join12(papiDir, "active-task-scope.txt");
+  writeFileSync4(scopePath, content, "utf-8");
 }
 function clearActiveTaskScope(projectRoot) {
-  const scopePath = join11(projectRoot, ".papi", "active-task-scope.txt");
-  if (existsSync7(scopePath)) {
-    unlinkSync2(scopePath);
+  const scopePath = join12(projectRoot, ".papi", "active-task-scope.txt");
+  if (existsSync8(scopePath)) {
+    unlinkSync3(scopePath);
   }
 }
 function sanitiseResponseExcerpt(raw) {
@@ -21401,7 +21909,7 @@ function extractDocMeta(absolutePath, relativePath, cycleNumber) {
   else if (relativePath.startsWith("docs/architecture/")) type = "architecture";
   else if (relativePath.startsWith("docs/audits/")) type = "audit";
   try {
-    const content = readFileSync6(absolutePath, "utf-8").slice(0, 2e3);
+    const content = readFileSync7(absolutePath, "utf-8").slice(0, 2e3);
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (fmMatch) {
       const fm = fmMatch[1];
@@ -21798,14 +22306,14 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
   let docWarning;
   try {
     if (adapter2.searchDocs && hasLocalWorkspace() && await ownsLocalWorkspace(adapter2, config2.projectRoot)) {
-      const docsDir = join11(config2.projectRoot, "docs");
-      if (existsSync7(docsDir)) {
+      const docsDir = join12(config2.projectRoot, "docs");
+      if (existsSync8(docsDir)) {
         const scanDir = (dir, depth = 0) => {
           if (depth > 8) return [];
           const entries = readdirSync5(dir, { withFileTypes: true });
           const files = [];
           for (const e of entries) {
-            const full = join11(dir, e.name);
+            const full = join12(dir, e.name);
             if (e.isDirectory() && !e.isSymbolicLink()) files.push(...scanDir(full, depth + 1));
             else if (e.name.endsWith(".md")) files.push(full.replace(config2.projectRoot + "/", ""));
           }
@@ -21820,7 +22328,7 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
           const failed = [];
           for (const docPath of unregistered) {
             try {
-              const meta = extractDocMeta(join11(config2.projectRoot, docPath), docPath, cycleNumber);
+              const meta = extractDocMeta(join12(config2.projectRoot, docPath), docPath, cycleNumber);
               await adapter2.registerDoc({
                 title: meta.title,
                 type: meta.type,
@@ -21858,6 +22366,10 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}, cli
     clearActiveTaskScope(config2.projectRoot);
   } catch {
   }
+  try {
+    clearBuildCheckpoint({ cwd: config2.projectRoot, taskId });
+  } catch {
+  }
   return {
     task,
     report,
@@ -21972,8 +22484,8 @@ ${instructions}`;
 }
 
 // src/tools/doc-registry.ts
-import { readdirSync as readdirSync6, existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
-import { join as join12, relative } from "path";
+import { readdirSync as readdirSync6, existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { join as join13, relative } from "path";
 import { homedir as homedir3 } from "os";
 import { randomUUID as randomUUID12 } from "crypto";
 import { docDeletionBlockMessage } from "@papi-ai/shared";
@@ -22171,7 +22683,7 @@ async function handleDocSearch(adapter2, args, config2) {
   const lines = docs.map((d) => {
     const actionCount = d.actions?.filter((a) => a.status === "pending").length ?? 0;
     const actionNote = actionCount > 0 ? ` | ${actionCount} pending action(s)` : "";
-    const missingNote = root && d.path && !existsSync8(join12(root, d.path)) ? `
+    const missingNote = root && d.path && !existsSync9(join13(root, d.path)) ? `
 > \u26A0\uFE0F **File missing on disk** \u2014 the registry points at \`${d.path}\` but nothing is there. Check \`git stash list\` for a papi-autostash entry, or re-create/deregister the doc.` : "";
     return `### ${d.title}
 **Type:** ${d.type} | **Status:** ${d.status} | **Cycle:** ${d.cycleCreated}${d.cycleUpdated ? `\u2192${d.cycleUpdated}` : ""}${actionNote}
@@ -22185,12 +22697,12 @@ ${d.summary}
 ${lines.join("\n---\n\n")}`);
 }
 function scanMdFiles(dir, rootDir) {
-  if (!existsSync8(dir)) return [];
+  if (!existsSync9(dir)) return [];
   const files = [];
   try {
     const entries = readdirSync6(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = join12(dir, entry.name);
+      const full = join13(dir, entry.name);
       if (entry.isDirectory()) {
         files.push(...scanMdFiles(full, rootDir));
       } else if (entry.name.endsWith(".md")) {
@@ -22203,7 +22715,7 @@ function scanMdFiles(dir, rootDir) {
 }
 function extractTitle(filePath) {
   try {
-    const content = readFileSync7(filePath, "utf-8").slice(0, 1e3);
+    const content = readFileSync8(filePath, "utf-8").slice(0, 1e3);
     const fmMatch = content.match(/^---[\s\S]*?title:\s*(.+?)$/m);
     if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, "");
     const headingMatch = content.match(/^#+\s+(.+)$/m);
@@ -22215,7 +22727,7 @@ function extractTitle(filePath) {
 async function detectUnregisteredDocsNote(adapter2, config2) {
   try {
     if (!adapter2.searchDocs || !hasLocalWorkspace()) return "";
-    const docsDir = join12(config2.projectRoot, "docs");
+    const docsDir = join13(config2.projectRoot, "docs");
     const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
     if (docsFiles.length === 0) return "";
     const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
@@ -22241,17 +22753,17 @@ async function handleDocScan(adapter2, config2, args) {
   const includePlans = args.include_plans ?? false;
   const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
   const registeredPaths = new Set(registered.map((d) => d.path));
-  const docsDir = join12(config2.projectRoot, "docs");
+  const docsDir = join13(config2.projectRoot, "docs");
   const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
   const unregisteredDocs = docsFiles.filter((f) => !registeredPaths.has(f));
   let unregisteredPlans = [];
   if (includePlans) {
-    const plansDir = join12(homedir3(), ".claude", "plans");
-    if (existsSync8(plansDir)) {
+    const plansDir = join13(homedir3(), ".claude", "plans");
+    if (existsSync9(plansDir)) {
       const planFiles = scanMdFiles(plansDir, plansDir);
       unregisteredPlans = planFiles.map((f) => `plans/${f}`).filter((f) => !registeredPaths.has(f)).map((f) => ({
         path: f,
-        title: extractTitle(join12(plansDir, f.replace("plans/", "")))
+        title: extractTitle(join13(plansDir, f.replace("plans/", "")))
       }));
     }
   }
@@ -22262,7 +22774,7 @@ async function handleDocScan(adapter2, config2, args) {
   if (unregisteredDocs.length > 0) {
     lines.push(`## Unregistered Docs (${unregisteredDocs.length})`);
     for (const f of unregisteredDocs) {
-      const title = extractTitle(join12(config2.projectRoot, f));
+      const title = extractTitle(join13(config2.projectRoot, f));
       lines.push(`- \`${f}\`${title ? ` \u2014 ${title}` : ""}`);
     }
   }
@@ -22435,97 +22947,6 @@ async function handleDocReorder(adapter2, args) {
 
 // src/tools/build.ts
 init_git();
-
-// src/lib/build-checkpoint.ts
-import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync9, mkdirSync as mkdirSync3, readFileSync as readFileSync8, unlinkSync as unlinkSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join13 } from "path";
-var BUILD_CHECKPOINT_VERSION = 1;
-function cwdHash(cwd) {
-  return createHash4("sha256").update(realpathOrSelf(cwd)).digest("hex").slice(0, 12);
-}
-function safeTaskId(taskId) {
-  return taskId.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-function checkpointDir(cwd) {
-  return join13(cwd, ".papi", "state");
-}
-function checkpointPath(cwd, taskId) {
-  return join13(checkpointDir(cwd), `build-${safeTaskId(taskId)}.${cwdHash(cwd)}.json`);
-}
-function writeBuildCheckpoint(input) {
-  try {
-    const dir = checkpointDir(input.cwd);
-    if (!existsSync9(dir)) {
-      mkdirSync3(dir, { recursive: true });
-    }
-    const checkpoint = {
-      version: BUILD_CHECKPOINT_VERSION,
-      taskId: input.taskId,
-      branch: input.branch,
-      step: input.step,
-      lastCommitSha: input.lastCommitSha,
-      modifiedFiles: input.modifiedFiles,
-      cwd: realpathOrSelf(input.cwd),
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    writeFileSync4(checkpointPath(input.cwd, input.taskId), JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
-  } catch {
-  }
-}
-function readBuildCheckpoint(key) {
-  try {
-    const path7 = checkpointPath(key.cwd, key.taskId);
-    if (!existsSync9(path7)) return null;
-    const parsed = JSON.parse(readFileSync8(path7, "utf-8"));
-    if (!parsed || parsed.version !== BUILD_CHECKPOINT_VERSION || parsed.taskId !== key.taskId) {
-      return null;
-    }
-    return {
-      version: BUILD_CHECKPOINT_VERSION,
-      taskId: parsed.taskId,
-      branch: parsed.branch ?? null,
-      step: "branch_ready",
-      lastCommitSha: parsed.lastCommitSha ?? null,
-      modifiedFiles: Array.isArray(parsed.modifiedFiles) ? parsed.modifiedFiles : [],
-      cwd: typeof parsed.cwd === "string" ? parsed.cwd : realpathOrSelf(key.cwd),
-      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : ""
-    };
-  } catch {
-    return null;
-  }
-}
-function clearBuildCheckpoint(key) {
-  try {
-    const path7 = checkpointPath(key.cwd, key.taskId);
-    if (existsSync9(path7)) {
-      unlinkSync3(path7);
-    }
-  } catch {
-  }
-}
-function formatResumeNote(cp) {
-  const files = cp.modifiedFiles.filter((f) => f && f.trim());
-  const fileList = files.length > 0 ? files.slice(0, 12).map((f) => `  - ${f}`).join("\n") + (files.length > 12 ? `
-  - \u2026+${files.length - 12} more` : "") : "  _(none recorded)_";
-  const lines = [
-    "> **\u21BB Resuming from checkpoint** \u2014 this task is already In Progress; you are NOT starting clean.",
-    `> - Branch: \`${cp.branch ?? "unknown"}\``,
-    "> - Last step: branch ready",
-    `> - Last commit: ${cp.lastCommitSha ? cp.lastCommitSha.slice(0, 8) : "none"}`,
-    `> - Checkpoint saved: ${cp.updatedAt || "unknown"}`,
-    ">",
-    "> Modified files at last checkpoint:",
-    ...fileList.split("\n").map((l) => `> ${l}`),
-    ">",
-    "> Review the existing branch and changes above before writing new code \u2014 do not re-do work already committed.",
-    "",
-    ""
-  ];
-  return lines.join("\n");
-}
-
-// src/tools/build.ts
 var buildListTool = {
   name: "build_list",
   description: "List cycle tasks that have BUILD HANDOFFs ready for execution. Shows task ID, title, status, priority, and complexity. In Progress tasks appear first, then Backlog. Does not call the Anthropic API.",
@@ -22561,7 +22982,17 @@ var buildExecuteTool = {
   description: "Start or complete a build task. Call with just task_id to start (returns BUILD HANDOFF, creates feature branch, marks In Progress). After implementing the task, you MUST call build_execute again with all report fields (completed, effort, estimated_effort, surprises, discovered_issues, architecture_notes) to finish \u2014 do not wait for user confirmation between start and complete. Never call on tasks that are already In Review or Done. Does not call the Anthropic API. Set light=true to skip branch/PR creation (commits to current branch). Set PAPI_LIGHT_MODE=true in env to default all builds to light mode.",
   annotations: { title: "Run Build", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
+    // task-2802: JSON Schema 2020-12. Shared effort-size enum lives in $defs and is
+    // referenced from effort/estimated_effort so the two stay in lockstep; the
+    // start-vs-complete contract is expressed as a conditional (see allOf below).
+    $defs: {
+      effortSize: {
+        type: "string",
+        enum: ["XS", "S", "M", "L", "XL"]
+      }
+    },
     properties: {
       task_id: {
         type: "string",
@@ -22581,13 +23012,11 @@ var buildExecuteTool = {
         description: `task-2833: set true to assert every acceptance criterion in the task's BUILD HANDOFF was met. Required to record a completed:"yes" build when the handoff lists acceptance criteria \u2014 without it, build_execute returns the criteria checklist and does NOT mark the task Done (the report is not discarded; re-send with acceptance_confirmed:true). Tasks with no acceptance criteria, and completed:"partial"/"no", are unaffected.`
       },
       effort: {
-        type: "string",
-        enum: ["XS", "S", "M", "L", "XL"],
+        $ref: "#/$defs/effortSize",
         description: "Actual effort: XS, S, M, L, or XL. Required for complete."
       },
       estimated_effort: {
-        type: "string",
-        enum: ["XS", "S", "M", "L", "XL"],
+        $ref: "#/$defs/effortSize",
         description: "Estimated effort from the BUILD HANDOFF. Required for complete."
       },
       model: {
@@ -22631,6 +23060,8 @@ var buildExecuteTool = {
       },
       corrections_count: {
         type: "integer",
+        minimum: 0,
+        default: 0,
         description: "Number of times the user corrected or redirected the build during implementation. Captures informal pushback that bypasses review_submit. Default 0."
       },
       dead_ends: {
@@ -22681,7 +23112,29 @@ var buildExecuteTool = {
         }
       }
     },
-    required: ["task_id"]
+    required: ["task_id"],
+    // task-2802: a COMPLETE call is any call carrying report data (mirrors the
+    // handler's isCompleteCall at build.ts). When any of the six report fields is
+    // present, all six are required — exactly what completeBuild enforces, so this
+    // never rejects a call the handler would accept; it just steers the agent to
+    // send the full report in one shot instead of round-tripping on a missing field.
+    allOf: [
+      {
+        if: {
+          anyOf: [
+            { required: ["completed"] },
+            { required: ["effort"] },
+            { required: ["estimated_effort"] },
+            { required: ["surprises"] },
+            { required: ["discovered_issues"] },
+            { required: ["architecture_notes"] }
+          ]
+        },
+        then: {
+          required: ["completed", "effort", "estimated_effort", "surprises", "discovered_issues", "architecture_notes"]
+        }
+      }
+    ]
   }
 };
 var buildCancelTool = {
@@ -22872,14 +23325,6 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
     const result = await startBuild(adapter2, config2, taskId, { light }, clientName);
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.task.cycle ?? null });
     await tracker.recordStep("branch_ready");
-    writeBuildCheckpoint({
-      cwd: config2.projectRoot,
-      taskId,
-      branch: getCurrentBranch(config2.projectRoot),
-      step: "branch_ready",
-      lastCommitSha: getHeadCommitSha(config2.projectRoot),
-      modifiedFiles: getModifiedFiles(config2.projectRoot)
-    });
     tracker.mark("start_decorate_handoff");
     const branchInfo = result.branchLines.length > 0 ? result.branchLines.map((l) => `> ${l}`).join("\n") + "\n\n" : "";
     const phaseNote = result.phaseChanges.length > 0 ? "\n\n" + result.phaseChanges.map((c) => `Phase auto-updated: ${c.phaseId} ${c.oldStatus} \u2192 ${c.newStatus}`).join("\n") : "";
@@ -23098,7 +23543,6 @@ Your report was NOT discarded and the task is NOT yet Done \u2014 re-send with \
       preview
     }, { light }, clientName);
     tracker.mark("complete_format");
-    clearBuildCheckpoint({ cwd: config2.projectRoot, taskId });
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.cycleNumber });
     await tracker.recordStep("report_written");
     if ((result.autoTriagedCount ?? 0) > 0) {
@@ -23456,12 +23900,460 @@ Re-submit with \`notes: "... Reference: <path>"\` to link one, or ignore if none
   return textResponse(`${result.message}${overrideNote}`);
 }
 
+// src/services/import.ts
+import { randomUUID as randomUUID13 } from "crypto";
+var IMPLEMENTED_SOURCES = ["csv", "markdown", "linear"];
+var MAX_TITLE_LEN = 200;
+var MAX_NOTES_LEN = 2e3;
+function sanitiseText(value, maxLen, keepNewlines = false) {
+  let str;
+  if (typeof value === "string") str = value;
+  else if (typeof value === "number" || typeof value === "boolean") str = String(value);
+  else if (value == null) str = "";
+  else {
+    try {
+      str = String(value);
+    } catch {
+      str = "";
+    }
+  }
+  if (keepNewlines) {
+    str = str.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, " ");
+    str = str.replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n");
+  } else {
+    str = str.replace(/[\x00-\x1F\x7F-\x9F]/g, " ");
+    str = str.replace(/\s+/g, " ");
+  }
+  str = str.trim();
+  if (str.length > maxLen) str = str.slice(0, maxLen).trim();
+  return str;
+}
+function mapPriorityString(value) {
+  const v = String(value ?? "").trim().toLowerCase();
+  if (/\b(p0|urgent|critical|highest|blocker)\b/.test(v)) return "P0 Critical";
+  if (/\b(p1|high)\b/.test(v)) return "P1 High";
+  if (/\b(p3|low|lowest|minor)\b/.test(v)) return "P3 Low";
+  return "P2 Medium";
+}
+function mapPriorityNumber(value) {
+  const n = typeof value === "number" ? value : Number(value);
+  switch (n) {
+    case 1:
+      return "P0 Critical";
+    case 2:
+      return "P1 High";
+    case 4:
+      return "P3 Low";
+    case 3:
+    case 0:
+    default:
+      return "P2 Medium";
+  }
+}
+function mapStatusString(value) {
+  const v = String(value ?? "").trim().toLowerCase();
+  if (/\b(done|complete|completed|closed|merged|shipped|resolved)\b/.test(v)) return "Done";
+  if (/\b(cancel|cancelled|canceled|wont.?fix|duplicate|abandoned)\b/.test(v)) return "Cancelled";
+  if (/\b(in.?review|review|qa|verifying)\b/.test(v)) return "In Review";
+  if (/\b(in.?progress|started|doing|active|wip)\b/.test(v)) return "In Progress";
+  if (/\b(blocked|waiting|on.?hold)\b/.test(v)) return "Blocked";
+  return "Backlog";
+}
+function estimateToComplexity(value) {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n) || n <= 0) return "Small";
+  if (n <= 1) return "XS";
+  if (n <= 2) return "Small";
+  if (n <= 3) return "Medium";
+  if (n <= 5) return "Large";
+  return "XL";
+}
+function mapComplexityField(value) {
+  const v = String(value ?? "").trim();
+  if (v !== "" && /^\d+(\.\d+)?$/.test(v)) return estimateToComplexity(v);
+  return normalizeComplexity(v);
+}
+function parseCsv(text) {
+  const rows = [];
+  let field = "";
+  let row = [];
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += c;
+      }
+      continue;
+    }
+    if (c === '"') {
+      inQuotes = true;
+    } else if (c === ",") {
+      row.push(field);
+      field = "";
+    } else if (c === "\n" || c === "\r") {
+      if (c === "\r" && text[i + 1] === "\n") i++;
+      row.push(field);
+      field = "";
+      if (row.some((f) => f.trim() !== "")) rows.push(row);
+      row = [];
+    } else {
+      field += c;
+    }
+  }
+  if (field !== "" || row.length > 0) {
+    row.push(field);
+    if (row.some((f) => f.trim() !== "")) rows.push(row);
+  }
+  return rows;
+}
+function findColumn(header, candidates) {
+  const lower = header.map((h) => h.trim().toLowerCase());
+  for (const cand of candidates) {
+    const idx = lower.indexOf(cand);
+    if (idx !== -1) return idx;
+  }
+  return -1;
+}
+var csvNormaliser = ({ raw }) => {
+  if (!raw || !raw.trim()) return [];
+  const rows = parseCsv(raw);
+  if (rows.length < 2) return [];
+  const header = rows[0];
+  const titleCol = findColumn(header, ["title", "name", "task", "summary", "subject"]);
+  if (titleCol === -1) {
+    throw new Error(
+      "CSV import: no recognisable title column. Expected a header row with one of: title, name, task, summary, subject."
+    );
+  }
+  const notesCol = findColumn(header, ["notes", "description", "details", "body"]);
+  const statusCol = findColumn(header, ["status", "state"]);
+  const priorityCol = findColumn(header, ["priority", "importance"]);
+  const complexityCol = findColumn(header, ["complexity", "estimate", "size", "points", "effort"]);
+  const idCol = findColumn(header, ["id", "key", "identifier", "ref"]);
+  const out = [];
+  for (let r = 1; r < rows.length; r++) {
+    const cells = rows[r];
+    const title = sanitiseText(cells[titleCol], MAX_TITLE_LEN);
+    if (!title) continue;
+    out.push({
+      title,
+      notes: notesCol === -1 ? "" : sanitiseText(cells[notesCol], MAX_NOTES_LEN, true),
+      status: statusCol === -1 ? "Backlog" : mapStatusString(cells[statusCol]),
+      priority: priorityCol === -1 ? "P2 Medium" : mapPriorityString(cells[priorityCol]),
+      complexity: complexityCol === -1 ? "Small" : mapComplexityField(cells[complexityCol]),
+      sourceId: idCol === -1 ? void 0 : sanitiseText(cells[idCol], 80) || void 0
+    });
+  }
+  return out;
+};
+var markdownNormaliser = ({ raw }) => {
+  if (!raw || !raw.trim()) return [];
+  const lines = raw.split(/\r?\n/);
+  const tableHeaderIdx = lines.findIndex(
+    (l, i) => /\|/.test(l) && lines[i + 1] !== void 0 && /^\s*\|?[\s:|-]+\|?\s*$/.test(lines[i + 1]) && /-/.test(lines[i + 1])
+  );
+  if (tableHeaderIdx !== -1) {
+    const splitRow = (l) => l.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim());
+    const header = splitRow(lines[tableHeaderIdx]);
+    const titleCol = findColumn(header, ["title", "name", "task", "summary", "subject"]);
+    if (titleCol === -1) {
+      throw new Error(
+        "Markdown table import: no recognisable title column. Expected a header cell of: title, name, task, summary, subject."
+      );
+    }
+    const notesCol = findColumn(header, ["notes", "description", "details", "body"]);
+    const statusCol = findColumn(header, ["status", "state"]);
+    const priorityCol = findColumn(header, ["priority", "importance"]);
+    const complexityCol = findColumn(header, ["complexity", "estimate", "size", "points", "effort"]);
+    const idCol = findColumn(header, ["id", "key", "identifier", "ref"]);
+    const out2 = [];
+    for (let i = tableHeaderIdx + 2; i < lines.length; i++) {
+      const l = lines[i];
+      if (!/\|/.test(l) || l.trim() === "") break;
+      const cells = splitRow(l);
+      const title = sanitiseText(cells[titleCol], MAX_TITLE_LEN);
+      if (!title) continue;
+      out2.push({
+        title,
+        notes: notesCol === -1 ? "" : sanitiseText(cells[notesCol], MAX_NOTES_LEN, true),
+        status: statusCol === -1 ? "Backlog" : mapStatusString(cells[statusCol]),
+        priority: priorityCol === -1 ? "P2 Medium" : mapPriorityString(cells[priorityCol]),
+        complexity: complexityCol === -1 ? "Small" : mapComplexityField(cells[complexityCol]),
+        sourceId: idCol === -1 ? void 0 : sanitiseText(cells[idCol], 80) || void 0
+      });
+    }
+    return out2;
+  }
+  const out = [];
+  const checklistRe = /^\s*(?:[-*+]|\d+\.)\s+(?:\[( |x|X)\]\s+)?(.*\S)\s*$/;
+  for (const line of lines) {
+    const m = line.match(checklistRe);
+    if (!m) continue;
+    const checked = m[1];
+    const title = sanitiseText(m[2], MAX_TITLE_LEN);
+    if (!title) continue;
+    out.push({
+      title,
+      notes: "",
+      status: checked && checked.toLowerCase() === "x" ? "Done" : "Backlog",
+      priority: "P2 Medium",
+      complexity: "Small"
+    });
+  }
+  return out;
+};
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+var linearNormaliser = ({ rows }) => {
+  if (!rows || rows.length === 0) return [];
+  const out = [];
+  for (const row of rows) {
+    if (!isRecord(row)) continue;
+    const issue = row;
+    const title = sanitiseText(issue.title, MAX_TITLE_LEN);
+    if (!title) continue;
+    const stateName = isRecord(issue.state) ? issue.state.name ?? issue.state.type : issue.state;
+    const identifier = sanitiseText(issue.identifier, 80) || sanitiseText(issue.id, 80) || void 0;
+    const url = sanitiseText(issue.url, 300);
+    const description = sanitiseText(issue.description, MAX_NOTES_LEN, true);
+    const notesParts = [];
+    if (description) notesParts.push(description);
+    if (url) notesParts.push(`Reference: ${url}`);
+    out.push({
+      title,
+      notes: sanitiseText(notesParts.join("\n"), MAX_NOTES_LEN, true),
+      status: mapStatusString(stateName),
+      priority: mapPriorityNumber(issue.priority),
+      complexity: issue.estimate == null ? "Small" : estimateToComplexity(issue.estimate),
+      sourceId: identifier
+    });
+  }
+  return out;
+};
+function notImplemented(source) {
+  return () => {
+    throw new Error(
+      `Import source "${source}" is not implemented yet. Shipped sources: ${IMPLEMENTED_SOURCES.join(", ")}. To add "${source}", implement a normaliser in packages/server/src/services/import.ts (see the "EXTENDING THE IMPORTER" header comment) \u2014 the host reads "${source}" via its own MCP tool and passes rows here; PAPI never connects to it directly.`
+    );
+  };
+}
+var SOURCE_NORMALISERS = {
+  csv: csvNormaliser,
+  markdown: markdownNormaliser,
+  linear: linearNormaliser,
+  // Extension points — build these by replacing notImplemented() with a real normaliser.
+  trello: notImplemented("trello"),
+  todoist: notImplemented("todoist"),
+  notion: notImplemented("notion")
+};
+function importMarker(source, sourceId) {
+  return `[papi-import:${source}:${sourceId}]`;
+}
+function dedupTitleKey(title) {
+  return title.toLowerCase().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, " ").trim();
+}
+async function importBacklog(adapter2, input) {
+  const normaliser = SOURCE_NORMALISERS[input.source];
+  if (!normaliser) {
+    throw new Error(
+      `Unknown import source "${input.source}". Valid sources: ${Object.keys(SOURCE_NORMALISERS).join(", ")}.`
+    );
+  }
+  const normalised = normaliser({ raw: input.raw, rows: input.rows });
+  const existing = await adapter2.queryBoard({});
+  const existingTitleKeys = /* @__PURE__ */ new Set();
+  const existingMarkers = /* @__PURE__ */ new Set();
+  for (const t of existing) {
+    existingTitleKeys.add(dedupTitleKey(t.title));
+    const notes = t.notes ?? "";
+    const markerMatches = notes.match(/\[papi-import:[^\]]+\]/g);
+    if (markerMatches) for (const mk of markerMatches) existingMarkers.add(mk);
+  }
+  const health = await adapter2.getCycleHealth();
+  warnIfEmpty("getCycleHealth (import)", health);
+  const createdCycle = health.totalCycles;
+  const targetModule = input.module && input.module.trim() || "Core";
+  const createdTasks = [];
+  const skippedTitles = [];
+  const seenThisBatch = /* @__PURE__ */ new Set();
+  for (const task of normalised) {
+    const titleKey = dedupTitleKey(task.title);
+    const marker = task.sourceId ? importMarker(input.source, task.sourceId) : null;
+    const isDup = marker !== null && existingMarkers.has(marker) || existingTitleKeys.has(titleKey) || seenThisBatch.has(marker ?? titleKey);
+    if (isDup) {
+      skippedTitles.push(task.title);
+      continue;
+    }
+    seenThisBatch.add(marker ?? titleKey);
+    if (input.dryRun) {
+      createdTasks.push({ id: "(dry-run)", title: task.title });
+      continue;
+    }
+    const notes = marker ? `${task.notes ? `${task.notes}
+
+` : ""}${marker}`.trim() : task.notes;
+    const created = await adapter2.createTask({
+      uuid: randomUUID13(),
+      displayId: "",
+      title: task.title,
+      status: task.status,
+      priority: task.priority,
+      complexity: task.complexity,
+      module: targetModule,
+      epic: "Platform",
+      phase: "Unscoped",
+      owner: "TBD",
+      reviewed: false,
+      createdCycle,
+      notes,
+      taskType: "task",
+      maturity: "raw",
+      source: `import:${input.source}`
+    });
+    createdTasks.push({ id: created.id, title: created.title });
+    existingTitleKeys.add(titleKey);
+    if (marker) existingMarkers.add(marker);
+  }
+  return {
+    source: input.source,
+    normalised: normalised.length,
+    imported: input.dryRun ? 0 : createdTasks.length,
+    skipped: skippedTitles.length,
+    skippedTitles,
+    createdTasks,
+    dryRun: input.dryRun === true
+  };
+}
+
+// src/tools/import.ts
+var ALL_SOURCES = ["csv", "markdown", "linear", "trello", "todoist", "notion"];
+var backlogImportTool = {
+  name: "backlog_import",
+  annotations: { title: "Import Backlog", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  description: `Import an existing backlog from another tool into PAPI as Backlog tasks, removing the "start from an empty board" wall. PAPI never connects to the source tool \u2014 YOU (the host) read the export and pass it here. Flat-file sources (csv, markdown) take a \`raw\` string; structured sources (linear) take a \`rows\` array you read via that tool's MCP. Import is one-way and idempotent: re-running the same import does NOT create duplicates. Shipped sources: ${IMPLEMENTED_SOURCES.join(", ")}. trello/todoist/notion are reserved but not implemented yet. Does not call the Anthropic API.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      source: {
+        type: "string",
+        enum: ALL_SOURCES,
+        description: "The tool the backlog came from. csv/markdown read a `raw` string; linear reads a `rows` array of issues. trello/todoist/notion are reserved extension points (not implemented yet)."
+      },
+      raw: {
+        type: "string",
+        description: "Raw export text for flat-file sources. CSV: a header row + data rows (title/name column required; optional notes/description, status/state, priority, complexity/estimate, id). Markdown: a checklist (`- [ ] Task`) or a GitHub-style table."
+      },
+      rows: {
+        type: "array",
+        description: "Pre-read rows for structured sources. For linear: an array of issues you read via the Linear MCP, each like { identifier, title, description, state: { name }, priority (0-4), estimate, url }.",
+        items: { type: "object" }
+      },
+      module: {
+        type: "string",
+        description: 'Module to file imported tasks under (default "Core").'
+      },
+      dry_run: {
+        type: "boolean",
+        description: "When true, normalise and dedup-check without writing anything. Use this to preview what would be imported. Default: false."
+      },
+      project: {
+        type: "string",
+        description: "Project id (UUID) or slug to import into, overriding the session project for THIS call only. Must be a project on your account \u2014 fails closed otherwise."
+      }
+    },
+    required: ["source"]
+  }
+};
+function diagnostic(lastStep, error, hint) {
+  return errorResponse(JSON.stringify({ tool: "backlog_import", lastStep, error, hint }, null, 2));
+}
+function formatResult(result, overrideNote) {
+  const lines = [];
+  const verb = result.dryRun ? "Would import" : "Imported";
+  lines.push(
+    `${verb} ${result.dryRun ? result.normalised - result.skipped : result.imported} task(s) from ${result.source}${overrideNote}.`
+  );
+  lines.push(`  normalised: ${result.normalised} \xB7 ${result.dryRun ? "would-write" : "written"}: ${result.dryRun ? result.normalised - result.skipped : result.imported} \xB7 skipped (duplicates): ${result.skipped}`);
+  if (result.createdTasks.length > 0 && !result.dryRun) {
+    const preview = result.createdTasks.slice(0, 10).map((t) => `  - ${t.id}: ${t.title}`);
+    lines.push("Created:");
+    lines.push(...preview);
+    if (result.createdTasks.length > 10) lines.push(`  \u2026and ${result.createdTasks.length - 10} more`);
+  }
+  if (result.skipped > 0) {
+    const dupPreview = result.skippedTitles.slice(0, 5).map((t) => `  - ${t}`);
+    lines.push(`Skipped ${result.skipped} duplicate(s) (already on the board or repeated in this import):`);
+    lines.push(...dupPreview);
+    if (result.skippedTitles.length > 5) lines.push(`  \u2026and ${result.skippedTitles.length - 5} more`);
+  }
+  if (!result.dryRun && result.imported > 0) {
+    lines.push("\nRun `plan` to triage and scope the imported backlog into a cycle.");
+  }
+  return lines.join("\n");
+}
+async function handleBacklogImport(adapter2, args) {
+  const source = args.source?.trim();
+  if (!source) {
+    return errorResponse(`source is required \u2014 one of: ${ALL_SOURCES.join(", ")}.`);
+  }
+  if (!ALL_SOURCES.includes(source)) {
+    return errorResponse(`Unknown source "${source}". Valid: ${ALL_SOURCES.join(", ")}.`);
+  }
+  const raw = args.raw;
+  const rawRows = args.rows;
+  const rows = Array.isArray(rawRows) ? rawRows : void 0;
+  const isFlatFile = source === "csv" || source === "markdown";
+  if (isFlatFile && (!raw || !raw.trim())) {
+    return errorResponse(`Source "${source}" needs a \`raw\` string (the exported ${source} text).`);
+  }
+  if (!isFlatFile && IMPLEMENTED_SOURCES.includes(source) && (!rows || rows.length === 0)) {
+    return errorResponse(`Source "${source}" needs a \`rows\` array of issues you read via that tool's MCP.`);
+  }
+  let target = adapter2;
+  let overrideNote = "";
+  try {
+    ({ adapter: target, overrideNote } = await resolvePerCallProjectAdapter(adapter2, args));
+  } catch (err) {
+    if (err instanceof ProjectResolutionError) return errorResponse(err.message);
+    throw err;
+  }
+  try {
+    const result = await importBacklog(target, {
+      source,
+      raw,
+      rows,
+      module: args.module,
+      dryRun: args.dry_run === true
+    });
+    return textResponse(formatResult(result, overrideNote));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/not implemented yet|no recognisable title column/i.test(message)) {
+      return errorResponse(message);
+    }
+    return diagnostic(
+      "importBacklog",
+      message,
+      "Check the export shape matches the source (csv/markdown need `raw`; linear needs `rows`). Re-run with dry_run:true to preview."
+    );
+  }
+}
+
 // src/tools/bug.ts
 import os from "os";
 init_git();
 
 // src/services/bug.ts
-import { randomUUID as randomUUID13 } from "crypto";
+import { randomUUID as randomUUID14 } from "crypto";
 function resolveCurrentPhase2(phases) {
   if (phases.length === 0) return "Unscoped";
   const inProgress = phases.find((p) => p.status === "In Progress");
@@ -23487,7 +24379,7 @@ async function captureBug(adapter2, input) {
   warnIfEmpty("getCycleHealth (bug)", health);
   const phase = input.phase || resolveCurrentPhase2(phases);
   return adapter2.createTask({
-    uuid: randomUUID13(),
+    uuid: randomUUID14(),
     displayId: "",
     title: input.text,
     status: "Backlog",
@@ -23741,7 +24633,7 @@ ${lines.join("\n")}`
 init_git();
 
 // src/services/ad-hoc.ts
-import { randomUUID as randomUUID14 } from "crypto";
+import { randomUUID as randomUUID15 } from "crypto";
 function resolveAdHocCycle(cycle, latest, latestComplete) {
   if (cycle === void 0) return null;
   if (typeof cycle === "number") return cycle;
@@ -23781,7 +24673,7 @@ async function recordAdHoc(adapter2, input) {
   } else {
     const phase = resolveCurrentPhase(phases);
     task = await adapter2.createTask({
-      uuid: randomUUID14(),
+      uuid: randomUUID15(),
       displayId: "",
       title: input.title,
       status: landInReview ? "In Review" : "Done",
@@ -23800,7 +24692,7 @@ async function recordAdHoc(adapter2, input) {
     });
   }
   const report = {
-    uuid: randomUUID14(),
+    uuid: randomUUID15(),
     createdAt: now.toISOString(),
     taskId: task.id,
     taskName: task.title ?? task.displayId ?? "untitled",
@@ -23954,13 +24846,38 @@ async function handleAdHoc(adapter2, config2, args) {
   const promoNote = result.task.cycle != null ? ` Promoted into Cycle ${result.task.cycle} as injected work${result.task.status === "In Review" ? " (In Review \u2014 will release with the cycle)" : ""}.` : "";
   if (holdArg) {
     const branch = `feat/${result.task.id}`;
+    let collisionBlock = "";
+    try {
+      const board = await adapter2.queryBoard({ status: ["In Progress"] });
+      const otherInProgress = board.filter((t) => t.id !== result.task.id && t.displayId !== result.task.id).map((t) => ({ taskId: t.displayId || t.id, branch: (t.branchName ?? "").trim() })).filter((t) => t.branch.length > 0);
+      const collision = detectWorktreeCollision({
+        taskId: result.task.id,
+        targetBranch: branch,
+        inProgress: otherInProgress,
+        // Held work never runs git server-side — treat as suggest-only.
+        autoWorktree: false
+      });
+      if (collision) {
+        collisionBlock = `
+> ${collision.warning}
+> Instead of \`git switch -c\`, isolate into a worktree:
+> \`\`\`
+> git worktree add -b ${branch} ${collision.worktreePath}
+> cd ${collision.worktreePath} && npm run worktree:setup
+> \`\`\`
+> ${collision.setupHint}
+
+`;
+      }
+    } catch {
+    }
     return textResponse(
       `**${result.task.id}:** "${result.task.title}" held for review (${effortRaw}, ${priorityRaw}, ${typeLabel}, ${taskModule}).${truncateWarning}${promoNote} Build report attached.
 
 ## Held for the next cycle \u2014 branch + commit, do NOT merge
 The task is recorded **In Review** and pinned to **Cycle ${result.task.cycle}**, so the planner won't re-plan it and it rides that cycle's review \u2192 release bundled with planned work.
 
-1. Create a branch and commit your code there (never \`main\`):
+` + collisionBlock + `1. Create a branch and commit your code there (never \`main\`):
    \`\`\`
    git switch -c ${branch}
    git add -- <your changed files>
@@ -24568,7 +25485,7 @@ import { join as join15 } from "path";
 init_git();
 
 // src/services/review.ts
-import { randomUUID as randomUUID15 } from "crypto";
+import { randomUUID as randomUUID16 } from "crypto";
 function isValidVerdict(stage, verdict) {
   if (stage === "handoff-review") {
     return verdict === "approve" || verdict === "request-changes" || verdict === "reject";
@@ -24625,7 +25542,7 @@ async function submitReview(adapter2, input) {
   }
   const date = (/* @__PURE__ */ new Date()).toISOString();
   const review = {
-    uuid: randomUUID15(),
+    uuid: randomUUID16(),
     taskId: input.taskId,
     stage: input.stage,
     reviewer: input.reviewer,
@@ -24840,6 +25757,7 @@ var reviewSubmitTool = {
   description: "Record a review verdict on a completed build (build-acceptance) or task plan (handoff-review). ALWAYS ask the human for their verdict before calling \u2014 never auto-submit without human input. Accept moves the task to Done, request-changes sends it back for rework, reject discards the build. Updates task status based on the verdict. On handoff-review with suggested changes, returns a prompt to revise the BUILD HANDOFF.\n\nDO NOT use this tool as a substitute for review_list. If you need to see what is pending review, call review_list first. If review_list is unavailable in your tool set, STOP and tell the human their MCP integration is incomplete rather than guessing at the next pending task. (SUP-2026-010.)",
   annotations: { title: "Submit Review", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
     properties: {
       task_id: {
@@ -24906,7 +25824,21 @@ var reviewSubmitTool = {
         required: ["verdict", "summary", "findings"]
       }
     },
-    required: ["task_id", "stage", "verdict", "comments"]
+    required: ["task_id", "stage", "verdict", "comments"],
+    // task-2802: mirror isValidVerdict — the legal verdict set is stage-dependent.
+    // handoff-review takes approve/request-changes/reject; build-acceptance takes
+    // accept/request-changes/reject. The flat enum above lists the union; these
+    // conditionals narrow it per stage so the agent can't pair an impossible verdict.
+    allOf: [
+      {
+        if: { properties: { stage: { const: "handoff-review" } }, required: ["stage"] },
+        then: { properties: { verdict: { enum: ["approve", "request-changes", "reject"] } } }
+      },
+      {
+        if: { properties: { stage: { const: "build-acceptance" } }, required: ["stage"] },
+        then: { properties: { verdict: { enum: ["accept", "request-changes", "reject"] } } }
+      }
+    ]
   }
 };
 function formatReviewList(pendingBuilds) {
@@ -25525,7 +26457,7 @@ async function handleReviewClaim(adapter2, config2, args) {
 }
 
 // src/tools/init.ts
-import { randomUUID as randomUUID16 } from "crypto";
+import { randomUUID as randomUUID17 } from "crypto";
 import { access as access3, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
 import path5 from "path";
 var initTool = {
@@ -25958,7 +26890,7 @@ ${writeNote}
     );
   }
   if (isDatabaseUser) {
-    const projectId = randomUUID16();
+    const projectId = randomUUID17();
     const envVars = {
       PAPI_PROJECT_DIR: projectRoot,
       PAPI_ADAPTER: "pg",
@@ -26333,9 +27265,15 @@ var TASK_REF = /\btask-\d+\b/gi;
 var RECENT_CYCLE_WINDOW = 5;
 var MAX_CANDIDATES = 5;
 async function findUnblockCandidates(adapter2, currentCycle) {
+  try {
+    const blockedProbe = await adapter2.queryBoard({ status: ["Blocked"], compact: true });
+    if (blockedProbe.length === 0) return [];
+  } catch {
+    return [];
+  }
   let allTasks = [];
   try {
-    allTasks = await adapter2.queryBoard();
+    allTasks = await adapter2.queryBoard({ compact: true });
   } catch {
     return [];
   }
@@ -26761,6 +27699,7 @@ var orientTool = {
   description: "Session orientation \u2014 run this FIRST at session start before any other tool. Single call that replaces build_list + health. Returns: cycle number, task counts by status, in-progress/in-review tasks, strategy review cadence, velocity snapshot, recommended next action, and a release reminder when all cycle tasks are Done but release has not run. Read-only, does not modify any files. PAPI detects build capability from the connecting harness (clientInfo); pass `environment` only to override that detection for git-dependent recommendations (build_execute, release, review_submit).",
   annotations: { title: "Orient Session", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
   inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
     properties: {
       environment: {
@@ -26920,7 +27859,13 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
       lines.push(`**Nearing Closure:** ${hierarchy.phasesNearingClosure.join(", ")}`);
     }
     if (hierarchy.stageExitCriteria && hierarchy.stageExitCriteria.length > 0) {
-      lines.push(`**Stage Exit Criteria:** ${hierarchy.stageExitCriteria.map((c) => `[ ] ${c}`).join(" | ")}`);
+      const crit = hierarchy.stageExitCriteria;
+      const met = crit.filter((c) => c.met).length;
+      const total = crit.length;
+      lines.push(`**Stage Exit Criteria [${met}/${total} met]:** ${crit.map((c) => `${c.met ? "[x]" : "[ ]"} ${c.text}`).join(" | ")}`);
+      if (met === total) {
+        lines.push("  \u21B3 All exit criteria met \u2014 run `strategy_review` to propose advancing the stage.");
+      }
     }
     lines.push("");
   }
@@ -27125,9 +28070,9 @@ function formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds) {
     for (const issue of alerts) {
       const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
       lines.push(`- **${issue.severity}**: ${desc}`);
-      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})`);
+      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})${issue.id ? ` \xB7 id \`${issue.id}\`` : ""}`);
     }
-    lines.push("_Escalate: run `idea` with P1 priority to log as a backlog task, or `board_edit` if already handled._");
+    lines.push("_Already fixed? `discovered_issue_resolve <id>` clears it for good (won't reappear). Not yet? `idea` with P1 priority to log it as a backlog task._");
     alertsNote = lines.join("\n");
   }
   if (allLowSev.length > 0) {
@@ -27137,18 +28082,18 @@ function formatDiscoveredIssuesBlocks(candidateLearnings, closedTaskIds) {
     for (const issue of unactioned) {
       const desc = issue.summary.length > 100 ? `${issue.summary.slice(0, 97)}\u2026` : issue.summary;
       lines.push(`- **${issue.severity}**: ${desc}`);
-      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})`);
+      lines.push(`  \u21B3 discovered during ${issue.taskId} (C${issue.cycleNumber})${issue.id ? ` \xB7 id \`${issue.id}\`` : ""}`);
     }
-    lines.push("_Run `idea` to log these as backlog tasks, or `board_edit` if already handled._");
+    lines.push("_Already fixed? `discovered_issue_resolve <id>` clears it. Otherwise `idea` to log as a backlog task._");
     unactionedIssuesNote = lines.join("\n");
   }
   return { alertsNote, unactionedIssuesNote };
 }
-async function computeTeamSummary(adapter2) {
+async function computeTeamSummary(adapter2, contributorsInput) {
   if (typeof adapter2.listContributors !== "function") return void 0;
   let members;
   try {
-    members = (await adapter2.listContributors()).length;
+    members = (await (contributorsInput ?? adapter2.listContributors())).length;
   } catch {
     return void 0;
   }
@@ -27165,11 +28110,11 @@ async function computeTeamSummary(adapter2) {
   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) {
+async function computeReleaseHistory(adapter2, contributorsInput) {
   if (typeof adapter2.listContributors !== "function") return void 0;
   let contributors;
   try {
-    contributors = await adapter2.listContributors();
+    contributors = await (contributorsInput ?? adapter2.listContributors());
   } catch {
     return void 0;
   }
@@ -27500,13 +28445,13 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       // "writing to the wrong project" for multi-project users on a shared key / stateless
       // HTTP transport where a once-per-session gate can't work.
       tracked("project-banner", async () => {
-        if (!adapter2.getProjectInfo) return { banner: "", name: void 0 };
+        if (!adapter2.getProjectInfo) return { banner: "", name: void 0, repoConnected: void 0 };
         const projectInfo = await adapter2.getProjectInfo();
-        if (!projectInfo) return { banner: "", name: void 0 };
+        if (!projectInfo) return { banner: "", name: void 0, repoConnected: void 0 };
         const banner = getProjectConnectionBanner(projectInfo.name, projectInfo.slug);
         return { banner: banner ? `
 > ${banner}
-` : "", name: projectInfo.name };
+` : "", name: projectInfo.name, repoConnected: !!projectInfo.repo_url };
       }),
       // Session guidance — proactive nudges (doc_register, context bloat, mode switch)
       tracked("session-guidance", async () => {
@@ -27644,7 +28589,7 @@ ${versionDrift}` : "";
     const patternsNote = patternsOutcome.status === "fulfilled" ? patternsOutcome.value : "";
     const { alertsNote, unactionedIssuesNote } = discoveredIssuesOutcome.status === "fulfilled" ? discoveredIssuesOutcome.value : { alertsNote: "", unactionedIssuesNote: "" };
     const skillProposalsNote = skillScanOutcome.status === "fulfilled" ? skillScanOutcome.value : "";
-    const projectBannerResult = projectBannerOutcome.status === "fulfilled" ? projectBannerOutcome.value : { banner: "", name: void 0 };
+    const projectBannerResult = projectBannerOutcome.status === "fulfilled" ? projectBannerOutcome.value : { banner: "", name: void 0, repoConnected: void 0 };
     const projectBannerNote = projectBannerResult.banner;
     const projectName = projectBannerResult.name;
     const sessionGuidanceNote = sessionGuidanceOutcome.status === "fulfilled" ? sessionGuidanceOutcome.value : "";
@@ -27685,16 +28630,27 @@ ${versionDrift}` : "";
         preBuildCheckNote = lines.join("\n");
       }
     }
-    tracker.mark("unblock-candidates");
-    let unblockNote = "";
-    try {
-      const candidates = await tracked("unblock-candidates", () => findUnblockCandidates(adapter2, currentCycle))();
-      const section = formatUnblockSection(candidates);
-      if (section) unblockNote = `
+    tracker.mark("parallel-tail");
+    const sharedContributorsPromise = typeof adapter2.listContributors === "function" ? adapter2.listContributors().catch(() => []) : Promise.resolve([]);
+    const [unblockCandidates, subAgents, teamSummaryLine, releaseHistoryLine, carryForwardRefs] = await Promise.all([
+      tracked("unblock-candidates", () => findUnblockCandidates(adapter2, currentCycle))().catch(() => []),
+      // task-1866: discover project sub-agents for the orient surface (read-only, never throws).
+      listAgents(config2.projectRoot),
+      // task-2071 (MU-3) + task-2072 (MU-5): team summary + release-history — both
+      // multi-member only; solo projects get undefined from both, so orient stays
+      // byte-identical there.
+      tracked("team-summary", () => computeTeamSummary(adapter2, sharedContributorsPromise))().catch(() => void 0),
+      tracked("release-history", () => computeReleaseHistory(adapter2, sharedContributorsPromise))().catch(() => void 0),
+      // task-2751 (C332): resolve every task-NNNN mentioned in the Carry-Forward
+      // prose to its title so orient can name it inline. Built from the board
+      // already in hand — no extra query.
+      resolveCarryForwardRefs(healthResult.carryForward, allTasks, adapter2)
+    ]);
+    const unblockSection = formatUnblockSection(unblockCandidates);
+    const unblockNote = unblockSection ? `
 
-${section}`;
-    } catch {
-    }
+${unblockSection}` : "";
+    const teamSummary = [teamSummaryLine, releaseHistoryLine].filter(Boolean).join("\n") || void 0;
     let deferredGateNote = "";
     if (deepHousekeeping) {
       try {
@@ -27706,16 +28662,22 @@ ${section}`;
       } catch {
       }
     }
+    let onboardingCoachingNote = "";
+    try {
+      const adsForCoaching = await sharedActiveDecisionsPromise;
+      onboardingCoachingNote = formatOnboardingCoachingBlock({
+        surface: "orient",
+        repoConnected: projectBannerResult.repoConnected,
+        hasLocalWorkspace: hasLocalWorkspace(),
+        hasActiveDecisions: adsForCoaching.length > 0,
+        cycleNumber: currentCycle,
+        hasActiveCycle: currentCycle > 0 && !cycleIsComplete
+      });
+    } catch {
+    }
     tracker.mark("format-summary");
-    const subAgents = await listAgents(config2.projectRoot);
-    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, merged-but-In-Progress tasks, unrecorded commits, unregistered docs, and stale skill forks (implies `full`).*";
-    const carryForwardRefs = await resolveCarryForwardRefs(healthResult.carryForward, allTasks, adapter2);
-    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
+    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents, projectName, teamSummary, clientName, carryForwardRefs) + unblockNote + deferredGateNote + feedbackResolvedNote + alertsNote + ttfvNote + reconciliationNote + mergedInProgressNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + onboardingCoachingNote + 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);
@@ -27770,7 +28732,7 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
 // src/tools/hierarchy.ts
 var hierarchyUpdateTool = {
   name: "hierarchy_update",
-  description: "Update the status of a phase, stage, or horizon in the project hierarchy (AD-14). Accepts a level (phase, stage, or horizon), a name or ID, and a new status. For stages, optionally set exit_criteria \u2014 a checklist defining when the stage is considered done. Does not call the Anthropic API.",
+  description: "Create or update a horizon, stage, or phase in the project hierarchy (AD-14). For stages and horizons this UPSERTS: if the named entity exists it is updated, otherwise it is CREATED (pass a label). Phases are update-only (they evolve via plan/strategy). For stages you can set exit_criteria (a checklist), or flip a single criterion with set_criterion_met. NEVER auto-advances \u2014 progression is human-in-loop via strategy_review. Does not call the Anthropic API.",
   annotations: { title: "Update Hierarchy", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -27778,129 +28740,218 @@ var hierarchyUpdateTool = {
       level: {
         type: "string",
         enum: ["phase", "stage", "horizon"],
-        description: "Which hierarchy level to update."
+        description: "Which hierarchy level to create/update."
       },
       name: {
         type: "string",
-        description: "The label or ID of the stage/horizon to update."
+        description: "The label, slug, or ID of the entity. On create, becomes the label if `label` is omitted."
+      },
+      label: {
+        type: "string",
+        description: 'Display label. Required to CREATE a new stage/horizon when `name` does not match an existing one (e.g. "S2: Alpha Cohort").'
+      },
+      slug: {
+        type: "string",
+        description: "Explicit slug for a new entity (stage/horizon). Auto-derived from the label when omitted."
+      },
+      description: {
+        type: "string",
+        description: "Optional longer description (stage/horizon)."
       },
       status: {
         type: "string",
         enum: ["Not Started", "In Progress", "Done", "Deferred"],
-        description: "The new status to set."
+        description: 'The status to set. On create, defaults to "Not Started".'
+      },
+      sort_order: {
+        type: "number",
+        description: "Display order for a new entity. Auto-computed (max existing + 10) when omitted."
+      },
+      horizon: {
+        type: "string",
+        description: "Parent horizon (name/slug/id) when CREATING a stage. Defaults to the sole horizon if only one exists."
       },
       exit_criteria: {
         type: "array",
         items: { type: "string" },
-        description: 'Checklist defining when this stage is done (stages only). Each item is a completion condition, e.g. "All P0 tasks shipped". Replaces existing criteria.'
+        description: "Checklist defining when a STAGE is done. Each item is a completion condition. REPLACES existing criteria (resets met state \u2014 use set_criterion_met to flip one)."
+      },
+      set_criterion_met: {
+        type: "object",
+        description: "Flip a single stage exit criterion (task-1625). { criterion_id, met, evidence? }.",
+        properties: {
+          criterion_id: { type: "string", description: "The ExitCriterion id to flip." },
+          met: { type: "boolean", description: "true = met, false = unmet." },
+          evidence: { type: "string", description: 'Optional evidence for a met criterion (e.g. "task-1234 shipped").' }
+        },
+        required: ["criterion_id", "met"]
       }
     },
     required: ["level", "name"]
   }
 };
 var VALID_STATUSES3 = /* @__PURE__ */ new Set(["Not Started", "In Progress", "Done", "Deferred"]);
+function slugify(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "item";
+}
+function nextSortOrder(existing) {
+  if (existing.length === 0) return 10;
+  return Math.max(...existing.map((e) => e.sortOrder)) + 10;
+}
 async function handleHierarchyUpdate(adapter2, args) {
   const level = args.level;
   const name = args.name;
+  const label = args.label;
+  const slug = args.slug;
+  const description = args.description;
   const status = args.status;
+  const sortOrder = typeof args.sort_order === "number" ? args.sort_order : void 0;
+  const horizonRef = args.horizon;
   const exitCriteria = args.exit_criteria;
+  const setCriterion = args.set_criterion_met;
   if (!level || !name) {
     return errorResponse("Missing required parameters: level, name.");
   }
-  if (!status && !exitCriteria) {
-    return errorResponse("Nothing to update. Provide at least one of: status, exit_criteria.");
-  }
   if (level !== "phase" && level !== "stage" && level !== "horizon") {
     return errorResponse(`Invalid level "${level}". Must be "phase", "stage", or "horizon".`);
   }
   if (status && !VALID_STATUSES3.has(status)) {
     return errorResponse(`Invalid status "${status}". Must be one of: Not Started, In Progress, Done, Deferred.`);
   }
-  if (exitCriteria !== void 0 && level !== "stage") {
-    return errorResponse("exit_criteria can only be set on stages.");
+  if ((exitCriteria !== void 0 || setCriterion !== void 0) && level !== "stage") {
+    return errorResponse("exit_criteria and set_criterion_met can only be used on stages.");
+  }
+  if (!status && exitCriteria === void 0 && setCriterion === void 0 && !label) {
+    return errorResponse("Nothing to do. Provide at least one of: status, exit_criteria, set_criterion_met, or label (to create).");
   }
   try {
     if (level === "phase") {
-      if (!adapter2.readPhases || !adapter2.updatePhaseStatus) {
-        return errorResponse("Phase management is not supported by the current adapter.");
-      }
-      const phases = await adapter2.readPhases();
-      const phase = phases.find(
-        (p) => p.label.toLowerCase() === name.toLowerCase() || p.id === name || p.slug === name
-      );
-      if (!phase) {
-        const available = phases.map((p) => p.label).join(", ");
-        return errorResponse(`Phase "${name}" not found. Available phases: ${available || "none"}`);
-      }
-      if (!status) {
-        return errorResponse("status is required for phase updates.");
-      }
-      if (phase.status === status) {
-        return textResponse(`Phase "${phase.label}" is already "${status}". No change made.`);
-      }
-      const oldStatus2 = phase.status;
-      await adapter2.updatePhaseStatus(phase.id, status);
-      return textResponse(`Phase updated: **${phase.label}** ${oldStatus2} \u2192 ${status}`);
+      return await handlePhase(adapter2, name, status);
     }
     if (level === "stage") {
-      if (!adapter2.readStages) {
-        return errorResponse("Stage management is not supported by the current adapter.");
-      }
-      const stages = await adapter2.readStages();
-      const stage = stages.find(
-        (s) => s.label.toLowerCase() === name.toLowerCase() || s.id === name || s.slug === name
-      );
-      if (!stage) {
-        const available = stages.map((s) => s.label).join(", ");
-        return errorResponse(`Stage "${name}" not found. Available stages: ${available || "none"}`);
-      }
-      const resultLines = [];
-      if (status) {
-        if (!adapter2.updateStageStatus) {
-          return errorResponse("Stage status updates are not supported by the current adapter.");
-        }
-        if (stage.status === status) {
-          resultLines.push(`Stage "${stage.label}" is already "${status}".`);
-        } else {
-          const oldStatus2 = stage.status;
-          await adapter2.updateStageStatus(stage.id, status);
-          resultLines.push(`Stage updated: **${stage.label}** ${oldStatus2} \u2192 ${status}`);
-        }
-      }
-      if (exitCriteria !== void 0) {
-        if (!adapter2.updateStageExitCriteria) {
-          return errorResponse("Exit criteria updates are not supported by the current adapter.");
-        }
-        await adapter2.updateStageExitCriteria(stage.id, exitCriteria);
-        resultLines.push(`Exit criteria set (${exitCriteria.length} item${exitCriteria.length !== 1 ? "s" : ""}):`);
-        exitCriteria.forEach((c) => resultLines.push(`  - ${c}`));
-      }
-      return textResponse(resultLines.join("\n"));
-    }
-    if (!adapter2.readHorizons || !adapter2.updateHorizonStatus) {
-      return errorResponse("Horizon management is not supported by the current adapter.");
-    }
-    const horizons = await adapter2.readHorizons();
-    const horizon = horizons.find(
-      (h) => h.label.toLowerCase() === name.toLowerCase() || h.id === name || h.slug === name
-    );
-    if (!horizon) {
-      const available = horizons.map((h) => h.label).join(", ");
-      return errorResponse(`Horizon "${name}" not found. Available horizons: ${available || "none"}`);
-    }
-    if (!status) {
-      return errorResponse("status is required for horizon updates.");
-    }
-    if (horizon.status === status) {
-      return textResponse(`Horizon "${horizon.label}" is already "${status}". No change made.`);
+      return await handleStage(adapter2, { name, label, slug, description, status, sortOrder, horizonRef, exitCriteria, setCriterion });
     }
-    const oldStatus = horizon.status;
-    await adapter2.updateHorizonStatus(horizon.id, status);
-    return textResponse(`Horizon updated: **${horizon.label}** ${oldStatus} \u2192 ${status}`);
+    return await handleHorizon(adapter2, { name, label, slug, description, status, sortOrder });
   } catch (err) {
     return errorResponse(err instanceof Error ? err.message : String(err));
   }
 }
+async function handlePhase(adapter2, name, status) {
+  if (!adapter2.readPhases || !adapter2.updatePhaseStatus) {
+    return errorResponse("Phase management is not supported by the current adapter.");
+  }
+  if (!status) return errorResponse("status is required for phase updates.");
+  const phases = await adapter2.readPhases();
+  const phase = phases.find((p) => p.label.toLowerCase() === name.toLowerCase() || p.id === name || p.slug === name);
+  if (!phase) {
+    const available = phases.map((p) => p.label).join(", ");
+    return errorResponse(`Phase "${name}" not found. Available phases: ${available || "none"} (phases are update-only \u2014 create them via plan/setup).`);
+  }
+  if (phase.status === status) return textResponse(`Phase "${phase.label}" is already "${status}". No change made.`);
+  const oldStatus = phase.status;
+  await adapter2.updatePhaseStatus(phase.id, status);
+  return textResponse(`Phase updated: **${phase.label}** ${oldStatus} \u2192 ${status}`);
+}
+async function handleStage(adapter2, a) {
+  if (!adapter2.readStages) {
+    return errorResponse("Stage management is not supported by the current adapter.");
+  }
+  const stages = await adapter2.readStages();
+  let stage = stages.find(
+    (s) => s.label.toLowerCase() === a.name.toLowerCase() || s.id === a.name || s.slug === a.name
+  );
+  const resultLines = [];
+  let created = false;
+  if (!stage) {
+    if (!adapter2.createHorizon || !adapter2.createStage || !adapter2.readHorizons) {
+      return errorResponse("Stage creation is not supported by the current adapter.");
+    }
+    const createLabel = a.label ?? a.name;
+    const horizons = await adapter2.readHorizons();
+    let parent;
+    if (a.horizonRef) {
+      parent = horizons.find((h) => h.label.toLowerCase() === a.horizonRef.toLowerCase() || h.id === a.horizonRef || h.slug === a.horizonRef);
+      if (!parent) {
+        const available = horizons.map((h) => h.label).join(", ");
+        return errorResponse(`Parent horizon "${a.horizonRef}" not found. Available horizons: ${available || "none"}.`);
+      }
+    } else if (horizons.length === 1) {
+      parent = horizons[0];
+    } else if (horizons.length === 0) {
+      return errorResponse('No horizon exists to attach the stage to. Create a horizon first (level:"horizon", label:"H1: ...").');
+    } else {
+      return errorResponse(`Multiple horizons exist \u2014 pass \`horizon\` to say which one the stage belongs to: ${horizons.map((h) => h.label).join(", ")}.`);
+    }
+    const newId = await adapter2.createStage({
+      slug: a.slug ?? slugify(createLabel),
+      label: createLabel,
+      description: a.description,
+      status: a.status ?? "Not Started",
+      sortOrder: a.sortOrder ?? nextSortOrder(stages.filter((s) => s.horizonId === parent.id)),
+      horizonId: parent.id
+    });
+    const refreshed = await adapter2.readStages();
+    stage = refreshed.find((s) => s.id === newId);
+    if (!stage) return errorResponse("Stage was created but could not be re-read.");
+    created = true;
+    resultLines.push(`Stage created: **${stage.label}** (under ${parent.label}, status ${stage.status})`);
+  }
+  if (a.status && !created) {
+    if (!adapter2.updateStageStatus) return errorResponse("Stage status updates are not supported by the current adapter.");
+    if (stage.status === a.status) {
+      resultLines.push(`Stage "${stage.label}" is already "${a.status}".`);
+    } else {
+      const oldStatus = stage.status;
+      await adapter2.updateStageStatus(stage.id, a.status);
+      resultLines.push(`Stage updated: **${stage.label}** ${oldStatus} \u2192 ${a.status}`);
+    }
+  }
+  if (a.exitCriteria !== void 0) {
+    if (!adapter2.updateStageExitCriteria) return errorResponse("Exit criteria updates are not supported by the current adapter.");
+    await adapter2.updateStageExitCriteria(stage.id, a.exitCriteria);
+    resultLines.push(`Exit criteria set (${a.exitCriteria.length} item${a.exitCriteria.length !== 1 ? "s" : ""}, all unmet):`);
+    a.exitCriteria.forEach((c) => resultLines.push(`  - ${c}`));
+  }
+  if (a.setCriterion !== void 0) {
+    if (!adapter2.setCriterionMet) return errorResponse("set_criterion_met is not supported by the current adapter.");
+    await adapter2.setCriterionMet(stage.id, a.setCriterion.criterion_id, a.setCriterion.met, a.setCriterion.evidence ?? null);
+    const after = (await adapter2.readStages()).find((s) => s.id === stage.id);
+    const crit = after?.exitCriteria?.find((c) => c.id === a.setCriterion.criterion_id);
+    if (!crit) {
+      resultLines.push(`\u26A0\uFE0F Criterion id "${a.setCriterion.criterion_id}" not found on this stage \u2014 no change.`);
+    } else {
+      const met = after?.exitCriteria?.filter((c) => c.met).length ?? 0;
+      const total = after?.exitCriteria?.length ?? 0;
+      resultLines.push(`Criterion "${crit.text}" \u2192 ${crit.met ? "met" : "unmet"}. [${met}/${total} criteria met]`);
+    }
+  }
+  return textResponse(resultLines.join("\n"));
+}
+async function handleHorizon(adapter2, a) {
+  if (!adapter2.readHorizons) {
+    return errorResponse("Horizon management is not supported by the current adapter.");
+  }
+  const horizons = await adapter2.readHorizons();
+  const horizon = horizons.find((h) => h.label.toLowerCase() === a.name.toLowerCase() || h.id === a.name || h.slug === a.name);
+  if (!horizon) {
+    if (!adapter2.createHorizon) return errorResponse("Horizon creation is not supported by the current adapter.");
+    const createLabel = a.label ?? a.name;
+    const newId = await adapter2.createHorizon({
+      slug: a.slug ?? slugify(createLabel),
+      label: createLabel,
+      description: a.description,
+      status: a.status ?? "Not Started",
+      sortOrder: a.sortOrder ?? nextSortOrder(horizons)
+    });
+    return textResponse(`Horizon created: **${createLabel}** (id ${newId}, status ${a.status ?? "Not Started"})`);
+  }
+  if (!a.status) return errorResponse("status is required to update an existing horizon (or pass a new name to create one).");
+  if (horizon.status === a.status) return textResponse(`Horizon "${horizon.label}" is already "${a.status}". No change made.`);
+  if (!adapter2.updateHorizonStatus) return errorResponse("Horizon status updates are not supported by the current adapter.");
+  const oldStatus = horizon.status;
+  await adapter2.updateHorizonStatus(horizon.id, a.status);
+  return textResponse(`Horizon updated: **${horizon.label}** ${oldStatus} \u2192 ${a.status}`);
+}
 
 // src/services/zoom-out.ts
 var BUDGET_SOFT = 12e4;
@@ -29906,6 +30957,7 @@ var PAPI_TOOLS = [
   buildExecuteTool,
   buildCancelTool,
   ideaTool,
+  backlogImportTool,
   bugTool,
   bugListTool,
   adHocTool,
@@ -30088,6 +31140,8 @@ function createServer(adapter2, config2) {
           return handleBuildCancel(adapter2, safeArgs);
         case "idea":
           return handleIdea(adapter2, config2, safeArgs);
+        case "backlog_import":
+          return handleBacklogImport(adapter2, safeArgs);
         case "bug":
           return handleBug(adapter2, config2, safeArgs);
         case "bug_list":
@@ -30664,7 +31718,11 @@ async function dispatchRequest(args) {
   const requestConfig = {
     ...baseConfig,
     adapterType: "proxy",
-    projectId: effectiveProjectId
+    projectId: effectiveProjectId,
+    // Remote transport: the client cannot read files this server writes, so
+    // prepare must keep returning inline blobs (2905's budget bounds them),
+    // never a server-side file path (task-2906).
+    localFilesystem: false
   };
   const server2 = createServer(adapter2, requestConfig);
   const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });