lobstah 0.6.2 → 0.6.4

package/dist/runner.js

@@ -739,6 +739,18 @@ function parse(toml, { maxDepth = 1e3, integersAsBigInt } = {}) {
 }
 
 // packages/core/dist/config.js
+var BRIEF_KINDS = ["conflict", "checks", "review", "ciFix", "rebase"];
+function parseBriefHooks(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    return void 0;
+  const out = {};
+  for (const kind of [...BRIEF_KINDS, "all"]) {
+    const text = raw[kind];
+    if (typeof text === "string" && text.trim())
+      out[kind] = text.trim();
+  }
+  return Object.keys(out).length ? out : void 0;
+}
 var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report"];
 var DEFAULT_ATTENTION_KINDS = ["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"];
 function parseAttentionKinds(raw) {
@@ -766,7 +778,7 @@ var DEFAULT_HELM = {
   armGraceSecs: 5
 };
 var DEFAULT_GLASS = { port: 4949 };
-var DEFAULT_WATCH = { maxForksPerCycle: 3, autoRepair: true, conflicts: true, checks: true, maxRepairsPerPr: 2, repairSettleSecs: 600, repairTrapWaitSecs: 600 };
+var DEFAULT_WATCH = { maxForksPerCycle: 3, autoRepair: true, conflicts: true, checks: true, maxRepairsPerPr: 2, maxRepairsWithoutProgress: 2, repairSettleSecs: 600, repairTrapWaitSecs: 600 };
 var DEFAULT_LIMITS = {
   maxConcurrent: 2,
   choreConcurrent: 1,
@@ -809,7 +821,8 @@ function loadConfig() {
       pushEarly: r.pushEarly === void 0 ? void 0 : Boolean(r.pushEarly),
       draftPr: r.draftPr === void 0 ? void 0 : Boolean(r.draftPr),
       checkpointOnStop: r.checkpointOnStop === void 0 ? void 0 : Boolean(r.checkpointOnStop),
-      humanGateChecks: Array.isArray(r.humanGateChecks) ? r.humanGateChecks.map(String).filter(Boolean) : void 0
+      humanGateChecks: Array.isArray(r.humanGateChecks) ? r.humanGateChecks.map(String).filter(Boolean) : void 0,
+      briefHooks: parseBriefHooks(r.briefHooks)
     };
   }
   const groundsRaw = raw.grounds ?? {};
@@ -857,6 +870,26 @@ var GB = 1024 ** 3;
 // packages/core/dist/watch.js
 import * as fs3 from "node:fs";
 import * as path3 from "node:path";
+
+// packages/core/dist/gh-errors.js
+function firstMeaningfulLine(...outputs) {
+  for (const out of outputs) {
+    for (const raw of (out ?? "").split("\n")) {
+      let line = raw.trim();
+      if (!line || /^(warning:|hint:|\(node:|\{|\})/i.test(line))
+        continue;
+      const m = /^error:\s*(.*)$/.exec(line);
+      if (m)
+        line = m[1].replace(/^"(.*)"$/, "$1").trim();
+      line = line.replace(/^(gh|GraphQL):\s*/i, "");
+      if (line)
+        return line;
+    }
+  }
+  return void 0;
+}
+
+// packages/core/dist/watch.js
 function watchesDir() {
   return path3.join(lobstahHome(), "watches");
 }
@@ -1577,6 +1610,7 @@ var COMPILED_BINARY = (() => {
 })();
 
 // packages/core/dist/pr.js
+import { spawnSync } from "node:child_process";
 function parsePrRef(s) {
   const m = /^(?:pr:)?([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)#(\d+)$/.exec(s.trim()) ?? /^https?:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/(\d+)(?:[/?#].*)?$/.exec(s.trim());
   if (!m)
@@ -1587,6 +1621,59 @@ function parsePrRef(s) {
 }
 var PR_VIEW_FIELDS = "title,state,isDraft,headRefOid,baseRefName,baseRefOid,headRefName,mergeStateStatus,reviewDecision,statusCheckRollup,mergedAt,closedAt,updatedAt,reviews";
 var PR_VIEW_FIELDS_NO_CHECKS = PR_VIEW_FIELDS.split(",").filter((f) => f !== "statusCheckRollup").join(",");
+var FORBIDDEN = /resource not accessible by (integration|personal access token)/i;
+function ghPrView(ref) {
+  const view1 = (fields2) => spawnSync("gh", ["pr", "view", String(ref.number), "--repo", `${ref.owner}/${ref.repo}`, "--json", fields2], {
+    encoding: "utf8",
+    timeout: 6e4
+  });
+  const reason = (r) => firstMeaningfulLine(r.stderr) ?? `gh exited ${r.status}`;
+  const unknownBase = (r) => r.status !== 0 && /unknown json field.*baseRefOid/i.test(r.stderr ?? "");
+  const withoutBase = (fields2) => fields2.split(",").filter((f) => f !== "baseRefOid").join(",");
+  let fields = PR_VIEW_FIELDS;
+  let res = view1(fields);
+  if (unknownBase(res))
+    res = view1(fields = withoutBase(fields));
+  if (res.error)
+    throw new Error(`gh: ${res.error.message}`);
+  let checksError;
+  if (res.status !== 0 && FORBIDDEN.test(res.stderr ?? "")) {
+    checksError = reason(res);
+    const retry = view1(fields === PR_VIEW_FIELDS ? PR_VIEW_FIELDS_NO_CHECKS : withoutBase(PR_VIEW_FIELDS_NO_CHECKS));
+    if (retry.error)
+      throw new Error(`gh: ${retry.error.message}`);
+    if (retry.status !== 0) {
+      throw new Error(FORBIDDEN.test(retry.stderr ?? "") ? `${reason(retry)} (fails even without check results)` : reason(retry));
+    }
+    res = retry;
+  }
+  if (res.status !== 0)
+    throw new Error(reason(res));
+  const view = JSON.parse(res.stdout);
+  if (checksError)
+    view.checksError = checksError;
+  if (view.state === "OPEN") {
+    const threads = ghUnresolvedThreads(ref);
+    if (threads !== void 0)
+      view.unresolvedThreads = threads;
+  }
+  return view;
+}
+var THREADS_QUERY = "query($owner:String!,$repo:String!,$n:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100){nodes{isResolved}}}}}";
+function ghUnresolvedThreads(ref) {
+  const res = spawnSync("gh", ["api", "graphql", "-f", `query=${THREADS_QUERY}`, "-f", `owner=${ref.owner}`, "-f", `repo=${ref.repo}`, "-F", `n=${ref.number}`], { encoding: "utf8", timeout: 6e4 });
+  if (res.error || res.status !== 0)
+    return void 0;
+  return parseUnresolvedThreads(res.stdout);
+}
+function parseUnresolvedThreads(stdout) {
+  try {
+    const nodes = JSON.parse(stdout).data?.repository?.pullRequest?.reviewThreads?.nodes;
+    return Array.isArray(nodes) ? nodes.filter((t) => t.isResolved === false).length : void 0;
+  } catch {
+    return void 0;
+  }
+}
 
 // packages/core/dist/prs.js
 import * as fs14 from "node:fs";
@@ -1594,6 +1681,20 @@ import * as path11 from "node:path";
 function prsDir() {
   return path11.join(lobstahHome(), "prs");
 }
+function prRecordFile(key) {
+  const ref = parsePrRef(key);
+  if (!ref)
+    throw new Error(`not a PR key: ${key}`);
+  const safe = (s) => s.replace(/[^A-Za-z0-9._-]/g, "_");
+  return path11.join(prsDir(), `${safe(ref.owner)}__${safe(ref.repo)}__${ref.number}.json`);
+}
+function readPr(key) {
+  try {
+    return JSON.parse(fs14.readFileSync(prRecordFile(key), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
 function readPrs() {
   let files;
   try {
@@ -1640,11 +1741,11 @@ function chainPr(id, lane) {
 // packages/core/dist/pr-repair.js
 var PUSH_RETRIES = 3;
 var PUSH_REJECTED = "push rejected:";
-function pushRule(branch, id = "<dispatch id>") {
+function pushRule(branch, id = "<dispatch id>", mode = "rebase") {
   const b = branch ?? "the PR's head branch";
   return [
     `Push only to the existing branch ${b}.`,
-    `If the push is rejected as non-fast-forward because ${b} moved, fetch ${b}, rebase your commits onto the moved head again, and push with \`--force-with-lease=${b}:<the head you just fetched>\`. Retry at most ${PUSH_RETRIES} times.`,
+    mode === "merge" ? `If the push is rejected as non-fast-forward because ${b} moved, fetch ${b}, merge the moved head into your branch, and push again with a normal push. Retry at most ${PUSH_RETRIES} times. Never force-push.` : `If the push is rejected as non-fast-forward because ${b} moved, fetch ${b}, rebase your commits onto the moved head again, and push with \`--force-with-lease=${b}:<the head you just fetched>\`. Retry at most ${PUSH_RETRIES} times.`,
     "If a push hook fails with a real test or type error, do not retry the push: fix the error, commit, and push again.",
     `If you still cannot push, report \`lobstah report ${id} failed "${PUSH_REJECTED} <rejection text>; moved head <full sha of the head you fetched>"\` and leave the PR as it was.`,
     "Never push to another branch. Never open a new PR."
@@ -1655,7 +1756,7 @@ function pushRule(branch, id = "<dispatch id>") {
 import * as fs15 from "node:fs";
 import * as os3 from "node:os";
 import * as path12 from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-([0-9a-f])[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function harnessFromSessionId(sessionId) {
   const version = sessionId ? UUID.exec(sessionId)?.[1] : void 0;
@@ -1717,7 +1818,7 @@ function isUnresumable(error) {
 function worktreeProgress(worktree, trunk) {
   if (!worktree || !fs15.existsSync(worktree))
     return "No worktree progress recorded.";
-  const git2 = (...a) => spawnSync("git", a, { cwd: worktree, encoding: "utf8" }).stdout?.trim() ?? "";
+  const git2 = (...a) => spawnSync2("git", a, { cwd: worktree, encoding: "utf8" }).stdout?.trim() ?? "";
   const commits = trunk ? git2("log", "--oneline", `origin/${trunk}..HEAD`) : git2("log", "--oneline", "-15");
   const status = git2("status", "--short");
   return `Commits so far:
@@ -1827,7 +1928,7 @@ function isFinished(id, lane) {
 // packages/runner/src/run.ts
 import * as fs19 from "node:fs";
 import * as path16 from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // packages/adapters/dist/claude.js
@@ -2346,7 +2447,7 @@ function loadAdapter(name) {
 import * as fs17 from "node:fs";
 import * as path14 from "node:path";
 import { createHash } from "node:crypto";
-import { exec, execFile } from "node:child_process";
+import { exec, execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 var run = promisify(execFile);
 var shell = promisify(exec);
@@ -2372,7 +2473,12 @@ var LOCK_CONTENTION = [
   // held by another process ("fetching ref <ref> failed: reference already
   // exists"). The files backend maps the lock's EEXIST to this reason; older
   // git printed "Unable to create '<ref>.lock': File exists" instead.
-  /reference already exists/
+  /reference already exists/,
+  // Windows: two fetches unpack the same loose object, and one cannot write
+  // the file the other holds open ("unable to write file
+  // .git/objects/<xx>/<rest>: Permission denied", then "unpack-objects
+  // failed"). Only an object path matches, not any denied write.
+  /unable to write file \S*objects[\\/][0-9a-f]{2}[\\/][0-9a-f]{38,}: Permission denied/
 ];
 function gitStderr(err) {
   const stderr = err.stderr;
@@ -2399,6 +2505,112 @@ ${gitStderr(err)}`, { cause: err });
     }
   }
 }
+var REPO_LOCK_WAIT_MS = 5 * 6e4;
+var repoQueues = /* @__PURE__ */ new Map();
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+var BUSY = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY"]);
+function takeRepoLock(file, mine) {
+  try {
+    fs17.writeFileSync(file, mine, { flag: "wx" });
+    return { state: "held" };
+  } catch (err) {
+    const code = err.code ?? "";
+    if (code !== "EEXIST" && !BUSY.has(code))
+      throw err;
+  }
+  let raw = "";
+  let age = 0;
+  try {
+    raw = fs17.readFileSync(file, "utf8");
+    age = Date.now() - fs17.statSync(file).mtimeMs;
+  } catch {
+    return { state: "retry" };
+  }
+  let holder;
+  try {
+    holder = JSON.parse(raw);
+  } catch {
+    holder = void 0;
+  }
+  const stale = age > REPO_LOCK_WAIT_MS || (holder ? !pidAlive(holder.pid) : age > 5e3);
+  if (stale) {
+    try {
+      if (fs17.readFileSync(file, "utf8") === raw)
+        fs17.rmSync(file, { force: true });
+    } catch {
+    }
+    return { state: "retry" };
+  }
+  return { state: "wait", ...holder ? { holder: holder.pid } : {} };
+}
+function releaseRepoLock(file, mine) {
+  try {
+    if (fs17.readFileSync(file, "utf8") === mine)
+      fs17.rmSync(file, { force: true, recursive: true, maxRetries: 5 });
+  } catch {
+  }
+}
+async function withRepoLock(common, fn) {
+  const file = path14.join(common, "lobstah-git.lock");
+  const mine = JSON.stringify({ pid: process.pid, at: (/* @__PURE__ */ new Date()).toISOString() });
+  const deadline = Date.now() + REPO_LOCK_WAIT_MS;
+  let held = false;
+  while (Date.now() < deadline) {
+    const took = takeRepoLock(file, mine);
+    if (took.state === "held") {
+      held = true;
+      break;
+    }
+    if (took.state === "wait")
+      await new Promise((r) => setTimeout(r, 50 + Math.random() * 50));
+  }
+  try {
+    await fn();
+  } finally {
+    if (held)
+      releaseRepoLock(file, mine);
+  }
+}
+async function oneAtATime(cwd, fn) {
+  const common = await git(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir");
+  const key = realpath(common);
+  const run2 = (repoQueues.get(key) ?? Promise.resolve()).then(() => withRepoLock(common, () => fn(common)));
+  const tail = run2.catch(() => {
+  });
+  repoQueues.set(key, tail);
+  try {
+    await run2;
+  } finally {
+    if (repoQueues.get(key) === tail)
+      repoQueues.delete(key);
+  }
+}
+function fetchStamps(common) {
+  try {
+    return JSON.parse(fs17.readFileSync(path14.join(common, "lobstah-fetch.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function fetchShared(cwd, remote, ref) {
+  const asked = Date.now();
+  const key = `${remote} ${ref}`;
+  await oneAtATime(cwd, async (common) => {
+    if ((fetchStamps(common)[key] ?? -Infinity) >= asked)
+      return;
+    const started = Date.now();
+    await gitShared(cwd, "fetch", remote, ref);
+    const stamps = { ...fetchStamps(common), [key]: started };
+    fs17.writeFileSync(path14.join(common, "lobstah-fetch.json"), JSON.stringify(stamps, null, 2));
+  });
+}
 async function allocate(repo, id, fromRemoteBranch = repo.trunk) {
   const dir = worktreePath(id);
   if (fs17.existsSync(dir)) {
@@ -2409,8 +2621,10 @@ async function allocate(repo, id, fromRemoteBranch = repo.trunk) {
       throw new Error(`repo path ${repo.path} missing and no origin configured`);
     await run("git", ["clone", repo.origin, repo.path], { env: process.env });
   }
-  await gitShared(repo.path, "fetch", "origin", fromRemoteBranch);
-  await gitShared(repo.path, "worktree", "add", "--no-track", dir, "-b", `lobstah/${id}`, `origin/${fromRemoteBranch}`);
+  await fetchShared(repo.path, "origin", fromRemoteBranch);
+  await oneAtATime(repo.path, async () => {
+    await gitShared(repo.path, "worktree", "add", "--no-track", dir, "-b", `lobstah/${id}`, `origin/${fromRemoteBranch}`);
+  });
   await runSetup(repo, dir);
   return dir;
 }
@@ -2544,7 +2758,7 @@ async function chooseWorktree(input) {
   return { reuse: true, path: found.path, owner: found.owner, from: found.from };
 }
 async function prepareReuse(repo, dir) {
-  await gitShared(dir, "fetch", "origin", repo.trunk);
+  await fetchShared(dir, "origin", repo.trunk);
   if (!repo.setup?.length)
     return { setupRan: false };
   if (recordedSetupHash(dir) === setupHash(repo, dir))
@@ -2874,6 +3088,7 @@ function planStart(input) {
 function startWallClock(opts) {
   const now2 = opts.now ?? Date.now;
   const tickMs = Math.max(1, Math.min(opts.tickMs ?? 5e3, opts.limitMs));
+  const sleepGapMs = opts.sleepGapMs ?? Math.max(6e4, tickMs * 6);
   let elapsed = opts.initialElapsedMs ?? 0;
   const maxMs = Math.max(opts.limitMs, opts.maxMs ?? opts.limitMs);
   let windowMs = Math.min(maxMs, Math.max(opts.limitMs, opts.initialWindowMs ?? opts.limitMs));
@@ -2887,7 +3102,8 @@ function startWallClock(opts) {
     } catch {
       paused = false;
     }
-    if (!paused) elapsed += t - last;
+    const step = Math.max(0, t - last);
+    if (!paused) elapsed += step > sleepGapMs ? Math.min(step, tickMs) : step;
     last = t;
     if (!done && elapsed >= windowMs && elapsed < maxMs) {
       let advanced = false;
@@ -3094,13 +3310,23 @@ function keepRemote(opts) {
 }
 
 // packages/runner/src/run.ts
+function livePrState(url) {
+  const ref = parsePrRef(url);
+  if (!ref) return void 0;
+  try {
+    return ghPrView(ref).state;
+  } catch {
+    return void 0;
+  }
+}
 var defaultDeps = {
   loadAdapter,
   allocate,
   chooseWorktree,
   prepareReuse,
   collectEvidence,
-  reap: async () => 0
+  reap: async () => 0,
+  prState: livePrState
 };
 var DONE_WAIT_MS = 2e3;
 function within(p, ms, fallback) {
@@ -3141,6 +3367,14 @@ async function main(activeDir, lane, seams = {}) {
     attempts
   };
   fs19.writeFileSync(path16.join(activeDir, "runner.json"), JSON.stringify(runnerInfo, null, 2));
+  if (descriptor.systemRepair && descriptor.pr?.url) {
+    const state = deps.prState(descriptor.pr.url) ?? readPr(parsePrRef(descriptor.pr.url)?.key ?? "")?.state;
+    if (state === "MERGED" || state === "CLOSED") {
+      status("failed", `cancelled: ${descriptor.pr.url} is ${state.toLowerCase()}; nothing to repair`);
+      complete(id, lane);
+      return;
+    }
+  }
   const plan = planStart({
     id,
     lane,
@@ -3240,7 +3474,7 @@ async function main(activeDir, lane, seams = {}) {
   })();
   const head = () => {
     try {
-      return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+      return execFileSync2("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
     } catch {
       return void 0;
     }
@@ -3412,10 +3646,10 @@ async function main(activeDir, lane, seams = {}) {
 }
 
 // packages/runner/src/reap.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 function listProcesses() {
   if (process.platform === "win32") {
-    const out2 = execFileSync2(
+    const out2 = execFileSync3(
       "powershell.exe",
       [
         "-NoProfile",
@@ -3427,7 +3661,7 @@ function listProcesses() {
     );
     return out2.split(/\r?\n/).map((l) => l.trim().split(/\s+/).map(Number)).filter(([pid, ppid]) => Number.isInteger(pid) && Number.isInteger(ppid)).map(([pid, ppid]) => ({ pid, ppid }));
   }
-  const out = execFileSync2("ps", ["-A", "-o", "pid=,ppid=,pgid="], {
+  const out = execFileSync3("ps", ["-A", "-o", "pid=,ppid=,pgid="], {
     encoding: "utf8",
     timeout: 3e4,
     stdio: ["ignore", "pipe", "ignore"]
@@ -3470,7 +3704,7 @@ async function stopPids(pids, graceMs = 2e3) {
   if (process.platform === "win32") {
     for (const pid of pids) {
       try {
-        execFileSync2("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: 3e4 });
+        execFileSync3("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: 3e4 });
       } catch {
       }
     }

package/docs/configuration.md

@@ -42,6 +42,25 @@ rather than relying on the default — left unset, a Claude session takes
 `effortLevel` from the host's settings files, including the user's own
 `~/.claude/settings.json`.
 
+`[repos.<key>.briefHooks]` — markdown appended to the briefs lobstah
+writes for this repo, one key per kind. Each value is a string; lobstah
+appends it as written and does not read it.
+
+| Key | Appended to |
+|---|---|
+| `conflict` | A daemon repair of a PR with a merge conflict. |
+| `checks` | A daemon repair of a PR with failing checks. |
+| `review` | A daemon repair of a PR with requested changes, and a pickup review-feedback round. |
+| `ciFix` | A CI-fix continuation a PR watch forks. |
+| `rebase` | A rebase chore from pickup's merge loop. |
+| `all` | Every kind above, after that kind's own text. |
+
+```toml
+[repos.web.briefHooks]
+all = "Before you report done, run the repo's PR refresh (`/pr-refresh`)."
+checks = "Run `pnpm test:ci` before you push."
+```
+
 `lobstah repos add <path> [--pickup]` detects and appends a block (origin,
 default branch from `origin/HEAD`, setup from the lockfile); `lobstah init
 --scan <dir>...` does the same for every git repo found under the given
@@ -113,7 +132,8 @@ send a continuation.
 | `conflicts` | `true` | Repair conflicts when `autoRepair` is on. Set `false` to show conflict attention without a repair. |
 | `checks` | `true` | Repair failed current checks when `autoRepair` is on. Set `false` to show check attention without a repair. |
 | `maxRepairsPerPr` | `2` | Maximum repair follow-ups for one PR head SHA. When the limit is reached and the issue remains, `pr:conflict`, `pr:checks`, or `pr:review` attention names the limit. A repair that waits is not an attempt. Below this limit, each failing check gets at most one repair round per PR and head SHA: a check that had its round and still fails on the same head waits for a new commit, with `repair.status: waiting` and `heldBy: repaired`, and raises `pr:checks` attention. A CI-fix continuation from `lobstah pick` (`autoRepair = false`) follows the same rule. Human gates (`[repos.<key>].humanGateChecks`, `report --human-gate`) get no round. |
-| `repairSettleSecs` | `600` | A repair is queued only after the PR's head, its base branch's head, and its failing checks have been unchanged for this many seconds. Until then the PR record shows `repair.status: waiting` with `heldBy: settle` and `until`. |
+| `repairSettleSecs` | `600` | A repair is queued only after the PR's head, its base branch's head, and its failing checks have been unchanged for this many seconds. A conflict repair also waits this many seconds after the PR's latest approval. Until then the PR record shows `repair.status: waiting` with `heldBy: settle` and `until`. |
+| `maxRepairsWithoutProgress` | `2` | Maximum repairs in a row on one PR that end `done` while the PR stays at the head the repair pushed and does not merge. Past the cap, lobstah stops repairing that PR: the PR record shows `repair.status: gave-up`, `pr:conflict` (or `pr:checks`, `pr:review`) attention names the cap, and one `repair-stopped` notice is posted. The count resets when the PR merges or closes, when a push that is not the repair's moves the head, and on `lobstah watch release <key>` (or `--all`). |
 | `repairTrapWaitSecs` | `600` | A daemon repair chore addressed to the PR-owning trap waits this many seconds for that trap. If still queued, it becomes headless. A person's addressed work never falls back. |
 
 ## `[grounds.*]` — helm territories

package/docs/man.md

@@ -192,20 +192,47 @@ with `paused --waiting-on pr` or `--waiting-on review` merges, the daemon
 finishes that dispatch `done` with the note `the PR merged: <url>`. When
 the PR closes without merge, it finishes it `failed` with `the PR closed
 without merge: <url>`. The PR waited on is the `--link` when it names a
-GitHub PR, else the dispatch's own PR, else its chain's PR. Every paused
-dispatch waiting on that PR is finished, in the whole chain. The daemon
-does this after it observes PR watches and before its cull pass, so
-`[limits].releaseOnMerge` releases the chain's worktrees in the same pass.
-`report paused --waiting-on pr|review` registers the watch of the
-dispatch's own PR when it has none, so the merge is observed.
+GitHub PR that is not one of the dispatch's own. Otherwise the dispatch
+waits on all of its own PRs (its evidence, which `lobstah catch` shows),
+else its chain's PR, else the PRs of the `pr:` watches it owns. A
+dispatch with several PRs finishes only when every one of them has merged
+or closed: `done` when at least one merged (`the PRs merged: <urls>`, or
+`the PRs ended — merged: <urls>; closed without merge: <urls>`), `failed`
+when all closed without merge. Every paused dispatch waiting on those PRs
+is finished, in the whole chain. The daemon does this after it observes PR watches and before its
+cull pass, so `[limits].releaseOnMerge` releases the chain's worktrees in
+the same pass. `report paused --waiting-on pr|review` registers the watch
+of the dispatch's own PR when it has none. The daemon also reads, at
+`[pickup].pollSecs`, each waited-on PR that no live dispatch-owned watch
+observes (a linked PR with no watch, or a helm-owned watch), so its merge
+or close is seen without `lobstah pick`. When lobstah knows no PR for the
+wait, the report prints a `warning` and a merge will not finish the
+dispatch: report again with `--link <PR url>`.
 
 ### PR state after done
 
 A dispatch reports its PR with `report <id> <verb> --pr <url>`, which
 registers a `pr:` watch for the chain so the PR stays observed (see the
 PR preset in [vocabulary.md](vocabulary.md#the-pr-preset); `--no-watch`
-opts out). A trap's PR is tracked from its first push. What you get
-depends on what runs:
+opts out). A trap's PR is tracked from its first push.
+
+A dispatch can own several PRs. `--pr` is repeatable: each PR is recorded
+and gets its own `pr:` watch. The first is the dispatch's `prUrl`; all of
+them are its `prUrls`. When a reported PR is part of a stack, the other PRs
+of the stack are recorded too:
+
+- a gh stack: the `gh-stack` state in the dispatch's checkout (from
+  `gh stack init` or `gh stack submit`) lists a stack that holds the PR;
+- a base chain: the dispatch pushed two or more branches, and
+  `gh pr view <branch>` links their PRs to the reported one by base
+  branch.
+
+The report prints `prs` with every PR it recorded. `lobstah catch` and
+`lobstah status <id>` list each PR (`prs`), `man tend` lists each with its
+state in the story's `pr` column, and the glass links each by number. Each
+PR has its own record, so `pr:*` attention and the merged/closed notice are
+per PR. `[limits].releaseOnMerge` keeps the worktree while another PR of
+the dispatch is open. What you get depends on what runs:
 
 - **Only the helm park or `man wait`** (no service): PR state badges in
   `man tend`, `lobstah catch`, and the glass (`merged`, `draft`, `review`,
@@ -223,16 +250,21 @@ succeeds and the watch's check records `lastError`.
 
 Which commands register a watch. Only these write points register one:
 
-- `lobstah report <id> <verb> --pr <url>` registers the watch for the PR the
-  worker opened. Any verb but `failed` does this. A PR already watched is
-  not registered again.
+- `lobstah report <id> <verb> --pr <url> [--pr <url> ...]` registers the
+  watch for each PR the worker opened, and for the other PRs of a stack
+  that holds one of them. Any verb but `failed` does this. A PR already
+  watched is not registered again.
 - `lobstah report <id> paused --waiting-on pr|review` registers the watch
-  for the dispatch's own PR. A `--link` to another PR registers nothing.
+  for the dispatch's own PR. A `--link` to another PR registers nothing; the
+  daemon reads that PR while the dispatch waits on it.
 - `lobstah soak beat` registers the watch for a trap's PR from its first
   push. At most once a minute, it reads the trap's branch. When the branch
-  is not trunk and has an upstream, it asks `gh pr view <branch>` for the PR.
-  It records a new PR in the dispatch's evidence, where `lobstah catch` and
-  `lobstah status <id>` show it.
+  is not trunk, has an upstream, and its head commit is newer than the
+  dispatch's claim, it asks `gh pr view <branch>` for the PR. A trap that
+  takes new work on the branch of its last dispatch does not give that PR
+  to the new dispatch until the new dispatch commits. It records a new PR in
+  the dispatch's evidence, where `lobstah catch` and `lobstah status <id>`
+  show it.
 - `lobstah watch add <key>` registers the watch you name.
 - `lobstah watch backfill --apply` registers watches for PRs in old dispatch
   history, and fetches the title of each PR record that has none (one
@@ -304,6 +336,8 @@ and the glass show the repair's PR, chore lane, worker, and trap wait.
   PR whose head branch is its base branch.
 - The PR's head, its base branch's head, or its failing checks changed less
   than `[watch].repairSettleSecs` ago (default 600).
+- For a conflict repair: the PR was approved less than
+  `[watch].repairSettleSecs` ago.
 - For a checks repair: a fresh read of the latest run of each failing check
   shows that run in progress or passed.
 - The PR's watch is held. `lobstah cancel` on a repair dispatch holds its
@@ -322,13 +356,29 @@ in the `repairs waiting` table, the PR badge ends in `repair waits: <heldBy>`,
 the glass PR modal shows the reason, and `lobstah doctor` lists it. When the
 wait ends, the normal rules apply again.
 
+**Repairs stop** on a PR after `[watch].maxRepairsWithoutProgress`
+(default 2) repairs in a row that each ended `done` while the PR stayed at
+the head the repair pushed and did not merge. lobstah then queues no repair
+for that PR, marks its repair `gave-up`, raises `pr:conflict` (or
+`pr:checks`, `pr:review`) attention that names the cap, and posts one
+`repair-stopped` notice. The count resets when the PR merges or closes,
+when a push that is not the repair's moves the head, and on
+`lobstah watch release <key>`, which prints `repairsResumed` with the PRs it
+resumed.
+
 **A repair pushes** to its PR's head branch, and so does a rebase chore
 from pickup's merge loop. The descriptor of each names its PR (`pr`), so
 the runner pushes no branch and opens no PR for it. The brief gives the
-worker the push rule: push only to the PR's head branch. On a
-non-fast-forward rejection, fetch the branch, rebase the commits onto the
-moved head again, and push with `--force-with-lease` on the head just
-fetched, at most three times. A push hook that fails with a real test or
+worker the push rule: push only to the PR's head branch. A conflict
+repair of a **standalone** PR (its base is the repo's `trunk`) merges the
+base into the PR branch with a merge commit and pushes normally; on a
+non-fast-forward rejection it fetches the moved head, merges it, and
+pushes again, never with force. A conflict repair of a **stacked** PR (its
+base is another PR's branch) rebases onto that base and pushes with
+`--force-with-lease`; on a rejection it rebases onto the moved head again
+and pushes with a lease on the head just fetched. A checks or review
+repair follows the rebase rule on a rejection. Each retries at most three
+times. A push hook that fails with a real test or
 type error is not retried: the worker fixes the error and pushes again.
 For code already on main, the repair keeps main's version and only this
 PR's own changes. It does not change behavior. If a conflict resolution
@@ -509,7 +559,9 @@ the same rule.
   `attachments/`. The claimed helm alone may ask.
 - **Standing.** A decision stands until it is answered or the helm withdraws
   it with `lobstah man ask --withdraw <key>`, which removes its directory. A
-  newer `man ask` on the same dispatch replaces the older decision.
+  newer `man ask` on the same dispatch keeps the older decisions: each shows
+  as its own card. `lobstah man ask ... --replace <key>` replaces that one
+  standing decision; a key that is not standing is refused.
 - **Attention.** A standing decision is attention of kind `decision`, in
   the default `attentionKinds`. It makes the verdict `needs-attention`. A
   worker's raw `needs-decision` or `blocked` stays a `question` until the