lobstah 0.6.3 → 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 ?? {};
@@ -1728,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."

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

package/docs/vocabulary.md

@@ -83,9 +83,14 @@ Effects of `paused` with `--waiting-on`:
 - With `--waiting-on pr` or `--waiting-on review`: when the PR it waits on
   merges, the daemon finishes the dispatch `done` (`the PR merged: <url>`);
   closed without merge, `failed`. The PR is the `--link` when it names a
-  GitHub PR, else the dispatch's own PR, else its chain's PR. Every paused
-  dispatch in the chain that waits on the PR is finished. The report
-  registers the watch of the dispatch's own PR when it has none.
+  GitHub PR that is not the dispatch's own. Otherwise it is every PR of the
+  dispatch (`prUrl` and `prUrls`), else its chain's PR, else the PRs of the
+  `pr:` watches the dispatch owns; the dispatch finishes when all of them
+  have ended. Every paused dispatch in the chain that waits on the PR is
+  finished. The report registers the watch of the
+  dispatch's own PR when it has none, and the daemon reads a waited-on PR
+  that no live dispatch-owned watch observes. When no PR is known, the
+  report prints a `warning`.
 - No attention, no notice, no pet. It is a state, not a question.
 
 Source of truth: `WAITING_ON` in `packages/core/src/types.ts`.
@@ -349,7 +354,7 @@ evidence).
 | `draft` | Draft flipped (`value`). Evidence only. |
 | `merged` / `closed` | Terminal; the check sets `done`, and the watch retires once delivered. Emitted only on an open → terminal change, never on the first observation. |
 | evidence `pr` | `{ url, number, state, draft, reviewDecision, mergeStateStatus, headSha, checks: { total, passed, failed, pending, unknown? }, review: { unresolvedThreads, changesRequested, lastReviewAt }, observedAt }`. Check counts use only the latest run per check name and app/workflow. `CANCELLED` and `STALE` latest runs are unknown, not failed. The PR record also stores repair status, attempts, and reason. `prBadge` shows `repairing: conflict (attempt 1 of 2)` while a repair is in flight, and ends in `repair waits: <heldBy>` while a repair waits; tend, `catch`, and the glass share the badge. |
