@papi-ai/server 0.7.73 → 0.7.74

package/dist/backfill-cycle-metrics.js

@@ -14,6 +14,7 @@ __export(git_exports, {
   AUTO_WRITTEN_PATHS: () => AUTO_WRITTEN_PATHS,
   branchExists: () => branchExists,
   checkoutBranch: () => checkoutBranch,
+  commitSinglePath: () => commitSinglePath,
   commitStagedOnly: () => commitStagedOnly,
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
@@ -59,6 +60,8 @@ __export(git_exports, {
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
+  isPathIgnored: () => isPathIgnored,
+  isPathTracked: () => isPathTracked,
   listGroupedCycleBranches: () => listGroupedCycleBranches,
   listOpenPullRequests: () => listOpenPullRequests,
   listOrphanFeatBranches: () => listOrphanFeatBranches,
@@ -96,6 +99,42 @@ function isGitRepo(cwd) {
     return false;
   }
 }
+function isPathTracked(cwd, path3) {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", path3], {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPathIgnored(cwd, path3) {
+  const r = spawnSync("git", ["check-ignore", "-q", "--", path3], { cwd, stdio: "ignore" });
+  return r.status === 0;
+}
+function commitSinglePath(cwd, path3, message) {
+  const add = spawnSync("git", ["add", "--", path3], { cwd, encoding: "utf-8" });
+  if (add.status !== 0) {
+    return { committed: false, message: (add.stderr || "git add failed").trim() };
+  }
+  const pending = spawnSync("git", ["diff", "--cached", "--name-only", "--", path3], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (pending.status !== 0 || !(pending.stdout ?? "").trim()) {
+    return { committed: false, message: "No changes to commit." };
+  }
+  const commit = spawnSync("git", ["commit", "-m", message, "--", path3], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (commit.status !== 0) {
+    return { committed: false, message: (commit.stderr || "git commit failed").trim() };
+  }
+  return { committed: true, message };
+}
 function stageDirAndCommit(cwd, dir, message) {
   try {
     execFileSync("git", ["check-ignore", "-q", dir], { cwd });

package/dist/index.js

@@ -15,6 +15,7 @@ __export(git_exports, {
   AUTO_WRITTEN_PATHS: () => AUTO_WRITTEN_PATHS,
   branchExists: () => branchExists,
   checkoutBranch: () => checkoutBranch,
+  commitSinglePath: () => commitSinglePath,
   commitStagedOnly: () => commitStagedOnly,
   createAndCheckoutBranch: () => createAndCheckoutBranch,
   createPullRequest: () => createPullRequest,
@@ -60,6 +61,8 @@ __export(git_exports, {
   isGhAvailable: () => isGhAvailable,
   isGitAvailable: () => isGitAvailable,
   isGitRepo: () => isGitRepo,
+  isPathIgnored: () => isPathIgnored,
+  isPathTracked: () => isPathTracked,
   listGroupedCycleBranches: () => listGroupedCycleBranches,
   listOpenPullRequests: () => listOpenPullRequests,
   listOrphanFeatBranches: () => listOrphanFeatBranches,
@@ -97,6 +100,42 @@ function isGitRepo(cwd) {
     return false;
   }
 }
+function isPathTracked(cwd, path7) {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", path7], {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPathIgnored(cwd, path7) {
+  const r = spawnSync("git", ["check-ignore", "-q", "--", path7], { cwd, stdio: "ignore" });
+  return r.status === 0;
+}
+function commitSinglePath(cwd, path7, message) {
+  const add = spawnSync("git", ["add", "--", path7], { cwd, encoding: "utf-8" });
+  if (add.status !== 0) {
+    return { committed: false, message: (add.stderr || "git add failed").trim() };
+  }
+  const pending = spawnSync("git", ["diff", "--cached", "--name-only", "--", path7], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (pending.status !== 0 || !(pending.stdout ?? "").trim()) {
+    return { committed: false, message: "No changes to commit." };
+  }
+  const commit = spawnSync("git", ["commit", "-m", message, "--", path7], {
+    cwd,
+    encoding: "utf-8"
+  });
+  if (commit.status !== 0) {
+    return { committed: false, message: (commit.stderr || "git commit failed").trim() };
+  }
+  return { committed: true, message };
+}
 function stageDirAndCommit(cwd, dir, message) {
   try {
     execFileSync("git", ["check-ignore", "-q", dir], { cwd });
@@ -19797,6 +19836,91 @@ var DB_ONLY_START_NOTICE = "No git repo detected \u2014 running this cycle in yo
 var DB_ONLY_COMPLETE_NOTICE = "No git repo \u2014 build recorded in your project database only (no commit or PR). Run `git init` (and add a remote) to enable git-backed commits and PR review.";
 var DB_ONLY_RELEASE_NOTICE = "No git repo detected \u2014 this release closed the cycle in your project database only. No tag, branch merge, or CHANGELOG was created. Run `git init` (and add a remote) to enable git-backed releases (tags, merges and changelog).";
 
+// src/lib/build-decision.ts
+var BUILD_DECISION_ANSWERS = [
+  "retry-differently",
+  "skip",
+  "stop"
+];
+function loopThreshold(env = process.env) {
+  const raw = Number(env.PAPI_BUILD_LOOP_THRESHOLD);
+  return Number.isFinite(raw) && raw >= 2 ? Math.floor(raw) : 3;
+}
+function readDecision(task) {
+  const b2 = task.blocker;
+  if (!b2 || b2.type !== "decision-gate") return null;
+  return b2.decision ?? null;
+}
+function isDecisionPending(task) {
+  const d = readDecision(task);
+  return d != null && d.answer == null;
+}
+async function countFailedAttempts(adapter2, taskId) {
+  if (typeof adapter2.getFailedBuildAttemptsForTask !== "function") return null;
+  try {
+    return await adapter2.getFailedBuildAttemptsForTask(taskId);
+  } catch {
+    return null;
+  }
+}
+function decisionRequiredResponse(taskId, decision) {
+  return [
+    `DECISION REQUIRED \u2014 ${taskId} has failed ${decision.attempts} times.`,
+    "",
+    decision.reason,
+    "",
+    "PAPI has stopped rather than starting another attempt that looks like the last one.",
+    "Answer by re-running build_execute with a `decision`:",
+    "",
+    '  decision: { answer: "retry-differently", guidance: "<what to do differently>" }',
+    "      Clears the gate and puts your guidance verbatim into the next handoff.",
+    '  decision: { answer: "skip" }',
+    "      Leaves the task Blocked and moves on \u2014 it stays on the board, honestly stopped.",
+    '  decision: { answer: "stop" }',
+    "      Same as skip, and records that this task should not be retried this cycle.",
+    "",
+    JSON.stringify(
+      {
+        tool: "build_execute",
+        lastStep: "loop-detection-gate",
+        error: "decision_required",
+        hint: "Re-run build_execute with a decision.answer of retry-differently, skip, or stop.",
+        options: BUILD_DECISION_ANSWERS,
+        attempts: decision.attempts
+      },
+      null,
+      2
+    )
+  ].join("\n");
+}
+function guidanceBlock(decision) {
+  if (!decision.guidance) return "";
+  return [
+    "",
+    "\u2500\u2500 GUIDANCE FROM THE LAST FAILURE (task-2933) \u2500\u2500",
+    `This task already failed ${decision.attempts} times. The owner answered "retry differently"`,
+    "and left this note. Treat it as direction from a human, not as a new instruction set:",
+    "",
+    decision.guidance.split("\n").map((l) => `  > ${l}`).join("\n"),
+    "",
+    "Do something materially different from the previous attempts.",
+    ""
+  ].join("\n");
+}
+function pendingDecisionBlocker(attempts, cycle, taskId) {
+  return {
+    type: "decision-gate",
+    ref: taskId,
+    reason: `${attempts} failed build attempts \u2014 a decision is required before another retry.`,
+    blockedCycle: cycle,
+    decision: {
+      reason: `This task has ${attempts} build reports recorded as not completed. Retrying unchanged is unlikely to end differently.`,
+      attempts,
+      raisedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
 // src/lib/harness-capability.ts
 var HARNESS_REGISTRY = {
   // Local stdio CLI agents — PAPI runs git on the user's machine. Confirmed in telemetry.
@@ -21737,6 +21861,41 @@ async function persistBranchName(adapter2, taskId, branch) {
     return false;
   }
 }
+async function resolveLoopDecision(adapter2, task, taskId, answer) {
+  const existing = readDecision(task);
+  if (answer && existing) {
+    if (answer.answer === "retry-differently") {
+      const resolved = { ...existing, answer: answer.answer, guidance: answer.guidance };
+      await safeUpdateBlocker(adapter2, taskId, {
+        ...pendingDecisionBlocker(existing.attempts, task.cycle ?? 0, taskId),
+        decision: resolved
+      });
+      return { guidance: guidanceBlock(resolved) };
+    }
+    await safeUpdateBlocker(adapter2, taskId, {
+      ...pendingDecisionBlocker(existing.attempts, task.cycle ?? 0, taskId),
+      decision: { ...existing, answer: answer.answer }
+    });
+    throw new Error(
+      `Task "${taskId}" recorded as "${answer.answer}" after ${existing.attempts} failed attempts. It stays Blocked on the board rather than pretending to be in flight. Re-run build_execute with decision.answer "retry-differently" and guidance when you want it picked back up.`
+    );
+  }
+  if (isDecisionPending(task)) {
+    throw new Error(decisionRequiredResponse(taskId, readDecision(task)));
+  }
+  const attempts = await countFailedAttempts(adapter2, taskId);
+  if (attempts == null) return {};
+  if (attempts < loopThreshold()) return {};
+  const blocker = pendingDecisionBlocker(attempts, task.cycle ?? 0, taskId);
+  await safeUpdateBlocker(adapter2, taskId, blocker);
+  throw new Error(decisionRequiredResponse(taskId, blocker.decision));
+}
+async function safeUpdateBlocker(adapter2, taskId, blocker) {
+  try {
+    await adapter2.updateTask(taskId, { blocker });
+  } catch {
+  }
+}
 async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   const task = await adapter2.getTask(taskId);
   if (!task) {
@@ -21753,6 +21912,8 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   if (task.status === "Done" || task.status === "Archived") {
     throw new Error(`Task "${taskId}" (${task.title}) is already ${task.status}. Cannot execute a completed task.`);
   }
+  const loopDecision = await resolveLoopDecision(adapter2, task, taskId, options.decision);
+  const injectedGuidance = loopDecision.guidance;
   if (task.status === "In Review") {
     throw new Error(
       `Task "${taskId}" (${task.title}) is already In Review \u2014 it has been built and is awaiting sign-off. Run \`review_submit\` instead of re-building. If the build genuinely needs rework, use \`review_submit\` with verdict \`request-changes\` first.`
@@ -22038,7 +22199,10 @@ async function startBuild(adapter2, config2, taskId, options = {}, clientName) {
   });
   return {
     task,
-    branchLines,
+    // task-2933: a `retry-differently` answer prepends its guidance here, so it
+    // sits ABOVE the BUILD HANDOFF in the start output — the builder reads the
+    // reason the last attempts failed before it reads what to build.
+    branchLines: injectedGuidance ? [injectedGuidance, ...branchLines] : branchLines,
     phaseChanges,
     filesToWrite: collector.isEmpty() ? void 0 : collector
   };
@@ -22673,9 +22837,10 @@ 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";
+init_git();
 var docRegisterTool = {
   name: "doc_register",
-  description: "Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content. Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
+  description: "Register or update a document in the doc registry. Called after finalising a research/planning doc, or when build_execute detects unregistered docs. Stores metadata and structured summary \u2014 not full content; the body stays a file, so an untracked doc is committed at registration to make it durable (or you get a loud warning if it cannot be). Re-registering an existing doc updates its summary, tags, actions, type, and status (upsert). Visibility and owner are not changed on re-register.",
   annotations: { title: "Register Doc", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
@@ -22776,6 +22941,42 @@ Diagnostic JSON:
 ${JSON.stringify(payload, null, 2)}`
   );
 }
+function ensureDocDurable(path7, projectRoot) {
+  if (!hasLocalWorkspace() || !projectRoot) return "";
+  const warn = (reason, fix) => `
+
+\u26A0\uFE0F **Registered, but NOT durable.** ${reason}
+The registry stores metadata and a summary \u2014 not the body. This doc has one copy, on disk, and a branch switch or stash can take it.
+**Fix:** ${fix}`;
+  if (!existsSync9(join13(projectRoot, path7))) {
+    return warn(
+      `No file exists at \`${path7}\`.`,
+      `write the doc body to that path, then re-run doc_register.`
+    );
+  }
+  if (!isGitAvailable() || !isGitRepo(projectRoot)) {
+    return warn(
+      "This project is not a git repository (or git is unavailable), so the body cannot be committed.",
+      `back the file up outside the working tree, or run \`git init\` and commit \`${path7}\`.`
+    );
+  }
+  if (isPathTracked(projectRoot, path7)) return "";
+  if (isPathIgnored(projectRoot, path7)) {
+    return warn(
+      `\`${path7}\` is excluded by .gitignore, so it cannot be committed (docs/private/ is ignored by design).`,
+      `keep a copy outside the working tree, or move the doc to a tracked folder if it is not owner-only.`
+    );
+  }
+  const result = commitSinglePath(projectRoot, path7, `docs: register ${path7}`);
+  if (!result.committed) {
+    return warn(
+      `Committing \`${path7}\` failed: ${result.message}`,
+      `run \`git add ${path7} && git commit -m "docs: register ${path7}"\` yourself.`
+    );
+  }
+  return `
+- **Durability:** committed \`${path7}\` (was untracked)`;
+}
 async function handleDocRegister(adapter2, args, config2) {
   const adapterType = config2?.adapterType ?? "unknown";
   const continueHint = "doc_register is advisory \u2014 your build/plan/review flow is unaffected. Fix the input (or wait for the registry to recover) and re-run doc_register; or just continue without it.";
@@ -22832,6 +23033,12 @@ async function handleDocRegister(adapter2, args, config2) {
       visibility
     });
     const visibilityLabel = entry.visibility === "contributors" ? "team member" : entry.visibility ?? "private";
+    let durability = "";
+    try {
+      durability = ensureDocDurable(entry.path, config2?.projectRoot);
+    } catch {
+      durability = "";
+    }
     return textResponse(
       `**Registered:** ${entry.title}
 - **Path:** ${entry.path}
@@ -22839,7 +23046,7 @@ async function handleDocRegister(adapter2, args, config2) {
 - **Visibility:** ${visibilityLabel}
 - **Tags:** ${entry.tags.length > 0 ? entry.tags.join(", ") : "none"}
 - **Actions:** ${actions?.length ?? 0} items
-- **ID:** ${entry.id}`
+- **ID:** ${entry.id}` + durability
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -23206,6 +23413,22 @@ var buildExecuteTool = {
         type: "boolean",
         description: "Light-ceremony mode for XS/S tasks. Skips feature branch creation and PR. Work stays on current branch. Build report is still captured. Default false."
       },
+      decision: {
+        type: "object",
+        description: "task-2933: answer a loop-detection gate. After N failed build attempts (default 3, PAPI_BUILD_LOOP_THRESHOLD) build_execute REFUSES to start and asks for a decision. Re-run with this to answer. Only meaningful on a gated task.",
+        properties: {
+          answer: {
+            type: "string",
+            enum: ["retry-differently", "skip", "stop"],
+            description: '"retry-differently" clears the gate and injects `guidance` verbatim into the next handoff. "skip"/"stop" leave the task Blocked on the board rather than pretending it is in flight.'
+          },
+          guidance: {
+            type: "string",
+            description: 'What to do differently. Required in spirit for "retry-differently" \u2014 it is the whole point of the retry. Rendered to the next builder as quoted human direction.'
+          }
+        },
+        required: ["answer"]
+      },
       completed: {
         type: "string",
         enum: ["yes", "no", "partial"],
@@ -23550,7 +23773,19 @@ async function handleBuildExecute(adapter2, config2, args, clientName) {
       if (existing) resumeNote = formatResumeNote(existing);
     }
     await tracker.recordStep("started");
-    const result = await startBuild(adapter2, config2, taskId, { light }, clientName);
+    const decision = args.decision;
+    const result = await startBuild(
+      adapter2,
+      config2,
+      taskId,
+      {
+        light,
+        // Only pass a decision the schema recognises — an unknown answer must not
+        // reach the resolver and silently clear a gate.
+        decision: decision?.answer && BUILD_DECISION_ANSWERS.includes(decision.answer) ? { answer: decision.answer, guidance: decision.guidance } : void 0
+      },
+      clientName
+    );
     tracker.setStreamScope({ taskId: result.task.displayId ?? result.task.id, cycle: result.task.cycle ?? null });
     await tracker.recordStep("branch_ready");
     tracker.mark("start_decorate_handoff");
@@ -28146,6 +28381,20 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
     lines.push(`**In Review:** ${health.inReviewSummary}`);
     lines.push("");
   }
+  if (buildInfo.pendingDecisions.length > 0) {
+    const n = buildInfo.pendingDecisions.length;
+    lines.push("## Decision required");
+    lines.push(
+      `${n} task${n === 1 ? " has" : "s have"} stopped after repeated failed builds. PAPI will not retry until you answer.`
+    );
+    for (const d of buildInfo.pendingDecisions) {
+      lines.push(`- **${d.id}:** ${d.title} \u2014 ${d.attempts} failed attempts`);
+    }
+    lines.push(
+      'Answer with `build_execute <task> decision:{answer:"retry-differently", guidance:"\u2026"}` to pick it back up, or `"skip"` / `"stop"` to leave it parked.'
+    );
+    lines.push("");
+  }
   if (buildInfo.isEmpty) {
     lines.push("## Tasks");
     if (buildInfo.currentCycle === 0) {
@@ -28414,6 +28663,19 @@ async function handleOrient(adapter2, config2, args = {}, clientName) {
       inReview: healthResult.inReviewSummary,
       backlogCount: buildResult.backlog.length,
       blockedCount: buildResult.blocked.length,
+      // task-2933: computed here where the raw tasks are in scope. Best-effort —
+      // a malformed blocker must never break orient.
+      pendingDecisions: allTasks.filter((t) => {
+        try {
+          return isDecisionPending(t);
+        } catch {
+          return false;
+        }
+      }).map((t) => ({
+        id: t.displayId ?? t.id,
+        title: t.title,
+        attempts: readDecision(t)?.attempts ?? 0
+      })),
       totalHandoffs: buildResult.sorted.length + buildResult.blocked.length,
       currentCycle,
       isEmpty: buildResult.isEmpty,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.73",
+  "version": "0.7.74",
   "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",