lobstah 0.5.0 → 0.5.7

package/docs/configuration.md

@@ -14,6 +14,7 @@ keys of that section.
 |---|---|---|
 | `notifyCommand` | — | Exec'd by the daemon on wake-worthy status transitions with `LOBSTAH_ID`, `LOBSTAH_LANE`, `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_AT` in the environment. Fire-and-forget; point it at ntfy, a Slack helper, anything. |
 | `notifyVerbs` | `["needs-decision", "blocked", "done", "failed"]` | Which verbs fire `notifyCommand`. |
+| `attentionKinds` | `["question", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready"]` | Which attention kinds `man tend` lists — and so what the desktop pet and the glass walk across the screen. Valid kinds: `question`, `landed` (opt-in), `pr:draft`, `pr:review`, `pr:checks`, `pr:conflict`, `pr:ready`; an unknown kind is a config error naming the valid set. Notify is edge-triggered and fires once per transition; attention is level-triggered and stands until its clear condition ([vocabulary.md](vocabulary.md#attention-contract)). |
 | `remindSecs` | `900` | An unanswered `needs-decision`/`blocked` re-fires to `man wait`/`man haul` on this interval until answered. `0` = report once only. |
 
 ## `[repos.<key>]` — workspace definitions
@@ -52,6 +53,7 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 | `maxRestartAttempts` | `2` | Bounded restart ladder for dead and wedged runners. |
 | `wallClockSecs` | `3600` | Hard per-dispatch ceiling, enforced by the runner. |
 | `choreRetentionDays` | `7` | Completed chores age out of `chores/done/`. |
+| `attachmentMaxBytes` | `26214400` (25 MiB) | Maximum size of each file supplied with repeatable `dispatch --attach` or `send --attach`. |
 
 ## `[soak]` — soaking sessions (`lobstah soak`)
 

package/docs/design.md

@@ -444,7 +444,27 @@ task's diff. That contaminates evidence and falsely serializes merges.
 
 The daemon spawns one runner per dispatch with `setsid`, then records its pid and
 process start time. The runner drives the adapter; the daemon supervises the
-runner and never touches the harness directly.
+runner and never touches the harness directly. A turn that ends with the
+worker's last report on `needs-decision`, `blocked`, or `paused` does not end
+the session: a headless worker waiting on a question stays alive until
+answered, cancelled, or the wall clock — the runner polls the inbox, touches the
+event stream each poll so the wedge detector sees a live wait, delivers the
+answer into the next turn, and stamps `working`. Only a turn ending on `working`
+(or no report) with an empty inbox ends the session and is stamped `done`.
+
+**The session's own harness resumes it.** A session only resumes under the
+harness that wrote it: a Codex thread id handed to Claude Code is "No
+conversation found". The descriptor's `harness` records what was asked, not
+what ran (a trap claims unaddressed work with whatever harness it is), so every
+run stamps `harness` into evidence beside `sessionId` (the adapter's for a
+headless run, the trap's for a claim), and one resolver reads it back for a
+follow-up's fork, a daemon restart, `lobstah swap`, and `attach`. It falls back
+to the claiming trap, then the session id's UUID version, then the descriptor.
+A follow-up whose `--harness` names something the chain never asked for is a
+swap: cold on that harness with the brief plus a progress note. A resume the
+harness refuses before doing any work falls back the same way and records
+`resume-fallback: <reason>` in the status note and evidence. It never fails
+the dispatch. The first status note says which of these happened.
 
 ```ts
 // inside the runner

package/docs/lobsterman.md

@@ -106,6 +106,47 @@ view](pickup.md#merge-view) pickup persists each tick, so PR state is at most
 one poll interval stale without tend making a single network call. `--json`
 emits the full report for dashboards and scripts to render.
 
+### PR state after done
+
+A dispatch reports `done` when its PR opens; `report done --pr <url>`
+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). 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`,
+  `checks 1/2 failed`, `conflicts`, `behind`, `green`), and a `pr-merged` / `pr-closed` notice
+  when the PR lands. The inline poller observes at `[pickup].pollSecs`
+  (default 45 s), one `gh pr view` per PR per cycle, and forks nothing.
+- **With `lobstah pick`** (watch-only mode needs no tracker; `lobstah pick
+  install` runs it as a service for a steady cadence): all of the above,
+  plus CI-fix continuations — a failing check forks the chain with a brief
+  naming the PR, the check, its details URL, and the head sha — and
+  review-decision continuations for repos `[pickup.github]` doesn't cover.
+
+`gh` must be on PATH and authenticated; if it isn't, the done report still
+succeeds and the watch's check records `lastError`.
+
+Watching a PR nobody dispatched — `lobstah watch add pr:<owner>/<repo>#<n>`
+with no `--for` — is how a helm follows a human's PR, or one whose
+dispatch chain was culled. Every observation lands in a PR record keyed by
+the PR, so it shows in the glass PRs tab and stacks and in tend's `pr:*`
+attention kinds exactly like a dispatched PR (its dispatch chain column is
+empty). It stays quiet while it's fine: only a failing check or a changes
+request surfaces as a watch event; a merge or close arrives as a notice.
+
+An observed PR joins tend's attention list by kind — `pr:draft`,
+`pr:review` (unresolved threads or changes requested), `pr:checks` (a red
+head), `pr:conflict` (GitHub reports it conflicting with its base),
+`pr:ready` (approved or all green, and GitHub says it can merge) — so it crawls in the glass and
+the desktop pet until its clear condition holds; clicking it opens the PR.
+`pr:review` and `pr:checks` stay off the screen while a worker already owns
+them (a pickup feedback round or the watch's fix continuation in flight).
+`attentionKinds` in `config.toml` picks the kinds; `landed` is opt-in. See
+the [attention contract](vocabulary.md#attention-contract). A PR is
+something to look at, not a stall: it never flips the verdict to
+`needs-attention` and stays out of the digest.
+
 ### The spyglass
 
 `lobstah glass [--port <n>]` serves tend as a live web page on 127.0.0.1
@@ -117,7 +158,9 @@ and the helm identified by name. It is strictly read-only and consumes no
 cursor: looking through the glass changes nothing, so it needs no helm and
 threatens nothing. Links out are copyable commands (`lobstah attach`,
 `claude --resume`), never click-to-exec — localhost HTTP is reachable by
-any webpage, so the glass exposes no endpoint that acts.
+any webpage, so the glass exposes no endpoint that acts. The ⚙ popover's two
+preferences — table or cards, and whether lobsters crawl the page — are
+per-browser, kept in that browser's localStorage and never on disk.
 
 This is where "is the agent alive?" belongs: the helm's heartbeat age on a
 page, not periodic proof-of-life turns in a transcript.
@@ -144,7 +187,7 @@ Every carrier shares the cursor (per grounds, for a helm):
 - **The wait loop.** A `man wait` timeout (exit 3) prints the delta when
   something changed, so a looping session gets periodic fleet reports for
   free — see the loop idiom below.
-- **The park.** A helm session's Stop-hook park delivers the digest as a wake
+- **The blocking park.** A helm session's Stop-hook park delivers the digest as a wake
   at `[helm].reportSecs` cadence — including the landed-then-idle case, where
   the last catches finish and nothing is left in flight to wake for.
 - **Direct call.** Anything with a clock — a gateway heartbeat, a cron — runs
@@ -166,70 +209,27 @@ human is watching — come back later and the transcript is the report.
 
 ## Getting woken instead of asked
 
-Three escalation tiers, least to most invasive. All are built on
-`lobstah man wait`: block until a dispatch — or a watched external source
-(`lobstah watch add`, e.g. a ume review session) — needs attention, print the
-event and what to do next, exit. It is **level-triggered for attention
-states** — if a `needs-decision` or an unconsumed watch event is already
-standing when it starts, it returns immediately — so a gap between one
-watcher exiting and the next arming can never lose an event. When no pick
-process is running, `man wait` runs due watch checks itself, so watching
-works with every service stopped.
-
-**Tier 1 — a push for the human.** Set the daemon's hook and forget it:
-
-```toml
-notifyCommand = "ntfy pub my-topic \"$LOBSTAH_VERB $LOBSTAH_ID: $LOBSTAH_NOTE\""
-```
-
-**Tier 2 — a background watcher in the liaison session.** The liaison runs
-`lobstah man wait` as a background task; when it exits, the harness's task
-notification wakes the session, and the printed `next:` line tells the agent
-exactly what to do — including re-arming. One watcher per wake is inherent to
-background tasks; the level-trigger makes the re-arm race harmless. Add to the
-liaison instructions:
-
-```markdown
-After dispatching work, run `lobstah man wait` as a background task. When it
-completes, follow its `next:` instruction, then re-arm it.
-```
-
-**Arm it long-lived.** The default (`--timeout 0`) waits forever and returns
-only when something happens — that is the right idiom, not a compromise.
-Every wake costs the session a turn, so a short timeout used as a "check in
-periodically" mechanism buys nothing but noise: attention is level-triggered
-and stands on disk until consumed, so a wait that dies mid-shift drops zero
-events — the next wait delivers everything that accumulated. There is no
-report to miss either; a quiet fleet has nothing to say. Pass `--timeout`
-only as a dead-man's check on the channel itself (an hour, not minutes): a
-quiet timeout prints one line, exits 3, and the re-arm proves the line was
-alive. Liveness reassurance for the human belongs on a status surface
-(`lobstah man tend`), never in the transcript.
-
-**Tier 3 — park the session on a Stop hook (Claude Code only).** A Stop hook
-that blocks on `lobstah man wait`, so the session never
-really idles — it parks for free and continues the moment something needs it.
-What this buys over tier 2 is not the wake. Both wake on events, and both
-cost a turn per wake. The difference: the re-arm is **structural instead of
-instructed**. Tier 2 works only as long as the model remembers to re-arm the
-watcher after every wake. A forgotten re-arm, a crashed watcher, or an
-interrupted turn leaves the session deaf until a human speaks. The Stop hook
-fires at every turn end, no matter what the model did. Supervision cannot
-lapse through instruction drift, and a blind stop mid-shift is impossible.
+After `man helm`, run `lobstah man wait --session <id> --timeout 900` as a
+background task and re-arm it after each completion. The wait registers a
+heartbeating watcher for the session and exits with an event or a timeout
+(exit 3). At turn end, `man haul` blocks with standing attention; in arm mode,
+work in flight allows a stop with a live watcher and otherwise blocks with
+the arm command. `man haul --park` or `[helm].park = "block"` makes the hook
+wait for attention itself. Without a Stop hook, run `man wait` in the foreground.
 
 The hook is a CLI command — `lobstah man haul` (the lobsterman hauls the
 trapline; every orchestrator-facing command lives under `lobstah man`).
 Install it from the project you'll run the lobsterman in:
 
 ```bash
-# Easiest: the plugin ships the hooks + the lobsterman skill, no settings
+# Easiest: the plugin ships the hooks + the lobsterman and trap skills, no settings
 # edits — /plugin marketplace add aequitas-labs/lobstah, then
 # /plugin install lobstah@lobstah (Claude Code and Codex v0.114+; Codex asks
 # for a one-time hook trust review). Or wire the Claude hook by hand:
 lobstah man init            # merges the Stop hook into .claude/settings.local.json
 lobstah man init --shared   # …or the committed .claude/settings.json
 lobstah man init --global   # …or once into ~/.claude/settings.json — any
-                            # directory with a .lobstah-man file then parks
+                            # directory with a .lobstah-man file then uses the hook
 lobstah man init --marker   # also touch .lobstah-man (per-directory gate)
 ```
 
@@ -240,38 +240,33 @@ are preserved verbatim. What it writes:
 { "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "lobstah man haul", "timeout": 14400 }] }] } }
 ```
 
-`haul` gates itself twice: only a designated session parks (launch it with
-`LOBSTAH_MAN=1 claude`, or `touch .lobstah-man` for a per-directory gate), and
-only while dispatches are in flight — conversational turns end free. On an
-event it blocks the stop with the event as context and tells the agent the
-session re-parks automatically; on timeout or any error it silently allows
-the stop, leaving tier 1 as the backstop past the horizon.
-
-Two habits worth adding to a lobsterman session's instructions: run
-`lobstah man wait --peek` at session start (a wake consumed by a session that
-died mid-handling is still standing state — peek resurfaces it), and treat
-the haul context as the work order for that turn.
-
-The trade-offs, honestly. While parked, the turn never ends, so the terminal
-shows a running hook. Each wake appends a turn to the context, and long
-shifts eventually compact. Without the gate, the hook parks every session in
-the project. And parking needs a turn-end hook that
-can block and inject a continuation. Claude Code's Stop hook can, and so can
-Codex's since its hooks system landed (v0.114+; older Codex only has the
-fire-and-forget notify hook, which cannot). Tier 2 is the right default.
-Tier 3 is for a dedicated, long-lived liaison session.
+`haul` applies to a signed-on helm or trap, or a session opted in with
+`LOBSTAH_MAN=1` or `.lobstah-man`. Queued dispatches count as work in flight.
 
 **Delivery guarantee.** Attention wakes are at-least-once with backoff. An
 unanswered question is reported immediately. While it still stands, it
 re-fires as a reminder every `remindSecs` (top-level config, default 900). So
 a wake consumed by a session that died mid-handling resurfaces on its own.
-Answering ends the reminders naturally, because the answer produces a new
-status entry. Set `remindSecs = 0` for pure at-most-once.
-
-**Any-harness fallback — the wrapper loop.** Tiers 2 and 3 lean on Claude
-Code features (background-task notifications, the Stop hook). For any other
-harness — or no interactive session at all — an outer loop blocking on `wait`
-spawns one fresh headless turn per event:
+Answering ends the reminders: a message to the dispatch newer than its
+question — `lobstah send`, a forwarded tracker comment, anything written
+through the inbox with provenance — means the question no longer stands, even
+before the worker reads it; `man tend` then shows the dispatch as
+`needs-decision (answered <n>m ago)` instead of listing it under attention.
+A newer `needs-decision` from the worker stands again. Set `remindSecs = 0`
+for pure at-most-once.
+
+**Acknowledging, display-only.** Clicking a desktop pet opens its target and
+runs `lobstah attention ack <item-key> --by pet`, so that pet stops walking
+the item until its state changes (a new status entry, head, failed check, or
+thread count). The ack changes only what the pet and the glass lobs display:
+`man tend --json` still lists the item (marked `acked`), and `man wait`, the
+park, and reminders ignore acks entirely — a human having seen a question
+must never hide it from the orchestrator that has to answer it. The glass,
+which has no write endpoint, hides a clicked lob per browser in localStorage
+instead.
+
+**Wrapper loop.** An outer loop blocking on `wait` can spawn one fresh
+headless turn per event:
 
 ```sh
 while out=$(lobstah man wait); do
@@ -291,9 +286,9 @@ in Standard Technical English: triage and dispatch but never do the work,
 leave running catches to the daemon, judge the catch not the keystrokes, stay
 inside your grounds, report deltas not dumps. `man brief` re-injects the
 charter at every session start, so it survives restarts and compaction
-without anyone re-running anything. A helm registration also arms the
-Stop-hook park by itself — no `.lobstah-man` marker, no env var — and gates
-the park-delivered digest above.
+without anyone re-running anything. A helm registration enables the
+Stop hook by itself — no `.lobstah-man` marker, no env var — and
+gates the digest above.
 
 **One helm per grounds, enforced.** A **grounds** is a named territory: the
 subset of configured repos one orchestrator oversees (`[grounds.*]`; with
@@ -310,7 +305,9 @@ cannot hold two:
 - `lobstah man relieve` steps down; a relieved session never re-takes on its
   own.
 - The rule is strict: once a helm is claimed, `man wait` and `man report`
-  are reserved for the helm session (identify with `--session`), and no
+  are reserved for the helm session (identified by `--session`, else hook
+  stdin, else `$CLAUDE_CODE_SESSION_ID` — inside Claude Code no flag is
+  needed; a refusal names the id it resolved and from where), and no
   other session parks as a lobsterman — those verbs consume the helm's
   wakes and cursor. A grounds-scoped call is stricter still: it belongs to
   that grounds' own helm, never a neighboring one. `man tend`/`man brief`
@@ -332,9 +329,11 @@ visible terminal, and whatever authenticated tooling a headless spawn can't
 get.
 
 ```bash
-lobstah soak --session <id>     # from a worktree — the primary checkout is
+lobstah soak                    # from a worktree — the primary checkout is
                                 # never claimable, so sign on from a linked
                                 # worktree (git worktree add ../side -b side)
+                                # (the id: --session, else hook stdin, else
+                                # $CLAUDE_CODE_SESSION_ID)
 lobstah soak --wait             # hookless sessions: listen in the foreground
                                 # (re-runs need no flags — identity is the
                                 # worktree); exit 3 = quiet, run it again
@@ -347,7 +346,12 @@ lobstah stow                    # sign off; an open catch requeues, unread
 survives session restarts — a new session in the same worktree resumes the
 same trap (a *live* foreign session is refused: the session lock). The
 session id (from the plugin's session-start brief) lives inside the
-registration as the liveness principal. Once soaking, the same Stop hook
+registration as the liveness principal. The harness (claude or codex) is
+inferred — from `CLAUDE*` / `CODEX*` in the environment, and when both are
+set (one harness launched inside the other) from the session id's format:
+Codex thread ids are UUIDv7, Claude Code session ids UUIDv4 — and
+`--harness` overrides; an undecidable case refuses rather than guessing.
+Once soaking, the same Stop hook
 that parks a lobsterman parks the worker: at turn end it delivers messages
 first, then claims bait and wakes with the brief. While it works a catch,
 the park wakes it for `lobstah send` messages and cancels instead.

package/docs/vocabulary.md

@@ -14,7 +14,7 @@ anything else. The status log is append-only; the last entry wins.
 | Verb | Meaning | Who acts next |
 | --- | --- | --- |
 | `working` | Making progress; nothing needed. | Nobody. |
-| `needs-decision` | Blocked on a judgment call only a human (or the orchestrator) can make. The note carries the question. | Human — re-fires every `remindSecs` until answered. |
+| `needs-decision` | Blocked on a judgment call only a human (or the orchestrator) can make. The note carries the question. A headless worker waiting on a question stays alive until answered (`lobstah send`), cancelled, or the wall clock. | Human — re-fires every `remindSecs` until answered. |
 | `blocked` | Cannot proceed for an external reason (missing access, broken dependency). | Human. |
 | `paused` | Intentionally idle; resume is expected. | Whoever paused it. |
 | `done` | The brief is fulfilled. Terminal. Merging is never the dispatch's job. | Merge loop / reviewer. |
@@ -106,9 +106,26 @@ Work moves through two **lanes** — `work` (human-originated) and `chore`
 tracker) — and three **buckets** within a lane: `queued`, `active`, `done`.
 Bucket transitions are atomic renames; the directory *is* the state.
 
+An **attachment** is a dispatch descriptor entry `{ name, path, bytes, type }`
+pointing to a copied, dispatch-owned file under `state/<id>/attachments/`;
+follow-ups reuse those paths, and messages may carry their own attachments.
+
+## Follow-up and swap
+
+How a dispatch picks up a session it did not start. One resolver
+(`resolveSessionHarness`, `packages/core/src/resume.ts`) names the harness
+that owns a session: evidence `harness`, else the claiming trap, else the
+session id's UUID version (v7 codex, v4 claude), else the descriptor.
+
+| Word | Meaning |
+| ---- | ------- |
+| follow-up | `--follow-up <id>` forks the origin's session **under the origin's harness**, whatever the follow-up's own `--harness` says, unless that `--harness` names something the chain never asked for and the session is not, which makes it a swap. Pickup review rounds and watch continuations are follow-ups. |
+| swap | Start cold on another harness with the brief plus a progress note (commits so far, uncommitted changes, and the origin's branch/PR/commits for a follow-up). `lobstah swap` does it to an active dispatch; a follow-up does it when it asks for a new harness. |
+| `resume-fallback` | Status note and evidence field (`resumeFallback`) recorded when the harness refuses a resume (not found, culled, foreign) before doing any work: the runner starts cold with the progress note and the dispatch proceeds. |
+
 ## Doctor statuses
 
-`lobstah doctor` grades each check with one of three words. **Owner:**
+`lobstah doctor` grades each check with one of four words. **Owner:**
 `apps/cli/src/doctor.ts`. **Enforcement:** any `fail` row exits 1.
 
 | Status | Meaning |
@@ -116,6 +133,7 @@ Bucket transitions are atomic renames; the directory *is* the state.
 | `ok`   | Works as configured. |
 | `warn` | Degraded or optional — dispatches may still run (e.g. one harness missing, daemon not running). |
 | `fail` | Broken configuration or missing requirement — fix before relying on lobstah. |
+| `skip` | The check does not apply on this host (e.g. no harness plugin installed). Never fails the run. |
 
 ## Watch contract
 
@@ -138,6 +156,59 @@ events stand until the owner consumes them. One continuation dispatch in
 flight per watch; later events buffer and fork from the latest session in
 the chain.
 
+### The PR preset
+
+`lobstah watch add pr:<owner>/<repo>#<n>` (or a github.com PR URL,
+normalized to that key) installs the shipped check, `lobstah watch
+check-pr`: one read-only `gh pr view` per cycle, diffed against the
+previous observation that the cursor carries, plus — while the PR is open —
+one read-only `gh api graphql` query for `reviewThreads { isResolved }`,
+which `gh pr view --json` cannot return (no bodies are requested). `report <id> done --pr
+<url>` registers the same watch owned by `dispatch:<id>` (idempotent;
+`--no-watch` opts out). **Owner:** `packages/core/src/pr.ts` (derivation,
+badge) and `apps/cli/src/pr-watch.ts` (check, registration, evidence).
+
+| Word | Meaning |
+| ---- | ------- |
+| `pr:` key | `pr:<owner>/<repo>#<n>` — one watch per PR. |
+| cursor | The last observation (head sha, per-check conclusions, review decision, merge state, draft, state), base64url-encoded. An unchanged PR re-emits nothing and returns the same cursor. A new head sha resets check memory. |
+| `check-completed` | A check reached a conclusion on the current head (`name`, `conclusion`, `detailsUrl`). Failing → work; passing → evidence only. |
+| `review-decision` | The review decision changed (`value`). Work, unless `[pickup.github]` covers the repo — then pickup's feedback rule owns it ([pickup.md](pickup.md), "Feedback pickup"). |
+| `merge-state` | `mergeStateStatus` changed (`value`). Evidence only. |
+| `draft` | Draft flipped (`value`). Evidence only. |
+| `merged` / `closed` | Terminal; the check sets `done`, and the watch retires once delivered. |
+| evidence `pr` | `{ url, number, state, draft, reviewDecision, mergeStateStatus, headSha, checks: { total, passed, failed, pending }, review: { unresolvedThreads, changesRequested, lastReviewAt }, observedAt }`. `review.changesRequested` comes from `reviewDecision` or any reviewer's latest decisive review; `unresolvedThreads` from the GraphQL query, omitted for an observation where that query failed. Comment bodies are never stored. The object is merged into the owning dispatch's evidence on every observation. `prBadge` derives the one-word state that tend, `catch`, and the glass show: `merged`, `closed`, `draft`, `conflicts` (`DIRTY`, filled GitHub red, ahead of checks and review), `checks n/m failed`, `changes requested`, `n unresolved`, `checks n/m` (pending), `behind` (`BEHIND`, grey; not an attention kind), `review`, `green` (only for a mergeable merge state), `blocked`, `merge unknown`. |
+| PR record | `~/.lobstah/prs/<owner>__<repo>__<n>.json` — the PR's latest observation keyed by the PR, not by a dispatch: the evidence `pr` object plus `key`, `repo` (`<owner>/<repo>`), and `dispatches` (the ids whose watch observed it; empty for a human's or a culled PR). **Owner:** `packages/core/src/prs.ts` (`upsertPr`, `readPrs`); the one writer is the preset's observation path (`observePr`), on every observation, man-owned or dispatch-owned — a dispatch-owned one also stamps that dispatch's evidence, which stays the per-dispatch view. Tend's `pr:*` kinds and `pr:ready` stack suppression, the glass PRs tab and stacks, the merged/closed notice, and PR acks read records first and fall back to dispatch evidence only for a PR with no record yet. `cull` removes records merged or closed longer than its window, never open ones. |
+
+Every event carries `headSha`. A dispatch-owned PR watch emits only work
+events (a failing check; a review decision pickup doesn't own), so the
+`owner` row is unchanged: its events always fork. 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 man-owned PR watch (no `--for`) delivers as attention only what needs a
+human (`manEvents`, beside `workEvents` in `apps/cli/src/pr-watch.ts`): a
+failing `check-completed`, and a `review-decision` turning to
+`CHANGES_REQUESTED`. Green checks, draft toggles, merge-state changes, and
+approvals go to the PR record only — they show as `pr:*` kinds and in the
+glass, never as `watch` attention.
+
+One carrier per event kind:
+
+| Event | Carrier |
+| ----- | ------- |
+| `check-completed`, failing | dispatch-owned: a continuation (pick); man-owned: a `watch` attention event |
+| `review-decision` | dispatch-owned: a continuation unless pickup owns review feedback; man-owned: a `watch` event only for `CHANGES_REQUESTED` |
+| `check-completed` green, `draft`, `merge-state`, approvals | the PR record (and the owner's evidence) only |
+| `merged`, `closed` | a `pr-merged` / `pr-closed` notice from the record transition only |
+
+Pick stays the single writer of watch progress. The inline poller (`man
+wait`, the helm park) runs PR checks for man-owned watches as usual, and
+only **observes** dispatch-owned ones: it writes the PR record and the
+evidence `pr` object (and so the merged notice) and never advances their cursor or consumes
+their events, so pick still sees and forks every one.
+
 ## Soaking contract
 
 A **trap** is a worktree that volunteered as a worker seat through
@@ -152,7 +223,7 @@ refused (the session lock); a stale one is adopted.
 
 | Word | Meaning |
 | ---- | ------- |
-| `soak` | Sign the worktree's trap on: it parks at turn end (Stop hook) and takes matching work. `--session` only on first sign-on; re-runs infer everything from the anchor file. `--one` stows after the first catch. `--wait` parks in the foreground — the hookless path: work prints plain, a quiet timeout exits 3, re-running re-arms. Workers never run `man` verbs. |
+| `soak` | Sign the worktree's trap on and take matching work. `--session` is needed only on first sign-on. `--one` stows after the first catch. `--wait` registers a watcher and waits for work; a quiet timeout exits 3. Workers never run `man` verbs. |
 | `stow` | Sign the trap off (run it in the worktree); an open catch requeues (a cancelled one finalizes as failed) and unread messages bounce to the helm. A trap always stows itself freely; stowing someone else's (`--wt`) is steering — the claimed helm's alone. Stow closes the seat, never the session: an opted-in session can only be asked to stop, and a still-looping worker re-enlists visibly (`trap-signed-on`). |
 | address | `--for wt:<trap>` targets one trap; `session:<id>` is an alias resolved to the trap at dispatch time. **Sticky:** addressed work is never the daemon's — it waits for its trap; an orphan (trap gone) surfaces as a `bait-orphaned` notice for the helm to re-address, release, or cancel. Delivery stamps a receipt (`deliveredTo`/`deliveredAt`) into evidence. Unaddressed work defers to a parked matching trap for `[soak].deferSecs`, then the daemon spawns headless. |
 | message | `send wt:<trap> "<text>"` — a conversational continuation, not work: no branch, no catch, no report obligation. Delivered before bait at the trap's next park, stamped with its sender (`helm` / `session:<id>` / `terminal`); undeliverable messages bounce to the helm as notices. |
@@ -182,11 +253,63 @@ verbs stay open. A stale helm reserves nothing.
 
 | Word | Meaning |
 | ---- | ------- |
-| `helm` | Sign a session on as the orchestrator for one grounds. Prints the charter, arms the Stop-hook park without a marker file, and gates the periodic digest. Re-running from the same session is an idempotent re-sign. |
+| `helm` | Sign a session on as the orchestrator for one grounds. Prints the charter and enables the Stop hook without a marker file. Re-running from the same session is an idempotent re-sign. |
+| watcher registration | `~/.lobstah/watchers/<session-id>.json` stores a `man wait` or `soak --wait` process's PID and heartbeat. The waiter refreshes it while running and removes it on exit; a heartbeat older than five seconds is stale, and a second waiter for the same session refuses. |
+| `man haul --park` | Make the Stop hook wait for attention while work is in flight. `[helm].park = "block"` selects the same mode. In arm mode, the hook allows a stop with a live watcher or blocks with the arm command. |
 | `relieve` | Step down. `--take` on another session's `helm` is the only force path: it displaces a live holder deliberately and leaves them a stand-down notice, delivered once at their next park. A holder whose heartbeat lapsed past `[helm].ttlSecs` is stale and claimable without `--take`. |
 | grounds | A named territory: the subset of configured repos one helm oversees, from `[grounds.*]`. A repo belongs to at most one grounds (config error otherwise). No grounds configured means one implicit `fleet` grounds covering every repo. |
 | charter | The helm's persona and scope fences, in Standard Technical English. Printed at sign-on and re-injected by `man brief` at every session start, so it survives restarts and compaction. |
-| digest | The delta since the reported-through cursor: catches landed, attention arisen, still-waiting, fleet verdict. Carried by `man report`, a `man wait` timeout, and — for a helm session, at `[helm].reportSecs` cadence — the park itself. Change-gated: an empty delta is never delivered. |
+| digest | The delta since the reported-through cursor: catches landed, attention arisen, still-waiting, fleet verdict. Carried by `man report`, a `man wait` timeout, and — in blocking park mode, at `[helm].reportSecs` cadence — the park itself. Change-gated: an empty delta is never delivered. |
+
+## Attention contract
+
+**Attention** is what stands waiting for a human to look: `man tend`'s
+`attention` list, which the desktop pet and the glass walk across the
+screen. It is derived in one place (`apps/cli/src/tend.ts`) and nowhere
+else. **Owner:** `apps/cli/src/tend.ts`. **Enforcement:** `attentionKinds`
+in `config.toml` selects the kinds (an unknown kind is a config error);
+every kind is level-triggered — it stands until its own clear condition,
+never until someone acknowledges it.
+
+| Kind | Stands while | Clears when |
+| ---- | ------------ | ----------- |
+| `question` | The dispatch's last status is `needs-decision` or `blocked`. | Any newer status entry. |
+| `landed` | The dispatch is `done` or `failed` after its grounds' reported-through cursor (the grounds listing the repo, else `fleet`; at most 24 h back). Opt-in. | `man report` (or the helm park's digest) advances the cursor. |
+| `pr:draft` | Evidence `pr` is open and draft. | Ready for review, merged, or closed. |
+| `pr:review` | Evidence `pr` is open with `review.unresolvedThreads > 0` or `review.changesRequested`. | Every thread resolved and no changes requested, or merged / closed. |
+| `pr:checks` | Evidence `pr` is open with a failed check on the observed head. | Green on the head, or merged / closed. |
+| `pr:conflict` | Evidence `pr` is open and `mergeStateStatus` is `DIRTY` (GitHub: conflicting with its base). | The merge state leaves `DIRTY` (rebased or merged clean), or merged / closed. |
+| `pr:ready` | Evidence `pr` is open, not draft, no `pr:review` condition holds, `mergeStateStatus` is mergeable (`CLEAN`, `HAS_HOOKS`, or `UNSTABLE` — the last only means non-required checks are red, which `pr:checks` already carries), and it is approved — or every check passed with none pending. `DIRTY`, `BEHIND`, `BLOCKED`, and `UNKNOWN` never yield ready. | Merged or closed (or a review condition arises, or the merge state stops being mergeable). |
+
+`pr:*` kinds read only the `pr:` watch's evidence — never a forge call —
+and carry `prUrl`, `number`, and the fields they derive from. Unconsumed
+man-owned watch events also list, as `watch`: machinery wakes, always on.
+Only `question` and `watch` make the verdict `needs-attention` or arise in
+the digest; the rest are things to look at, not stalls.
+
+**The on-the-hook rule.** A `pr:review` or `pr:checks` item is suppressed
+while a worker owns the problem: a queued or active dispatch in the PR's
+chain (the evidence owner and its `followUp` descendants) that is a pickup
+feedback round — pickup's map records it with kind `review` — or the `pr:`
+watch's fix continuation — the watch records it as `lastFollowUpId`. It
+reappears when that dispatch finishes without clearing the condition.
+`question`, `landed`, `pr:draft`, `pr:conflict`, and `pr:ready` are never
+suppressed — a rebase is the human's or the helm's call, never assumed to be
+the fix continuation's.
+
+**Answered questions.** A `question` stands only while no message to the
+dispatch is newer than its latest `needs-decision` / `blocked` entry. A
+message counts when it carries provenance: `sendMessage` writes a
+`NNN.meta.json` sidecar `{ from, at }` beside each `NNN.msg` (`from` is
+`helm`, `session:<8>`, `terminal`, `tracker:<source>`, or `node`), and
+`acknowledge` moves it into `handled/` with its message. Any sender counts;
+a record without a sidecar (written before provenance existed) never does;
+the sidecar's `at` decides, never file mtime. `man wait`, the park, and the
+reminder loop apply the same predicate.
+
+| Word | Meaning |
+| ---- | ------- |
+| ack | `~/.lobstah/acks/<item-key>.json` — `{ key, kind, stateHash, at, by }`, written only by `lobstah attention ack` (removed by `unack`, by the CLI's `man tend` / `attention` when its `stateHash` goes stale, and by `cull` when the item is gone). **Display-only**: it hides the item from the desktop pet and the glass lobs while the item's `stateHash` is unchanged; `man tend --json` keeps the item with `acked: { at, by }`, and `man wait`, the park, reminders, and `notifyCommand` never read acks. Item keys: `<lane>:<uuid>` (question, landed), `pr:<owner>/<repo>#<n>` (all of a PR's `pr:*` kinds — one ack covers them), `watch:<key>`. `stateHash` covers the status entry (question, landed) or the PR's head sha plus every evidence field a `pr:*` kind stands on (not `observedAt`). |
 
 ## Exit codes
 

package/package.json

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