-| waiting repair | `repair.status: waiting` on a PR record: a repair is due but is not queued. `heldBy` names the holder: `wt:<trap>` or `dispatch:<id8>` (a live worker holds the PR's head branch or the head branch of a PR below it in the stack), `helm` (the helm cancelled a repair of this PR), `hold` or `dispatch:<id8>` (`watch hold`), `settle` (the head, base head, or failing checks changed less than `[watch].repairSettleSecs` ago; `until` says when), or `checks` (the latest run of a failing check is in progress or passed). `reason` says what holds it. A wait is not an attempt and raises no attention item. |
+| waiting repair | `repair.status: waiting` on a PR record: a repair is due but is not queued. `heldBy` names the holder: `wt:<trap>` or `dispatch:<id8>` (a live worker holds the PR's head branch or the head branch of a PR below it in the stack), `helm` (the helm cancelled a repair of this PR), `hold` or `dispatch:<id8>` (`watch hold`), `settle` (the head, base head, or failing checks changed less than `[watch].repairSettleSecs` ago, or, for a conflict repair, the PR was approved less than that ago; `until` says when), or `checks` (the latest run of a failing check is in progress or passed). `reason` says what holds it. A wait is not an attempt and raises no attention item. |
 | repair chore | A daemon repair or rebase runs in the `chore` lane under `[limits].choreConcurrent`. A repair chore for a trap-built PR waits for its live owning trap up to `[watch].repairTrapWaitSecs` (default 600), then runs headless in its own PR-branch checkout. A headless-built PR's repair runs headless in its origin worktree when safe. No headless chore uses a trap's worktree. This bounded fallback applies only to system repair chores; a person's addressed work is sticky and never falls back. Tend, daemon status, doctor, and the glass show the PR, lane, worker, and trap wait. |
 | live worker | An active headless dispatch, or a trap with an open catch. It holds a branch that its worktree has checked out, that its current branch tracks, or that it pushed during its current dispatch (evidence `pushes`). It holds a PR that its evidence names or that its chain owns. |
 | evidence `pushes` | `[{ branch, at }]`: the branches a dispatch pushed, as lobstah saw them. The runner records its own pushes; the runner records a headless worker's `git push` from the harness event stream (branch names only); `soak beat` records a trap's `git push`. |
@@ -368,7 +373,11 @@ PR's head branch or a branch below it in the stack, until the PR has settled
 for `[watch].repairSettleSecs`, while a failing check's latest run is in
 progress or passed, and while the PR's watch is held. A wait is not an
 attempt. A repair whose worker reported `failed "push rejected: ..."` is `blocked` at the
-moved head and at the head it started from. The rest is evidence.
+moved head and at the head it started from. After
+`[watch].maxRepairsWithoutProgress` repairs in a row that left the PR at
+their own push and unmerged, repairs of that PR stop (`gave-up`, a
+`repair-stopped` notice) until it merges or closes, a push that is not the
+repair's moves the head, or `lobstah watch release <key>`. The rest is evidence.
 Merged and closed reach the helm as a `pr-merged` / `pr-closed` notice,
 posted once by whichever process first records the open → terminal
 transition on the **PR record** — not by event routing. A PR whose first
@@ -431,7 +440,7 @@ worktree is refused (the session lock); a stale one is adopted.
 | defective enlistment | A stale registration that **never parked** — signed on but never listened (usually no Stop hook). Not swept: the helm gets a `trap-defective` notice with the remedy (`soak --wait`), and the registration stays so the address keeps protecting its work. |
 | reserved trap | A trap `lobstah trap reserve` created before any session signs on as it: a name, a `wt:` id, and a one-time ticket, shown as `starting`. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. Unredeemed past its deadline, it fails with a `trap-start-failed` notice and its work stays queued. `stow --wt <name>` withdraws it. |
 | trap request | A trap the human asked for from the glass's **+ New trap** button: a `trap-request` request in `requests/<id>.json` with a repo and a harness. It wakes the helm as a `trap-request` event; the helm reserves it with `trap reserve --request <id>`, which closes it. |
-| notice | The helm's attention channel for non-status events (`~/.lobstah/notices/`): reservations (`trap-starting`), reservations that did not start (`trap-start-failed`), trap requests from the glass (`trap-request`), sign-ons, first parks, sign-offs, ghosts, defective enlistments, orphaned work, bounced messages, PRs merged or closed, watches held over the fork cap (`watch-held`), failing (`watch-failing`), and recovered (`watch-recovered`), free-space holds (`disk-held`, `disk-cleared`), worktrees released after their PR merged (`worktree-released`, one per cull pass), a repair or rebase that could not push to its PR's branch (`push-failed`), and a human's answer to a decision (`decision-answer`; its ref is the request id in `~/.lobstah/requests/`). A trap leaves the registry only through a `trap-stowed` or `trap-ghosted` notice — the end-state is always explicit. Consumed by `man wait`/the park; a first park (`trap-listening`) is consumed without waking anyone. tend always shows the recent tail. |
+| notice | The helm's attention channel for non-status events (`~/.lobstah/notices/`): reservations (`trap-starting`), reservations that did not start (`trap-start-failed`), trap requests from the glass (`trap-request`), sign-ons, first parks, sign-offs, ghosts, defective enlistments, orphaned work, bounced messages, PRs merged or closed, watches held over the fork cap (`watch-held`), failing (`watch-failing`), and recovered (`watch-recovered`), free-space holds (`disk-held`, `disk-cleared`), worktrees released after their PR merged (`worktree-released`, one per cull pass), a repair or rebase that could not push to its PR's branch (`push-failed`), repairs stopped on a PR that made no progress (`repair-stopped`), and a human's answer to a decision (`decision-answer`; its ref is the request id in `~/.lobstah/requests/`). A trap leaves the registry only through a `trap-stowed` or `trap-ghosted` notice — the end-state is always explicit. Consumed by `man wait`/the park; a first park (`trap-listening`) is consumed without waking anyone. tend always shows the recent tail. |
 
 Delivery routes by ownership, same as watches: a continuation for a chain
 claimed by a live trap is addressed back to that trap and stays sticky.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lobstah",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
   "license": "MIT",
   "author": "aequitas labs LLC",