lobstah 0.3.2 → 0.5.5

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: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: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`)
 
@@ -60,6 +62,28 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 | `deferSecs` | `90` | A soaking session whose park heartbeat is this fresh holds unaddressed matching bait — the daemon waits instead of spawning. Addressed bait (`--for session:<id>`) waits regardless, until the registration is gone. |
 | `ttlSecs` | `1800` | Heartbeat age past which a registration is a ghost trap: the sweep removes it and requeues its open catch (or finalizes a cancelled one as failed). A fresh `lobstah report` on the catch counts as liveness too. |
 
+## `[helm]` — the orchestrator seat (`lobstah man helm`)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `ttlSecs` | `1800` | Heartbeat age past which a helm registration is stale: the next `man helm` claims it without `--take`. The park and `man brief` heartbeat it. |
+| `reportSecs` | `900` | Minimum seconds between park-delivered digests for a helm session. The digest is also change-gated — quiet grounds deliver nothing regardless of cadence. |
+
+## `[grounds.*]` — helm territories
+
+One helm per grounds; a repo belongs to at most one grounds (`man helm`
+refuses on overlap or an unknown repo key). With no `[grounds.*]` configured
+there is one implicit `fleet` grounds covering every repo — the partition
+only exists when asked for.
+
+```toml
+[grounds.base]
+repos = ["homebase", "matcha"]
+
+[grounds.aequitas]
+repos = ["lobstah", "lavish"]
+```
+
 ## `[pickup]` — tracker loops (`lobstah pick`)
 
 | Key | Default | Meaning |

package/docs/design.md

@@ -444,7 +444,13 @@ 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`.
 
 ```ts
 // inside the runner

package/docs/lobsterman.md

@@ -18,6 +18,17 @@ The liaison never watches the workers — the daemon does that with no model in
 the loop. The liaison reads `lobstah status` when you ask, which is the
 token-efficiency point: supervision is a filesystem read, not a conversation.
 
+**The helm is harness-agnostic: drive the fleet from whichever session you
+prefer.** The contract is the CLI, not the harness — a Claude Code session,
+a Codex session (hooks since v0.114), or anything with a terminal via the
+foreground loop (`man wait` for the lobsterman, `soak --wait` for workers)
+holds the same seat with the same verbs. Workers are equally mixed:
+dispatches pick their harness per item (`--harness claude|codex`), so a
+Codex helm can run Claude workers and the reverse. Sign-on records which
+harness took the helm, and `swap` moves an in-flight dispatch across
+harnesses mid-stream — the worktree, not the conversation, is the durable
+layer.
+
 ## Set it up
 
 1. Install lobstah, configure your repos, start the daemon
@@ -95,6 +106,106 @@ 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`, `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:ready` (approved or all green) — 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
+(default port 4949): the fleet verdict and attention questions, every
+dispatch with its full brief, status log, inbox, and evidence, each trap
+with its lifecycle notices, message history, and catches, the notices
+tail, the merge view, and watches — with filters, a table/cards toggle,
+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. 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.
+
+### The periodic report
+
+`lobstah man tend` is the full picture on demand; `lobstah man report` is the
+**delta** since the last acknowledged report — catches landed (with their
+notes and PRs), attention newly arisen, what still waits, and the fleet
+verdict. It advances a "reported through" cursor when it prints — the
+explicit acknowledgment — so nothing is ever reported twice, and it says
+`no change` when the delta is empty rather than re-dumping state. Standing
+unanswered questions appear under `still-waiting` without counting as
+change — reminders (`remindSecs`) own re-firing those.
+
+Delivery is at-least-once by construction: the carriers that might not be
+read (a `man wait` timeout in a background task) only **peek** at the delta,
+so a digest lost with a dead task re-surfaces on the next timeout; only
+`man report` (or a hook-delivered park digest, which lands in-context by
+construction) marks it handled.
+
+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
+  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
+  `lobstah man report` and forwards the output when it is not `no change`.
+  Escalating a report to a human (a phone push) is the gateway layer's job,
+  not lobstah's.
+
+The loop idiom needs no harness scheduler, because the timer is lobstah's own
+blocking wait:
+
+```
+lobstah man wait --timeout 900
+# exit 0 → an event printed; handle it, then loop
+# exit 3 → timeout; the delta digest printed above it when something changed
+```
+
+A session running this loop reports into its own transcript whether or not a
+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
@@ -153,7 +264,7 @@ 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:
@@ -173,14 +284,16 @@ are preserved verbatim. What it writes:
 
 `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.
+only while dispatches are in flight — queued dispatches count. 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
+died mid-handling is still standing state — peek resurfaces it without
+consuming it, and returns at once with `standing: none` and exit 0 when
+nothing is; it never blocks, so it takes no `--timeout`), 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
@@ -196,8 +309,23 @@ Tier 3 is for a dedicated, long-lived liaison session.
 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.
+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.
 
 **Any-harness fallback — the wrapper loop.** Tiers 2 and 3 lean on Claude
 Code features (background-task notifications, the Stop hook). For any other
@@ -214,6 +342,48 @@ Zero tokens between events and works anywhere a shell does; the cost is that
 each event gets a fresh context rather than a continuing liaison
 conversation.
 
+## The helm: signing on as the orchestrator
+
+Soak enlists workers; `lobstah man helm` enlists the one who dispatches to
+them. Sign-on prints the **charter** — the persona and scope fences, written
+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.
+
+**One helm per grounds, enforced.** A **grounds** is a named territory: the
+subset of configured repos one orchestrator oversees (`[grounds.*]`; with
+none configured, one implicit `fleet` grounds covers every repo). A repo
+belongs to at most one grounds, so two orchestrators can never dispatch into
+the same territory. The registration is one file per grounds — the data model
+cannot hold two:
+
+- Sign-on against a **live** foreign holder refuses with guidance;
+  `--take` is the only force path, and it is deliberate: the displaced
+  session finds a stand-down notice at its next park and stops orchestrating.
+- A **stale** holder (heartbeat past `[helm].ttlSecs`) is claimable outright —
+  a dead orchestrator holds nothing.
+- `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 (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`
+  stay open to everyone; a stale helm reserves nothing. Workers never run
+  `man` verbs at all — their hookless park is `soak --wait`.
+- An identified `man wait` heartbeats the helm while it waits (waiting is
+  liveness) and defaults its digest to the helm's own grounds.
+- Consumption is grounds-partitioned: a helm's `man wait` and park consume
+  only events and notices for its own grounds' repos (events whose repo is
+  unknowable stay visible to all helms). Two helms never eat each other's
+  wakes.
+
 ## Soaking: a live session volunteers as a worker
 
 Workers are usually traps lobstah sets itself — fresh headless sessions in
@@ -223,25 +393,50 @@ 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)
-lobstah stow --session <id>     # sign off; an open catch requeues
+                                # (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
+lobstah stow                    # sign off; an open catch requeues, unread
+                                # messages bounce back to the helm
 ```
 
-The session id comes from the plugin's session-start brief (`lobstah man
-brief` announces it into the conversation). Once soaking, the same Stop hook
-that parks a lobsterman parks the worker: at turn end it waits for bait,
-claims it, and wakes with the brief. While it works a catch, the park wakes
-it for `lobstah send` messages and cancels instead.
-
-Routing follows ownership: `dispatch --for session:<id>` targets one trap;
-unaddressed bait for a matching repo prefers a parked trap for
-`[soak].deferSecs` before the daemon spawns headless; a watch continuation
-for a chain a soaking session claimed is addressed back to that session. A
-registration whose heartbeat lapses past `[soak].ttlSecs` is a **ghost
-trap** — swept, its catch requeued. Nobody is conscripted: only a session
-that ran `soak` ever receives work.
+**Identity is the worktree.** Sign-on anchors a short trap id in
+`.lobstah-trap` and prints the trap's address (`wt:<id>`); the address
+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. 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.
+
+Routing follows ownership, and **addressed work is sticky**:
+`dispatch --for wt:<trap>` waits for that trap and never falls back to a
+headless spawn — if the trap ghosts, the orphan surfaces as a helm notice
+(re-address, release, or cancel; `cancel` finalizes unclaimed queue items
+with an audit record). Delivery stamps a receipt into evidence. Unaddressed
+bait for a matching repo prefers a parked trap for `[soak].deferSecs`, then
+the daemon spawns headless. Conversational steering goes through
+`send wt:<trap> "..."` — a message, not bait: no branch, no catch, sender
+stamped, bounced to the helm when undeliverable.
+
+Liveness has two failure shapes with two remedies: a registration that
+parked before and went quiet past `[soak].ttlSecs` is a **ghost trap** —
+swept, catch requeued, noticed; one that **never parked** is a **defective
+enlistment** — noticed with its diagnosis (usually a missing Stop hook →
+`soak --wait`) and left standing so the address keeps protecting its work.
+Nobody is conscripted: only a worktree whose session ran `soak` ever
+receives work.
 
 ## What the daemon gives your liaison for free
 

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,13 @@ 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.
+
 ## 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 +120,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,28 +143,155 @@ 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. |
+| 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 **soaking trap** is a live interactive session that volunteered as a worker
-through `lobstah soak` — the validated write path; nothing else touches
-`soaking/`. Sub-agent workers are the traps lobstah sets itself; a soaking
-session is a trap already in the water, and dispatch drops bait into it
-before building a new one. **Owner:** `packages/core/src/soak.ts`.
-**Enforcement:** sign-on is refused from a repo's primary checkout (never
-claimable) and when another session already soaks the same worktree.
+A **trap** is a worktree that volunteered as a worker seat through
+`lobstah soak` — the validated write path; nothing else touches `soaking/`.
+Identity is **worktree-anchored**: `.lobstah-trap` in the worktree root
+holds a short stable id, the registration keys on it, and the address
+(`wt:<id>`) survives session restarts. The session id inside the
+registration is the liveness principal. **Owner:**
+`packages/core/src/soak.ts`. **Enforcement:** sign-on is refused from a
+repo's primary checkout, and a live foreign session in an owned worktree is
+refused (the session lock); a stale one is adopted.
 
 | Word | Meaning |
 | ---- | ------- |
-| `soak` | Sign a session on: it parks at turn end (Stop hook) and takes matching bait from the work queue. `--one` stows after the first catch. |
-| `stow` | Sign a session off; an open catch goes back to the queue (a cancelled one finalizes as failed). |
-| bait address | `--for session:<id>` on a dispatch targets one soaking session. Addressed bait waits for its trap until the registration is gone; unaddressed bait defers to a parked matching trap for `[soak].deferSecs`, then the daemon spawns headless. |
-| catch | The active dispatch a soaking session claimed (`claim.json` in the active dir). One catch per trap; one active item per worktree. The daemon never spawns or restarts it — the session's reports are its liveness. |
-| ghost trap | A registration whose heartbeat lapsed past `[soak].ttlSecs` — a lost trap that keeps fishing. The sweep hauls it out and requeues its catch. A fresh report on the catch keeps a mid-turn session out of the sweep. |
+| `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. |
+| `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. |
+| catch | The active dispatch a trap claimed (`claim.json`, `by: wt:<id>`). One catch per trap; one active item per worktree. The daemon never spawns or restarts it — the session's reports are its liveness. |
+| ghost trap | A registration whose heartbeat lapsed past `[soak].ttlSecs` **after having parked at least once**. The sweep removes it, requeues its catch, and posts a `trap-ghosted` notice; re-soaking the worktree restores the same address. A fresh report on the catch keeps a mid-turn session out of the sweep. |
+| 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. |
+| notice | The helm's attention channel for non-status events (`~/.lobstah/notices/`): sign-ons, first parks, sign-offs, ghosts, defective enlistments, orphaned work, bounced messages. 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; tend always shows the recent tail. |
 
 Delivery routes by ownership, same as watches: a continuation for a chain
-claimed by a live soaking session is addressed back to that session; once it
-ghosts, the same bait forks headless. Sessions are never conscripted — a
-thread works bait only after opting in.
+claimed by a live trap is addressed back to that trap and stays sticky.
+Sessions are never conscripted — a thread works bait only after opting in,
+and nothing addressed is ever silently rerouted.
+
+## Helm contract
+
+The **helm** is the orchestrator seat: one interactive session signed on as
+the lobsterman for its grounds through `lobstah man helm` — the validated
+write path; nothing else touches `helm/`. Soak enlists workers; helm enlists
+the one who dispatches to them. **Owner:** `packages/core/src/helm.ts`.
+**Enforcement:** one registration file per grounds — the data model cannot
+hold two; a live foreign holder refuses sign-on without `--take`. The rule
+is strict: once a helm is claimed, the orchestrator verbs that consume helm
+state (`man wait`, `man report`, the lobsterman park) are reserved for the
+helm session — any other caller is refused with guidance (or, for the hook,
+silently ignored). Read verbs (`man tend`, `man brief`) and the enlistment
+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. |
+| `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. |
+
+## 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:ready` | Evidence `pr` is open, not draft, no `pr:review` condition holds, and it is approved — or every check passed with none pending. | Merged or closed (or a review condition arises). |
+
+`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`, and `pr:ready` are never suppressed.
+
+**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.3.2",
+  "version": "0.5.5",
   "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
   "license": "MIT",
   "author": "aequitas labs LLC",