@papi-ai/server 0.7.108 → 0.7.113

package/README.md

@@ -43,6 +43,17 @@ PAPI collects anonymous usage data (tool name, duration, project UUID — no cod
 
 PAPI is configured with `PAPI_PROJECT_ID` and `PAPI_DATA_API_KEY` — both are generated by the onboarding wizard at [getpapi.ai](https://getpapi.ai/) and pasted into your `.mcp.json`. If those env vars aren't set, PAPI will fall back to local file storage (md mode) and emit a stderr warning that your cycles aren't visible on the dashboard. To get on the dashboard, sign up at [getpapi.ai](https://getpapi.ai/) and use the config it gives you.
 
+### Stdio idle shutdown
+
+The stdio server exits cleanly after two minutes without input, including its
+database adapter pool, so abandoned client sessions do not accumulate. Set
+`PAPI_STDIO_IDLE_TIMEOUT_MS=0` to disable this behavior, or provide another
+non-negative millisecond value in the `.mcp.json` environment block. This
+setting applies only to stdio mode; hosted HTTP instances are not idle-killed.
+While `plan`, `handoff_generate`, or `strategy_review` is between its prepare
+and apply calls, the server allows an additional bounded grace period for the
+caller to finish the review instead of treating that intentional pause as idle.
+
 ## License
 
 [Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — free to use, self-host, and modify. Commercial hosting requires a license.

package/dist/index.js

@@ -7075,7 +7075,7 @@ async function resolveMutationProject(input) {
   if (input.workspacePath) {
     if (!storedPapiDir) {
       throw new ProjectResolutionError(
-        `Project "${projectSlug}" has no stored workspace mapping. Refusing to write from "${input.workspacePath}" until the project is explicitly mapped.`
+        `Project "${projectSlug}" has no stored workspace mapping. Refusing to write from "${input.workspacePath}" until the project is explicitly mapped. If your working directory belongs to a different project, run \`project_switch\` or pass \`project=<id>\` on the call.`
       );
     }
     try {
@@ -7087,7 +7087,7 @@ async function resolveMutationProject(input) {
       });
       if (pathResult?.action !== "ok") {
         throw new ProjectResolutionError(
-          `Project "${projectSlug}" has not been explicitly verified for this workspace. Refusing to write until its mapping is confirmed.`
+          `Project "${projectSlug}" has not been explicitly verified for this workspace ("${input.workspacePath}"). Refusing to write until its mapping is confirmed. If this session is bound to the wrong project, run \`project_switch\` or pass \`project=<id>\` on the call.`
         );
       }
     } catch (err) {
@@ -7133,6 +7133,10 @@ async function resolveMutationProject(input) {
 function formatMutationScopeReceipt(scope) {
   const target = scope.targetProject ? `
 Target project: ${scope.targetProject.name} (${scope.targetProject.slug}, ${scope.targetProject.id})` : "";
+  const workspaceUnverified = scope.workspacePath.startsWith("unavailable");
+  const noMapping = /mapping=none/.test(scope.resolutionEvidence);
+  const unverifiedNote = workspaceUnverified && noMapping ? `
+\u26A0 This project was bound from your MCP config with no workspace cross-check \u2014 PAPI cannot confirm it matches your working directory. If a write ever lands on the wrong board: pass \`project=<id>\` per call, run \`project_switch\`, or fix PAPI_PROJECT_ID / the x-papi-project-id header and reconnect.` : "";
   return [
     "---",
     "Project scope receipt",
@@ -7140,7 +7144,8 @@ Target project: ${scope.targetProject.name} (${scope.targetProject.slug}, ${scop
     `Repository evidence: ${scope.repositoryEvidence}`,
     `Workspace: ${scope.workspacePath}`,
     `Resolution: ${scope.resolutionEvidence}`,
-    target.trimStart()
+    target.trimStart(),
+    unverifiedNote.trimStart()
   ].filter(Boolean).join("\n");
 }
 
@@ -7558,9 +7563,10 @@ function resolveServerName(serverName) {
   const candidate = serverName?.trim();
   return candidate && SAFE_SERVER_NAME.test(candidate) ? candidate : DEFAULT_SERVER_NAME;
 }
-function formatConnectionBanner(identity) {
+function formatConnectionBanner(identity, health = "connected") {
   const projectIdShort = identity.projectId ? ` (${identity.projectId.slice(0, 8)})` : "";
-  return `[papi] Connected \u2014 server: ${resolveServerName(identity.serverName)}, project: ${identity.projectName}${projectIdShort}, adapter: ${identity.adapterType}, v${identity.pkgVersion}`;
+  const lead = health === "degraded" ? "Degraded \u2014 data may be stale" : health === "offline" ? "Offline \u2014 no database connection" : "Connected";
+  return `[papi] ${lead} \u2014 server: ${resolveServerName(identity.serverName)}, project: ${identity.projectName}${projectIdShort}, adapter: ${identity.adapterType}, v${identity.pkgVersion}`;
 }
 
 // src/server.ts
@@ -11034,7 +11040,7 @@ function isBlockerResolved(blocker, ctx) {
       if (decision?.outcome && resolvedOutcomes.has(decision.outcome)) return true;
       if (decision?.resolutionState === "resolved") return true;
       const hasRecentEvent = ctx.decisionEvents.some(
-        (e) => idMatches(e.decisionId, blocker.ref) && e.cycle >= blocker.blockedCycle && !PROPOSAL_EVENT_TYPES.includes(e.eventType)
+        (e) => idMatches(e.decisionId, blocker.ref) && e.cycle >= blocker.blockedCycle && !PROPOSAL_EVENT_TYPES.includes(e.eventType) && e.source !== "build_complete"
       );
       return hasRecentEvent;
     }
@@ -11240,6 +11246,20 @@ function determineContextTier(cycleCount) {
   if (cycleCount <= 20) return 2;
   return 3;
 }
+function trimContextForFirstCycle(ctx, cycleCount) {
+  if (cycleCount !== 0 || ctx.mode === "bootstrap") return;
+  ctx.cycleLog = "";
+  ctx.recentBuildReports = "";
+  const ad = ctx.activeDecisions;
+  if (ad && ad.includes("[Confidence: ")) {
+    const blocks = ad.split(/\n(?=### )/);
+    const highOnly = blocks.filter(
+      (b2) => !b2.startsWith("### ") || /\[Confidence: HIGH\]/.test(b2)
+    );
+    const trimmed = highOnly.join("\n").trim();
+    ctx.activeDecisions = trimmed.length > 0 ? trimmed : ad;
+  }
+}
 function applyContextTier(ctx, cycleCount) {
   const tier = determineContextTier(cycleCount);
   const label = tier === 1 ? "Tier 1 (cycles 1-5)" : tier === 2 ? "Tier 2 (cycles 6-20)" : "Tier 3 (cycles 21+)";
@@ -11993,6 +12013,7 @@ ${lines.join("\n")}`;
       siblingRepoWarning
     };
     const { label: leanTierLabel } = applyContextTier(ctx2, health.totalCycles);
+    trimContextForFirstCycle(ctx2, health.totalCycles);
     ctx2.contextTier = leanTierLabel;
     console.error(`[plan-perf] context tier: ${leanTierLabel} (cycle ${health.totalCycles})`);
     t = startTimer();
@@ -12190,6 +12211,7 @@ ${logLines}`);
     siblingRepoWarning
   };
   const { label: fullTierLabel } = applyContextTier(ctx, health.totalCycles);
+  trimContextForFirstCycle(ctx, health.totalCycles);
   ctx.contextTier = fullTierLabel;
   console.error(`[plan-perf] context tier: ${fullTierLabel} (cycle ${health.totalCycles})`);
   const prevHashes = contextHashesResultFull.status === "fulfilled" ? contextHashesResultFull.value : null;
@@ -12817,15 +12839,20 @@ async function assertSingleActiveCycle(adapter2, opts = {}) {
   for (const c of cycles) {
     if (!newestByNumber.has(c.number)) newestByNumber.set(c.number, c);
   }
-  const blocking = [...newestByNumber.values()].filter((c) => c.status === "active" && c.number !== opts.allowNumber).filter((c) => opts.userId == null || c.userId === opts.userId);
-  if (blocking.length === 0) return [];
+  const blockingAll = [...newestByNumber.values()].filter((c) => c.status === "active" && c.number !== opts.allowNumber).filter((c) => opts.userId == null || c.userId === opts.userId);
+  const phantoms = blockingAll.filter((c) => (c.goals?.length ?? 0) === 0);
+  const blocking = blockingAll.filter((c) => (c.goals?.length ?? 0) > 0);
+  const phantomNotes = phantoms.map(
+    (c) => `Absorbed phantom active cycle ${c.number} (no goals \u2014 incomplete plan apply). Re-planning replaces it.`
+  );
+  if (blocking.length === 0) return phantomNotes;
   if (!opts.autoComplete) {
     const nums = blocking.map((c) => c.number).join(", ");
     throw new Error(
       `Cycle ${nums} is still active for this project \u2014 a second active cycle corrupts orient/build_execute. Run \`release\` to complete it first, or pass \`force: true\` to auto-complete it and continue.`
     );
   }
-  const notes = [];
+  const notes = [...phantomNotes];
   for (const stale of blocking) {
     await adapter2.createCycle({
       ...stale,
@@ -12860,6 +12887,18 @@ async function validateAndPrepare(adapter2, force, callerUserId, adapterType) {
     const health = await adapter2.getCycleHealth();
     cycleNumber = health.totalCycles;
     mode = determineMode(health.projectCycleCount ?? health.totalCycles);
+    try {
+      const cyclesForPhantomCheck = await adapter2.readCycles();
+      let callerNewest;
+      for (const c of cyclesForPhantomCheck) {
+        if (callerUserId && c.userId != null && c.userId !== callerUserId) continue;
+        if (!callerNewest || c.number > callerNewest.number) callerNewest = c;
+      }
+      if (callerNewest && callerNewest.status === "active" && (callerNewest.goals?.length ?? 0) === 0 && callerNewest.number === cycleNumber) {
+        cycleNumber = callerNewest.number - 1;
+      }
+    } catch {
+    }
     const blockingCycle = callerUserId ? await resolveCallerLatestCycle(adapter2, callerUserId) : void 0;
     const latestStatus = callerUserId ? blockingCycle?.status : health.latestCycleStatus;
     const blockingNumber = blockingCycle?.number ?? cycleNumber;
@@ -12950,6 +12989,11 @@ function assertApplyPayloadNonEmpty(data, cycleNumber) {
       `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).`
     );
   }
+  if (!data.cycleLogTitle || data.cycleLogTitle.trim().length === 0) {
+    throw new Error(
+      `Plan apply rejected: trimmed/partial apply payload \u2014 nothing persisted. The parsed plan for Cycle ${cycleNumber + 1} has no cycleLogTitle, so the cycle row would be written with empty goals \u2014 the phantom-cycle failure mode that blocks the next plan and renders nowhere on the hub. Re-run the plan and resend the COMPLETE structured output including cycleLogTitle.`
+    );
+  }
 }
 var VALID_PLAN_PRIORITIES = /* @__PURE__ */ new Set(["P0 Critical", "P1 High", "P2 Medium", "P3 Low"]);
 function assertPlanPrioritiesValid(data) {
@@ -13086,7 +13130,7 @@ async function processLlmOutput(adapter2, config2, rawOutput, mode, cycleNumber,
     decisionConflicts
   };
 }
-async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density) {
+async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density, taskIds) {
   const prepareTimer = startTimer();
   tracker?.mark("validate_and_prepare");
   let t = startTimer();
@@ -13114,10 +13158,43 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     tracker?.mark("handoffs_only_assemble");
     t = startTimer();
     const targetCycle = cycleNumber + 1;
-    const allTasks = await adapter2.queryBoard({ status: ["Backlog", "In Cycle", "Ready", "In Progress"] });
-    const preAssigned = allTasks.filter((task) => task.cycle === targetCycle);
-    if (preAssigned.length === 0) {
-      throw new Error(`No tasks assigned to Cycle ${targetCycle}. Assign tasks first (set cycle = ${targetCycle} via SQL) or run plan without handoffs_only.`);
+    const allTasks = await adapter2.queryBoard({ status: ["Backlog", "In Cycle", "Ready", "In Progress", "In Review", "Blocked"] });
+    let preAssigned;
+    if (taskIds && taskIds.length > 0) {
+      const byDisplayId = new Map(allTasks.map((t2) => [t2.displayId ?? t2.id, t2]));
+      const byId = new Map(allTasks.map((t2) => [t2.id, t2]));
+      const BUILDABLE = /* @__PURE__ */ new Set(["Backlog", "In Cycle", "Ready"]);
+      const resolved = [];
+      const rejected = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const raw of taskIds) {
+        const task = byDisplayId.get(raw) ?? byId.get(raw);
+        if (!task) {
+          rejected.push(`${raw}: not a task in this project (or already Done/Cancelled/Deferred)`);
+          continue;
+        }
+        if (seen.has(task.id)) continue;
+        seen.add(task.id);
+        if (!BUILDABLE.has(task.status)) {
+          rejected.push(`${raw}: status is "${task.status}" \u2014 only Backlog / In Cycle / Ready tasks can be planned`);
+          continue;
+        }
+        resolved.push(task);
+      }
+      if (rejected.length > 0) {
+        throw new Error(
+          `Cycle ${targetCycle} \u2014 nothing was applied. ${rejected.length} of ${taskIds.length} task id(s) could not be planned:
+` + rejected.map((r) => `  - ${r}`).join("\n") + `
+
+Fix the ids and re-run. Every id must be a currently-buildable task (Backlog / In Cycle / Ready) in this project.`
+        );
+      }
+      preAssigned = resolved;
+    } else {
+      preAssigned = allTasks.filter((task) => task.cycle === targetCycle);
+      if (preAssigned.length === 0) {
+        throw new Error(`No tasks assigned to Cycle ${targetCycle}. Assign tasks first (set cycle = ${targetCycle} via SQL) or run plan without handoffs_only.`);
+      }
     }
     const [decisions, reports, brief] = await Promise.all([
       adapter2.getActiveDecisions(),
@@ -13759,6 +13836,37 @@ function planDelivery(input) {
   }
 }
 
+// src/lib/harness-capability.ts
+var HARNESS_REGISTRY = {
+  // Local stdio CLI agents — PAPI runs git on the user's machine. Confirmed in telemetry.
+  "claude-code": { build: true, label: "Claude Code" },
+  "opencode": { build: true, label: "opencode" },
+  "zcode": { build: true, label: "zcode" },
+  "codex": { build: true, label: "Codex" },
+  "cursor": { build: true, label: "Cursor" },
+  // Cloud harnesses with code sandboxes — their agent builds in-sandbox over HTTP+OAuth.
+  "lovable": { build: true, label: "Lovable" },
+  "bolt": { build: true, label: "Bolt" },
+  "replit": { build: true, label: "Replit" },
+  // Chat-only surfaces, no sandbox — planning only.
+  "chatgpt": { build: false, label: "ChatGPT" },
+  "claude.ai": { build: false, label: "Claude.ai" },
+  "claude-desktop": { build: false, label: "Claude Desktop" }
+};
+var UNKNOWN_DEFAULT = { build: false, label: "your tool" };
+function detectHarness(clientName) {
+  const raw = clientName?.trim() || null;
+  if (!raw) {
+    return { ...UNKNOWN_DEFAULT, raw: null, key: null, known: false };
+  }
+  const norm = raw.toLowerCase();
+  const key = HARNESS_REGISTRY[norm] ? norm : Object.keys(HARNESS_REGISTRY).find((k) => norm.includes(k)) ?? null;
+  if (!key) {
+    return { ...UNKNOWN_DEFAULT, label: raw, raw, key: null, known: false };
+  }
+  return { ...HARNESS_REGISTRY[key], raw, key, known: true };
+}
+
 // src/services/session-guidance.ts
 var DEFAULT_CALLER_KEY = "__default__";
 var sessionStates = /* @__PURE__ */ new Map();
@@ -13835,7 +13943,7 @@ function markOrient(callerKey) {
 }
 function getProjectConnectionBanner(projectName, projectSlug) {
   if (!projectName || !projectSlug) return null;
-  return `[Connected: ${projectName} (${projectSlug})] \u2014 confirm this is the project you mean before I write to it. If it's wrong, don't proceed: pass \`project=<id>\` on the call to target a different project, or fix the project id in your MCP config (PAPI_PROJECT_ID for local, x-papi-project-id header for remote) and reconnect.`;
+  return `**\u26A0 Bound to: ${projectName} (${projectSlug})** \u2014 every write on this session lands on THIS project's board. If that is not the project your working directory belongs to, stop: pass \`project=<id>\` on the call to target a different project, run \`project_switch\` to rebind the session, or fix the project id in your MCP config (PAPI_PROJECT_ID for local, x-papi-project-id header for remote) and reconnect.`;
 }
 function detectContextDegradation(now = Date.now(), callerKey) {
   const state = getState(callerKey);
@@ -14018,6 +14126,9 @@ function savePrepareContextFile(projectId, callerKey, content) {
 
 // src/tools/plan.ts
 var planPrepareCache = new PerCallerCache();
+function hasPendingPlanPrepare() {
+  return planPrepareCache.size() > 0;
+}
 var planTool = {
   name: "plan",
   description: 'Turn a backlog into one scoped cycle of work, with a written spec for every task in it. plan reads the whole board, the decisions this project has already taken, and how much it actually delivered in recent cycles, then prioritises what to do next and writes a per-task BUILD HANDOFF: scope, what is deliberately out of scope, acceptance criteria, files likely touched, security notes, and the shared branch each task belongs on. It also reports board health, so stale, blocked and drifting work is visible instead of accumulating. This is not the same as planning inside one session: the cycle, the specs and the reasoning are stored, so the next session, the next tool, or the next person picks up where this one stopped. Run once per cycle, after setup the first time, or after completing all builds AND running release for the previous cycle. NEVER call when unbuilt cycle tasks exist: 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, and generate handoffs separately via `handoff_generate`.',
@@ -14080,6 +14191,11 @@ var planTool = {
         type: "boolean",
         description: "Skip backlog analysis and task selection. Only generate BUILD HANDOFFs for tasks already assigned to the target cycle. Requires pre-assigned tasks (set cycle number on tasks first). ~30% of normal plan cost."
       },
+      task_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: 'Plan EXACTLY these backlog tasks into the cycle, with BUILD HANDOFFs, via the same atomic apply as a normal plan. Use when the user says "take these tasks and get them build-ready" or "plan task-12, task-15, task-19" \u2014 do NOT reach for ad_hoc (a receipt) or board_edit (strands them with no handoff). Skips backlog selection: only the named tasks are scoped. Every id must be a real, currently-buildable task (Backlog / In Cycle / Ready) in this project \u2014 unknown or ineligible ids are rejected with a per-id reason and nothing is applied. The apply assigns cycle + handoff + status together, so a failure leaves nothing half-landed.'
+      },
       skip_handoffs: {
         type: "boolean",
         description: "Run full planning (triage, task selection, board management) but skip BUILD HANDOFF generation. Selected tasks are assigned to the cycle without handoffs. Run `handoff_generate` after to create handoffs separately. Reduces planner cognitive load for large backlogs."
@@ -14189,7 +14305,7 @@ function formatPlanResult(result) {
   }
   return response;
 }
-async function handlePlan(adapter2, config2, args) {
+async function handlePlan(adapter2, config2, args, clientName) {
   const toolMode = args.mode;
   const callerKey = callerKeyFromConfig(config2);
   const filters = {};
@@ -14199,7 +14315,8 @@ async function handlePlan(adapter2, config2, args) {
   if (typeof args.priority === "string") filters.priority = args.priority;
   const focus = typeof args.focus === "string" ? args.focus : void 0;
   const force = args.force === true;
-  const handoffsOnly = args.handoffs_only === true;
+  const taskIds = Array.isArray(args.task_ids) ? args.task_ids.filter((v) => typeof v === "string" && v.trim().length > 0).map((v) => v.trim()) : void 0;
+  const handoffsOnly = args.handoffs_only === true || taskIds !== void 0 && taskIds.length > 0;
   const density = args.density === "light" || args.density === "standard" || args.density === "deep" ? args.density : void 0;
   const tracker = new ProgressTracker(toolMode === "apply" ? "apply_validate" : "prepare_validate").bindStream(adapter2, { stage: "plan" });
   try {
@@ -14281,7 +14398,7 @@ async function handlePlan(adapter2, config2, args) {
       } catch {
       }
       const skipHandoffs = args.skip_handoffs === true;
-      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density);
+      const result = await preparePlan(adapter2, config2, filters, focus, force, handoffsOnly, skipHandoffs, tracker, density, taskIds);
       const prepareState = {
         contextHashes: result.contextHashes,
         userMessage: result.userMessage,
@@ -14292,7 +14409,15 @@ async function handlePlan(adapter2, config2, args) {
       planPrepareCache.set(callerKey, prepareState);
       savePrepareSpill(adapter2.getProjectId?.(), callerKey, prepareState);
       const explicit = args.dispatch === "inline" ? false : args.dispatch === "subagent" ? true : void 0;
-      const dispatch = shouldDispatch(result.contextBytes ?? 0, explicit) ? "subagent" : "inline";
+      let dispatch = shouldDispatch(result.contextBytes ?? 0, explicit) ? "subagent" : "inline";
+      let autoRouteDowngraded = false;
+      if (dispatch === "subagent" && explicit === void 0) {
+        const harness = detectHarness(clientName);
+        if (harness.key !== "claude-code") {
+          dispatch = "inline";
+          autoRouteDowngraded = true;
+        }
+      }
       const modeLabel = result.mode === "bootstrap" ? "Bootstrap" : "Full";
       const header = result.strategyReviewWarning ? `${result.strategyReviewWarning}
 ` : "";
@@ -14328,7 +14453,12 @@ ${result.userMessage}
         const dispatchHeader = result.strategyReviewWarning ? `${result.strategyReviewWarning}
 
 ` : "";
-        return { ...textResponse(`${dispatchHeader}${dispatchPrompt}`), _contextBytes: result.contextBytes };
+        const inlineOverride = `
+
+---
+
+> **No sub-agent or \`Task\` primitive in your client?** Re-call \`plan\` with \`dispatch: "inline"\` to get the planning prompt back directly, then run it yourself in a fresh context and pass the output to the apply call. The apply contract is identical either way.`;
+        return { ...textResponse(`${dispatchHeader}${dispatchPrompt}${inlineOverride}`), _contextBytes: result.contextBytes };
       }
       if (contextFilePath) {
         const kb = result.contextBytes !== void 0 ? ` (~${(result.contextBytes / 1024).toFixed(0)} KB)` : "";
@@ -14350,8 +14480,11 @@ The full planning brief \u2014 system prompt + all context${kb} \u2014 has been
         );
         return { ...pathResponse, _contextBytes: result.contextBytes };
       }
+      const downgradeNote = autoRouteDowngraded ? `> This context is large. It is returned inline because your client has no \`Task\` sub-agent primitive. If your client CAN run a sub-agent, re-call \`plan\` with \`dispatch: "subagent"\`.
+
+` : "";
       const response = textResponse(
-        `${header}## PAPI Cycle Plan \u2014 Prepare Phase (${modeLabel} Mode, Cycle ${result.cycleNumber + 1})
+        `${header}${downgradeNote}## PAPI Cycle Plan \u2014 Prepare Phase (${modeLabel} Mode, Cycle ${result.cycleNumber + 1})
 
 Follow the system prompt and context below to generate a complete cycle plan.
 
@@ -17103,6 +17236,9 @@ function buildStrategyReviewPostDirective(cycleNumber) {
   ].join("\n");
 }
 var reviewPrepareCache = new PerCallerCache();
+function hasPendingStrategyReview() {
+  return reviewPrepareCache.size() > 0;
+}
 var strategyReviewTool = {
   name: "strategy_review",
   description: 'Run a Strategy Review \u2014 assesses project direction, velocity, and Active Decisions. Produces recommendations and potential AD updates that feed into the next plan. Offered every 5 cycles; hard-blocked at 7+ overdue cycles. Run it in your current conversation \u2014 only start a fresh one if you are genuinely under context pressure (your host just compacted, you are near the context limit, or the session is heavy with build context), not just because a review is next. First call returns a review prompt for you to execute (prepare phase). Then call again with mode "apply" and your output. Pass `force: true` to run before the cadence gate.',
@@ -17557,6 +17693,7 @@ ${result.userMessage}
 }
 
 // src/lib/task-readiness.ts
+var ADVISORY_GAP_LABELS = /* @__PURE__ */ new Set(["WHY NOW", "FILES LIKELY TOUCHED"]);
 function hasMeaningfulEntry(value) {
   return Array.isArray(value) && value.some((entry) => {
     if (typeof entry === "string") return entry.trim().length > 0;
@@ -17576,23 +17713,29 @@ function getHandoffGaps(handoff) {
   return gaps;
 }
 function getTaskReadiness(task, currentCycle2) {
-  const handoffGaps = getHandoffGaps(task.buildHandoff);
-  const handoffComplete = handoffGaps.length === 0;
+  const allGaps = getHandoffGaps(task.buildHandoff);
+  const blockingGaps = allGaps.filter((g) => !ADVISORY_GAP_LABELS.has(g));
+  const advisoryGaps = allGaps.filter((g) => ADVISORY_GAP_LABELS.has(g));
+  const handoffGaps = [...blockingGaps, ...advisoryGaps];
+  const handoffComplete = blockingGaps.length === 0;
+  const advisoryNote = advisoryGaps.length > 0 ? ` A planner should still fill ${advisoryGaps.join(", ")}, but it does not block the build.` : "";
   const cycleMismatch = currentCycle2 != null && currentCycle2 > 0 && task.cycle !== currentCycle2;
   if (task.status === "Backlog") {
     if (!handoffComplete) {
       return {
         label: "Needs Planning",
-        reason: `No complete BUILD HANDOFF (${handoffGaps.join(", ")}). Run plan before claiming or building this task.`,
+        reason: `No complete BUILD HANDOFF (${blockingGaps.join(", ")}). Run plan before claiming or building this task.`,
         handoffComplete,
-        handoffGaps
+        handoffGaps,
+        advisoryGaps
       };
     }
     return {
       label: "Needs Planning",
       reason: "Backlog work is waiting for a planning pass to assign it to a cycle before it can be built.",
       handoffComplete,
-      handoffGaps
+      handoffGaps,
+      advisoryGaps
     };
   }
   if (task.status === "In Cycle" || task.status === "Ready") {
@@ -17601,22 +17744,25 @@ function getTaskReadiness(task, currentCycle2) {
         label: "Needs Planning",
         reason: `Assigned to Cycle ${task.cycle ?? "an earlier cycle"}, not the active Cycle ${currentCycle2}. Run plan before building it.`,
         handoffComplete,
-        handoffGaps
+        handoffGaps,
+        advisoryGaps
       };
     }
     if (!handoffComplete) {
       return {
         label: "Needs Planning",
-        reason: `Planning has not produced a complete BUILD HANDOFF (${handoffGaps.join(", ")}).`,
+        reason: `Planning has not produced a complete BUILD HANDOFF (${blockingGaps.join(", ")}).`,
         handoffComplete,
-        handoffGaps
+        handoffGaps,
+        advisoryGaps
       };
     }
     return {
       label: "Ready to Build",
-      reason: "Task is assigned to the active cycle and has a complete BUILD HANDOFF.",
+      reason: `Task is assigned to the active cycle and has a complete BUILD HANDOFF.${advisoryNote}`,
       handoffComplete,
-      handoffGaps
+      handoffGaps,
+      advisoryGaps
     };
   }
   const labelByStatus = {
@@ -17632,7 +17778,8 @@ function getTaskReadiness(task, currentCycle2) {
     label,
     reason: label === "Needs Planning" ? "Task is not in a buildable lifecycle state." : `Task status is ${task.status}.`,
     handoffComplete,
-    handoffGaps
+    handoffGaps,
+    advisoryGaps
   };
 }
 
@@ -18243,6 +18390,20 @@ async function handleBoardView(adapter2, args) {
     fields,
     membership.isMultiMember ? assigneeColumn(membership.nameOf) : null
   );
+  if (typeof args.cycle === "number") {
+    try {
+      const cycleRows = await adapter2.readCycles();
+      const row = cycleRows.find((c) => c.number === args.cycle);
+      const listed = row?.taskIds?.length ?? 0;
+      const carrying = result.tasks.filter((t) => t.cycle === args.cycle).length;
+      if (row && listed > 0 && listed !== carrying) {
+        output += `
+
+> \u26A0\uFE0F Cycle ${args.cycle} membership disagrees: the cycle row lists ${listed} task(s) but ${carrying} carry cycle=${args.cycle}. This view shows the latter. Run \`board_reconcile\` to realign them.`;
+      }
+    } catch {
+    }
+  }
   if (!fields) {
     try {
       const comments = await adapter2.getRecentTaskComments?.(30);
@@ -20962,37 +21123,6 @@ function pendingDecisionBlocker(attempts, cycle, taskId) {
   };
 }
 
-// src/lib/harness-capability.ts
-var HARNESS_REGISTRY = {
-  // Local stdio CLI agents — PAPI runs git on the user's machine. Confirmed in telemetry.
-  "claude-code": { build: true, label: "Claude Code" },
-  "opencode": { build: true, label: "opencode" },
-  "zcode": { build: true, label: "zcode" },
-  "codex": { build: true, label: "Codex" },
-  "cursor": { build: true, label: "Cursor" },
-  // Cloud harnesses with code sandboxes — their agent builds in-sandbox over HTTP+OAuth.
-  "lovable": { build: true, label: "Lovable" },
-  "bolt": { build: true, label: "Bolt" },
-  "replit": { build: true, label: "Replit" },
-  // Chat-only surfaces, no sandbox — planning only.
-  "chatgpt": { build: false, label: "ChatGPT" },
-  "claude.ai": { build: false, label: "Claude.ai" },
-  "claude-desktop": { build: false, label: "Claude Desktop" }
-};
-var UNKNOWN_DEFAULT = { build: false, label: "your tool" };
-function detectHarness(clientName) {
-  const raw = clientName?.trim() || null;
-  if (!raw) {
-    return { ...UNKNOWN_DEFAULT, raw: null, key: null, known: false };
-  }
-  const norm = raw.toLowerCase();
-  const key = HARNESS_REGISTRY[norm] ? norm : Object.keys(HARNESS_REGISTRY).find((k) => norm.includes(k)) ?? null;
-  if (!key) {
-    return { ...UNKNOWN_DEFAULT, label: raw, raw, key: null, known: false };
-  }
-  return { ...HARNESS_REGISTRY[key], raw, key, known: true };
-}
-
 // src/lib/harness-build-steps.ts
 init_git();
 function startBuildSteps(branch, base, taskId) {
@@ -25566,6 +25696,9 @@ init_git();
 
 // src/tools/handoff.ts
 var handoffPrepareCache = new PerCallerCache();
+function hasPendingHandoffGenerate() {
+  return handoffPrepareCache.size() > 0;
+}
 var handoffGenerateTool = {
   name: "handoff_generate",
   description: "Generate BUILD HANDOFFs for cycle tasks that don't have one yet. Run after `plan` (with skip_handoffs=true) or to regenerate stale handoffs. Uses the prepare/apply pattern \u2014 first call returns a prompt, second call persists results.",
@@ -31770,10 +31903,14 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
       lines.push("Board is empty \u2014 run `plan` to create your next cycle.");
     }
     lines.push("");
+    lines.push(WORK_DUMP_ROUTING_RULE);
+    lines.push("");
   } else if (buildInfo.noHandoffs) {
     lines.push("## Tasks");
     lines.push("No tasks with BUILD HANDOFFs \u2014 run `plan` to generate cycle tasks.");
     lines.push("");
+    lines.push(WORK_DUMP_ROUTING_RULE);
+    lines.push("");
   } else {
     lines.push(`## Tasks with Handoffs`);
     lines.push(`${buildInfo.totalHandoffs} total \u2014 ${buildInfo.inProgress.length} in progress, ${buildInfo.backlogCount} backlog, ${buildInfo.blockedCount} blocked`);
@@ -31804,6 +31941,7 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
   return lines.join("\n").trimEnd();
 }
 var NOT_SET_UP_MESSAGE = "Setup required \u2014 this project has no PAPI state yet. That is the normal starting point, not an error. Run `setup` to generate your Product Brief and scaffold the workflow, then `plan` to create your first cycle.";
+var WORK_DUMP_ROUTING_RULE = '_If someone hands you a list of work (an audit, a bug list, "build all of these"), do NOT start writing code. File each item with `idea`, then run `plan` to scope a cycle \u2014 that is how work gets a spec, a branch and a review._';
 function emptyHealthSummary() {
   return {
     cycleNumber: 0,
@@ -32159,12 +32297,34 @@ async function handleOrient(rawAdapter, config2, args = {}, clientName, serverVe
       cycleSince: currentCycle2,
       compact: true
     }).catch(() => []) : [];
-    const cycleTasksAll = scopeTasksToCaller(cycleTasksAllRaw, callerUserId);
-    const cycleCounts = computeCycleTaskCounts(cycleTasksAll, currentCycle2, cycleIsComplete);
+    const cycleCounts = computeCycleTaskCounts(cycleTasksAllRaw, currentCycle2, cycleIsComplete);
     const { inProgress: cycleInProgress, inReview: cycleInReview, inCycle: cycleInCycle, ready: cycleReady, backlog: cycleBacklog, total: cycleTotal, done: cycleDone } = cycleCounts;
     if (!cycleIsComplete && cycleTotal === 0 && cycleDone > 0) {
       buildResult.warnings.unshift(`\u26A0\uFE0F Cycle ${currentCycle2} is complete \u2014 all ${cycleDone} task${cycleDone !== 1 ? "s" : ""} Done. Release has not been run. Run \`release\` now (or \`release\` with \`skipVersion=true\` to close the cycle without a git tag).`);
     }
+    if (!cycleIsComplete && currentCycle2 > 0) {
+      try {
+        const cyclesForPhantom = await adapter2.readCycles();
+        const mine = cyclesForPhantom.filter(
+          (c) => c.number === currentCycle2 && (!callerUserId || c.userId == null || c.userId === callerUserId)
+        );
+        const phantom = mine.find((c) => c.status === "active" && (c.goals?.length ?? 0) === 0);
+        if (phantom) {
+          buildResult.warnings.unshift(
+            `\u26A0\uFE0F Cycle ${currentCycle2} has no goals and looks like a plan that didn't finish writing. Run \`plan\` again \u2014 it will replace this incomplete cycle rather than stacking a new one on top. No data is lost: nothing has been built in it.`
+          );
+        }
+        const cycleRow = mine.find((c) => c.status === "active") ?? mine[0];
+        const taskIdMembership = cycleRow?.taskIds?.length ?? 0;
+        const columnMembership = cycleTasksAllRaw.filter((t) => t.cycle === currentCycle2).length;
+        if (cycleRow && taskIdMembership !== columnMembership && taskIdMembership > 0) {
+          buildResult.warnings.unshift(
+            `\u26A0\uFE0F Cycle ${currentCycle2} membership disagrees: the cycle row lists ${taskIdMembership} task(s) but ${columnMembership} task(s) actually carry cycle=${currentCycle2}. Some cycle tasks may not show on \`board_view cycle=${currentCycle2}\` or the hub. Run \`board_reconcile\` to realign them.`
+          );
+        }
+      } catch {
+      }
+    }
     tracker.mark("parallel-reads");
     const inProgressItems = buildResult.inProgress.map(
       (t) => `- **${t.id}:** ${t.title} (${t.priority} | ${t.complexity})`
@@ -32781,23 +32941,23 @@ ${formatRuntimeIdentity(getRuntimeIdentity(config2, serverVersion))}`;
   }
 }
 function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, clientName) {
-  if (!shouldWriteClaudeMd(clientName)) return "";
+  const targetFile = shouldWriteClaudeMd(clientName) ? "CLAUDE.md" : "AGENTS.md";
   if (adapterType === "proxy") {
     const additions2 = [];
     if (cycleNumber >= 6) additions2.push(CLAUDE_MD_TIER_1);
     if (cycleNumber >= 21) additions2.push(CLAUDE_MD_TIER_2);
     if (additions2.length === 0) return "";
-    collector.add({ path: "CLAUDE.md", content: additions2.join(""), mode: "append" });
+    collector.add({ path: targetFile, content: additions2.join(""), mode: "append" });
     const tierNames2 = [];
     if (cycleNumber >= 6) tierNames2.push("Established (batch building, strategy reviews, AD lifecycle)");
     if (cycleNumber >= 21) tierNames2.push("Mature (idea pipeline, doc registry, advanced patterns)");
     return `
 
-\u{1F4DD} **CLAUDE.md enriched** \u2014 added ${tierNames2.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
+\u{1F4DD} **${targetFile} enriched** \u2014 added ${tierNames2.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
   }
-  const claudeMdPath = join18(projectRoot, "CLAUDE.md");
-  if (!existsSync11(claudeMdPath)) return "";
-  const content = readFileSync13(claudeMdPath, "utf-8");
+  const targetPath = join18(projectRoot, targetFile);
+  if (!existsSync11(targetPath)) return "";
+  const content = readFileSync13(targetPath, "utf-8");
   const additions = [];
   if (cycleNumber >= 6 && !content.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1)) {
     additions.push(dedupeEnrichmentBlob(content, CLAUDE_MD_TIER_1));
@@ -32806,13 +32966,13 @@ function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector, client
     additions.push(dedupeEnrichmentBlob(content, CLAUDE_MD_TIER_2));
   }
   if (additions.length === 0) return "";
-  writeFileSync7(claudeMdPath, content + additions.join(""), "utf-8");
+  writeFileSync7(targetPath, content + additions.join(""), "utf-8");
   const tierNames = [];
   if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T1))) tierNames.push("Established (batch building, strategy reviews, AD lifecycle)");
   if (additions.some((a) => a.includes(CLAUDE_MD_ENRICHMENT_SENTINEL_T2))) tierNames.push("Mature (idea pipeline, doc registry, advanced patterns)");
   return `
 
-\u{1F4DD} **CLAUDE.md enriched** \u2014 added ${tierNames.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
+\u{1F4DD} **${targetFile} enriched** \u2014 added ${tierNames.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
 }
 
 // src/tools/hierarchy.ts
@@ -35560,6 +35720,9 @@ var PAPI_TOOLS = [
 function getQualifiedPapiTools() {
   return qualifyTools(PAPI_TOOLS);
 }
+function hasPendingStdioPrepare() {
+  return hasPendingPlanPrepare() || hasPendingStrategyReview() || hasPendingHandoffGenerate();
+}
 function getToolMetadata() {
   return PAPI_TOOLS.map((t) => ({ name: t.name, description: t.description }));
 }
@@ -35684,7 +35847,7 @@ function createServer(adapter2, config2, observation) {
     const runHandler = async () => {
       switch (name) {
         case "plan":
-          return handlePlan(scopedAdapter, scopedConfig, safeArgs);
+          return handlePlan(scopedAdapter, scopedConfig, safeArgs, server2.getClientVersion()?.name);
         case "strategy_review":
           return handleStrategyReview(scopedAdapter, scopedConfig, safeArgs);
         case "strategy_change":
@@ -36454,11 +36617,36 @@ function startHttpTransport(opts) {
         }
         try {
           parsedBody = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
-          observation?.setTool(extractToolName(parsedBody) ?? extractRpcMethod(parsedBody));
         } catch {
           sendError(res, { status: 400, body: { error: "Invalid JSON body" } });
           return;
         }
+        if (Array.isArray(parsedBody)) {
+          logEvent({
+            level: "warn",
+            msg: "jsonrpc_batch_rejected",
+            ip,
+            bearer_prefix: bearerPrefix(bearer),
+            status: 400
+          });
+          if (!res.headersSent) {
+            res.writeHead(400, {
+              "Content-Type": "application/json",
+              "CDN-Cache-Control": "private, no-store",
+              "Vercel-CDN-Cache-Control": "private, no-store"
+            });
+            res.end(JSON.stringify({
+              jsonrpc: "2.0",
+              id: null,
+              error: {
+                code: -32600,
+                message: "JSON-RPC batch requests are not supported. Send each tool call as its own HTTP request."
+              }
+            }));
+          }
+          return;
+        }
+        observation?.setTool(extractToolName(parsedBody) ?? extractRpcMethod(parsedBody));
       }
       logEvent({
         level: "info",
@@ -36707,6 +36895,56 @@ function shouldCheckForUpdate(version, selfHostFlag) {
   return version !== "unknown" && !isSelfHostedDeployment(selfHostFlag);
 }
 
+// src/lib/stdio-idle-timeout.ts
+var DEFAULT_STDIO_IDLE_TIMEOUT_MS = 12e4;
+var DEFAULT_STDIO_PENDING_GRACE_MS = 15 * 6e4;
+function parseStdioIdleTimeoutMs(raw = process.env["PAPI_STDIO_IDLE_TIMEOUT_MS"]) {
+  if (raw === void 0 || raw.trim() === "") return DEFAULT_STDIO_IDLE_TIMEOUT_MS;
+  const timeoutMs = Number(raw);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+    throw new Error(
+      `PAPI_STDIO_IDLE_TIMEOUT_MS must be a non-negative integer in milliseconds; received ${JSON.stringify(raw)}`
+    );
+  }
+  return timeoutMs;
+}
+function startStdioIdleTimeout(input, timeoutMs, onTimeout, isIdle = () => true) {
+  if (timeoutMs === 0) return () => void 0;
+  let timer2;
+  let stopped = false;
+  let pendingSince;
+  const schedule = () => {
+    timer2 = setTimeout(() => {
+      if (stopped) return;
+      if (!isIdle()) {
+        pendingSince ??= Date.now();
+        if (Date.now() - pendingSince < DEFAULT_STDIO_PENDING_GRACE_MS) {
+          schedule();
+          return;
+        }
+      }
+      stopped = true;
+      input.off("data", refresh);
+      onTimeout();
+    }, timeoutMs);
+  };
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer2 !== void 0) clearTimeout(timer2);
+    input.off("data", refresh);
+  };
+  const refresh = () => {
+    if (stopped) return;
+    if (timer2 !== void 0) clearTimeout(timer2);
+    pendingSince = void 0;
+    schedule();
+  };
+  input.on("data", refresh);
+  refresh();
+  return stop;
+}
+
 // src/index.ts
 init_dist();
 var __dirname = dirname7(fileURLToPath5(import.meta.url));
@@ -36808,7 +37046,7 @@ async function gracefulShutdown(signal) {
   } catch (err) {
     console.error(`[papi] Adapter close failed during ${signal}: ${err instanceof Error ? err.message : String(err)}`);
   }
-  process.exit(signal === "SIGTERM" || signal === "SIGINT" ? 0 : 1);
+  process.exit(signal === "SIGTERM" || signal === "SIGINT" || signal === "idle-timeout" ? 0 : 1);
 }
 process.on("SIGTERM", () => {
   void gracefulShutdown("SIGTERM");
@@ -36922,13 +37160,23 @@ if (isHttpMode && httpPort !== void 0) {
   } catch {
   }
   const transport = new StdioServerTransport();
+  let stopStdioIdleTimeout = () => void 0;
+  transport.onclose = () => stopStdioIdleTimeout();
   await server.connect(transport);
+  stopStdioIdleTimeout = startStdioIdleTimeout(
+    process.stdin,
+    parseStdioIdleTimeoutMs(),
+    () => {
+      void gracefulShutdown("idle-timeout");
+    },
+    () => !hasPendingStdioPrepare()
+  );
   process.stderr.write(`${formatConnectionBanner({
     serverName: config.serverName,
     projectName: basename2(config.projectRoot),
     projectId: config.projectId ?? process.env.PAPI_PROJECT_ID,
     adapterType: config.adapterType,
     pkgVersion
-  })}
+  }, getConnectionStatus())}
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.108",
+  "version": "0.7.113",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",