lobstah 0.5.13 → 0.6.0

package/docs/man.md

@@ -54,12 +54,13 @@ the background, dispatch it with the `lobstah` CLI instead of doing it inline:
 - `lobstah status [<id>]`, `lobstah ls` — check progress when I ask, not on a loop.
 - `lobstah send <id> "<instruction>"` — steer a live dispatch, add to a queued
   dispatch's inbox, or wake a finished chain as a follow-up. Sending to any
-  member of a finished chain follows up its newest member. Use `--no-wake` to
-  leave a message in a finished inbox without starting work (nothing reads it).
-  A new follow-up accepts `--harness`, `--model`, and `--for wt:<trap>`.
+  member of a finished chain follows up its newest member. To choose a new
+  worker, harness, or model, use `lobstah dispatch --follow-up <id> --repo
+  <key> --brief-text "<instruction>" --for <name> --harness <kind> --model <m>`.
 - `lobstah cancel <id>` — stop one.
-- A dispatch reporting `needs-decision` is waiting on ME — surface its question
-  immediately, then `lobstah send` my answer.
+- A dispatch reporting `needs-decision` or `blocked`: when the brief or your
+  context gives the answer, `lobstah send` it and tell me what you decided;
+  when the choice is mine, frame it with `lobstah man ask <id>` for me to answer.
 - `done` means brief fulfilled with a branch + commits; report the evidence
   (`~/.lobstah/state/<id>.evidence`) and never merge anything yourself.
 ```
@@ -96,6 +97,11 @@ finished member. If that member was last claimed by a trap still signed on,
 the follow-up returns to that trap unless `--for` overrides it. Otherwise it
 is unaddressed for a headless worker.
 
+A send to a dispatch expects a reply. The worker's next note after the send
+wakes `man wait`: a `working` or `paused` note arrives once as a `reply` event
+with the note and the sent instruction's first line, and any other verb wakes
+as itself. `--no-reply` sends without expecting a reply.
+
 Attach refuses while a dispatch is `working` (two writers, one session);
 follow the logs or `send` instead, or cancel and then attach.
 
@@ -149,17 +155,57 @@ review, a deploy) reports `paused "<note>" --waiting-on review --link <url>`
 before it waits. Tend, `status`, `ls`, and the glass then show
 `paused: waiting on review` with the link and the time waited. It is a
 state, not a question: nothing to answer, no attention, no pet. A paused
-headless worker is never counted as wedged and its wall clock stops, but it
-still holds a `maxConcurrent` slot while its process is alive. A paused
-trap is kept out of the ghost sweep until `--until` or
-`[soak].pausedTtlSecs` (24 hours). See [Waiting on](vocabulary.md#waiting-on).
+headless worker is never counted as wedged and its wall clock stops.
+
+A paused headless dispatch is **parked**. When the worker's turn ends on
+`paused`, the runner ends the session, stops what the harness started,
+and exits. The dispatch stays active and keeps its worktree lock, but it
+holds no `maxConcurrent` slot and runs no process. It wakes into the same
+session when an operator message reaches its inbox (`lobstah send <id>`)
+or when its `--until` time passes, as soon as a slot is free; a waking
+dispatch takes the slot before queued work. The first prompt of the woken
+session says why it woke and carries the messages. A parked dispatch
+counts in the status output, without a slot:
+
+```
+$ lobstah man tend
+active: headless: 1 of 2; traps: 0; parked: 1 (no slot)
+parked (no slot)[1]{id,waitingOn,for,link,note}:
+  6a1f0c2e,review,80m,https://github.com/o/r/pull/7,waiting for approval
+$ lobstah daemon status
+slots: 1 of 2 work in use, 1 free
+parked: 1
+parkedOn: 6a1f0c2e waiting on review for 80m https://github.com/o/r/pull/7
+```
+
+`lobstah doctor`'s `daemon` row ends in `parked: 1, no slot (…)`, and the
+glass header shows `parked: 1 (no slot)`. A worker that reported `done` or
+`failed` holds no slot: its runner exits within `[limits].exitGraceSecs`,
+and a restart of the daemon does not wait for it (see [status
+verbs](vocabulary.md#status-verbs)). A parked dispatch has no runner, so a
+restart does not wait for it either. A paused trap is kept out of the ghost
+sweep until `--until` or `[soak].pausedTtlSecs` (24 hours). See [Waiting
+on](vocabulary.md#waiting-on).
+
+**A PR's end finishes the waits on it.** When the PR a dispatch waits on
+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.
 
 ### PR state after done
 
-A dispatch reports `done` when its PR opens; `report done --pr <url>`
+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). What you get depends on what runs:
+opts out). A trap's PR is tracked from its first push. 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`,
@@ -177,15 +223,25 @@ succeeds and the watch's check records `lastError`.
 
 Which commands register a watch. Only these write points register one:
 
-- `lobstah report <id> done --pr <url>` registers the watch for the PR the
-  worker just opened.
+- `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> paused --waiting-on pr|review` registers the watch
+  for the dispatch's own PR. A `--link` to another PR registers nothing.
+- `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.
 - `lobstah watch add <key>` registers the watch you name.
 - `lobstah watch backfill --apply` registers watches for PRs in old dispatch
-  history. Without `--apply` it only lists them. Nothing runs it for you.
+  history, and fetches the title of each PR record that has none (one
+  `gh pr view --json title` per record). Without `--apply` it only lists
+  them. Nothing runs it for you.
 
 Read commands never register a watch: `catch`, `man tend`, `status`, `ls`,
-`prs`, `prs sync`, `attention`, and the glass. They read PR records and
-watches that already exist. `prs sync` refreshes existing PR watches only.
+`prs`, `attention`, and the glass. They read PR records and watches that
+already exist. Use `watch check-pr <key>` to force one PR-watch refresh.
 
 The first check of a new watch is a baseline:
 
@@ -207,16 +263,99 @@ and requested review changes. It follows up the newest dispatch in the PR's
 chain. A conflict brief names the PR's base branch, including a stacked
 base. A check brief names each failed check and its details URL. The watch
 records each attempt and stops at `[watch].maxRepairsPerPr` per head SHA.
+Each failing check gets at most one repair round per PR and head SHA; the
+PR record's `repair.checks` lists the checks that had their round. The
+same rule holds for CI-fix continuations from `lobstah pick`.
+
+**Human gates.** A check that fails until a person approves the change is
+a human gate. It gets no repair round and no CI-fix continuation on that
+PR. Two sources name gates: `[repos.<key>].humanGateChecks` in the config,
+and a worker's `lobstah report <id> <verb> --human-gate "<check>"` (once
+per check). The report records the gate in the worker's evidence
+(`humanGates`) and on the PR record (`humanGates`). A check brief lists
+the failing gates and tells the worker to name a gate it finds. A PR whose
+only failing checks are human gates shows `repair.status: waiting` with
+`heldBy: human-gate`.
 It does not repair a PR with a person's newer commits or uncertain commit
 ownership, a terminal PR, or a PR whose chain already has queued or active
 work. `[watch].autoRepair`, `conflicts`, and `checks` control this behavior.
 
+Daemon repairs run in the `chore` lane and use `[limits].choreConcurrent`.
+A repair for a trap-built PR is addressed to its owning live trap. If the
+trap is busy, the chore waits for up to `[watch].repairTrapWaitSecs`
+(default 600). It then runs headless in its own checkout of the PR branch.
+A repair for a headless-built PR runs headless and reuses its origin
+worktree when that checkout is clean and free. A headless chore never uses
+a trap's worktree. Only daemon-created repair chores have this bounded
+addressed fallback. Work addressed by a person stays addressed until the
+person releases or redirects it. `man tend`, `daemon status`, `doctor`,
+and the glass show the repair's PR, chore lane, worker, and trap wait.
+
+**A repair waits** while any of these is true:
+
+- A live worker holds the PR's head branch. A live worker is an active
+  headless dispatch, or a trap with an open catch. It holds a branch when
+  its worktree has the branch checked out, when its current branch tracks
+  the branch on the remote, or when it pushed the branch during its current
+  dispatch. It holds a PR when its evidence names the PR or its chain owns
+  the PR.
+- A live worker holds the head branch of an open PR below this PR in the
+  same stack. The stack is the one the glass shows: a PR's parent is the
+  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 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
+  PR's watch. `lobstah watch hold <key> [--for <id>]`
+  holds one PR's watch; with `--for`, the hold ends when that dispatch
+  ends. `lobstah watch release <key>` ends any hold.
+
+A waiting repair is recorded on the PR record as `repair.status: waiting`,
+with `heldBy` (`wt:<trap>`, `dispatch:<id8>`, `helm`, `hold`, `settle`,
+`checks`, `human-gate`, or `repaired`) and `reason`. `repaired` means each
+failing check already had its round at this head; a new commit ends it.
+Unlike the other waits, `repaired` also raises `pr:checks` attention with
+its reason: the round did not fix the check. A wait is not an attempt: it does not count against
+`[watch].maxRepairsPerPr`. It raises no attention item. `man tend` lists it
+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.
+
+**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
+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
+would change behavior, the worker reports `needs-decision`.
+When the worker cannot push, it reports
+`failed "push rejected: <rejection text>; moved head <sha>"` and leaves the
+PR as it was. That report marks the PR's repair `blocked` at the moved head
+(no new repair starts on that head, nor on the head the repair started
+from) and posts a `push-failed` notice. A repair never opens a branch or a
+PR.
+
+Lobstah records pushes it sees in the dispatch's evidence (`pushes`): the
+runner's own pushes, a headless worker's `git push` commands, and a trap's
+`git push` commands (from its post-tool beat). It does not read GitHub to
+guess who pushed. A worker that is about to push to other PRs can hold them
+first with `lobstah watch hold <key> --for <its dispatch id>`.
+
 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
+empty). Each PR card, PRs tab row, and PR modal header shows the PR's title
+after its number; a stack line shows numbers only, with each title on hover.
+`lobstah prs` prints the title, cut to 60 characters. Every check reads the
+title again, so a rename on GitHub shows on the next check and is never
+attention. 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.
 
 **PR order.** Every PR list uses one order: the glass PRs tab, the On deck
@@ -241,6 +380,15 @@ 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.
 
+A question is held while a helm is signed on for its grounds and has not
+ended a turn since the question was filed. A held question is in `man tend`,
+`man wait`, the park, and reminders, and `lobstah attention` and `man tend`
+mark it `held`. It is not in `attention --json` (the pet), the glass, or
+notifyCommand. The question walks when the helm ends a turn (`man haul`)
+without answering it; the release is recorded in `releases/<key>.json`. With
+no helm signed on, or a helm relieved or stale past `[helm].ttlSecs`, a
+question walks at once.
+
 ### The spyglass
 
 The lobstah man skill brings up the glass when it takes the helm.
@@ -250,43 +398,195 @@ as a user service. `lobstah glass restart` restarts the service, or a
 detached glass (stop, then `--detach`).
 
 `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
+(default port 4949): the fleet verdict, decision cards, 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
+and the helm identified by name. Its tabs are On deck, Dispatches, Traps,
+PRs, Reports, and Notices. The Reports tab lists every report, unacked first,
+then newest first, and the repo filter and the search box (title, author,
+dispatch id, repo) apply to it. Reading the glass consumes no cursor. Each
+live trap has a **↗ open** button at the end of its foot line. It asks the local server to focus
+that trap's reported session link, iTerm2 session, Terminal tab, editor
+worktree, or recorded app, in that order. The result names the step that
+worked; app-only activation says the exact window is not known. On other
+platforms, only a session link can open. A signed-off trap has no button; the
+page shows its resume command as text to copy. The focus endpoint accepts
+only a trap id in a same-origin, token-protected POST. 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.
 
+On a card, the title and the badge share one line. The title shrinks first,
+with an ellipsis, but always keeps its PR number or 8-character id. A badge of
+12 characters or fewer always shows whole. A longer badge truncates only
+after the title is at its minimum, never below 12 characters. The meta line
+and the note show at most two lines. The full text of each is in its hover
+title.
+
+The On deck tab shows up to 8 traps. Signed-on traps come first, oldest
+sign-on first, with name breaking ties. Traps stowed or ghosted in the last
+hour follow, most recent sign-off first, with name breaking ties. A "+N more"
+link opens the traps tab for the rest, in the same order. Both views show each
+trap's current dispatch, last activity, or idle and waiting state. A dot leads
+that state line on the deck, the traps tab cards, and the traps tab table. The
+dot is green when the trap is working or idle and listening. It is amber when
+the trap is parked. It is grey when the trap is not listening (its heartbeat is
+stale) or signed off.
+
 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.
 
+### Reports
+
+A report is a markdown page of findings, with images, that a dispatch or
+the helm files to keep.
+
+- **Filing a worker report.** `lobstah report <id> done "<one-line note>"
+  --report <file.md> [--attach <file> ...]` (also `failed`). The page is
+  copied to the dispatch's state directory as `state/<id>/report.md`, beside
+  `attachments/`. `--attach` copies each file into that `attachments/`. An
+  image the page names by bare filename (`![tray](tray.png)`) resolves to
+  that directory. The note stays one line.
+- **Filing a helm report.** `lobstah man file <file.md> [--attach <file> ...]
+  [--title <text>]`. It is stored under the helm's grounds,
+  `reports/<grounds>/<rid>/`, with the same layout, and the author is `helm`.
+- **Title and author.** The title is `--title`, else the page's first `#`
+  heading, else the dispatch's brief title. The author is the trap name, or
+  `headless`, or `helm`. A file larger than `[limits].attachmentMaxBytes` is
+  refused, and nothing is filed.
+- **Finding one.** `lobstah reports` lists every report, newest first: key,
+  title, author, the dispatch or helm grounds, when it was filed, and
+  whether it is acked. `lobstah status <id>` and `lobstah catch <id>` print
+  `report: <path>` when the dispatch has one.
+- **In the glass.** The deck has a reports block after Landed: newest first,
+  unacked first, up to 8, then "+N more", which opens the Reports tab. A
+  report's card or row shows its title, then who filed it (a trap's name, a
+  headless dispatch's id, nothing for the helm), its age, and `acked`. A
+  dispatch's report renders as a
+  page at the top of its dispatch modal. A helm report opens in a modal of
+  its own; `#report/<key>` links to it. The page shows headings, lists,
+  tables, fenced code, links (in a new tab), bold, italics, and images.
+  Raw HTML in the markdown shows as text. The glass serves the markdown and
+  the images read-only, and an image only by basename from that report's
+  own attachments.
+- **Images.** Every image in the glass (a decision card's, a report page's,
+  and an attachment's in the dispatch and trap modals) opens in an in-page
+  overlay: centered at up to 90% of the viewport over a dark backdrop, with
+  a link to open the original file. Escape, a click on the backdrop, or the
+  close button closes it. The glass serves a dispatch's and a trap's
+  attachment images read-only, by basename, from their own attachments
+  directories. Missing files, malformed names, and symlinks are not served.
+- **Attention.** A filed report with no ack stands as the `report` attention
+  kind. Add `report` to `attentionKinds` to walk it. The desktop pet shows
+  the report's title; a pet click opens the item and acks it through
+  `lobstah attention ack <key> --by pet`. The pet's Acknowledge menu entry
+  acks without opening, and `lobstah attention ack <key>` acks a report
+  whether or not `report` is in `attentionKinds`. Opening a report in the
+  glass does not ack it. A report filed by a follow-up dispatch acks the report
+  of each dispatch before it in the chain.
+- **Cull.** `lobstah cull` removes a dispatch's report with the rest of its
+  state. A helm report is culled when it is older than the retention window,
+  counted from when it was filed.
+
+### Decisions
+
+A decision is a question the helm puts to the human. Workers still ask in
+prose (`report needs-decision "<note>"`). The helm decides first. When the
+brief, the code, or its context gives the answer, it sends it with
+`lobstah send <id> "<answer>"` and says what it decided in its next report.
+When it lacks the context, or the choice is the human's (scope, product
+behavior, money, releases, merges, anything outward-facing or hard to
+undo), it frames a decision with `man ask`. The helm's own questions follow
+the same rule.
+
+- **Asking.** `lobstah man ask [<dispatch-id>] --title "<question>"
+  [--detail <file.md>] [--option "<label>"]... [--attach <file>]...` stores a
+  decision: its key (`decision:<rid>`), title, detail markdown (at most
+  64 KiB), 0 to 6 option labels, attachments, the dispatch it is about (none
+  for a question such as "cut 0.6.0?"), who asked (`helm`), and when. It is
+  stored in `~/.lobstah/decisions/<rid>/`: `decision.json`, `detail.md`, and
+  `attachments/`. The claimed helm alone may ask.
+- **Standing.** A decision stands until it is answered or the helm withdraws
+  it with `lobstah man ask --withdraw <key>`, which removes its directory. A
+  newer `man ask` on the same dispatch replaces the older decision.
+- **Attention.** A standing decision is attention of kind `decision`, in
+  the default `attentionKinds`. It makes the verdict `needs-attention`. A
+  worker's raw `needs-decision` or `blocked` stays a `question` until the
+  helm frames it. While a decision on the same dispatch, asked at or after
+  the question, is on disk, the `question` item is hidden: the decision
+  replaces it. Withdrawing the decision shows the question again.
+- **In the glass.** The attention section of On deck is a list of
+  full-width decision cards, newest first. A card shows the title, the
+  detail rendered as markdown, the attachments (images inline), the
+  dispatch link and repo, and the age. The options are buttons. Below them
+  is an empty text box that grows with its content, and an attach control
+  for images and files (`.png .jpg .jpeg .gif .webp .pdf .txt .md .csv
+  .json .log .diff .patch .yaml .yml .toml .zip`, each at most
+  `[limits].attachmentMaxBytes`, at most 8). Click an option, write an
+  answer, attach files, or any mix; one **Send** submits it. With no options,
+  the text box is the whole answer. After sending, the card shows
+  `answered · <what was chosen>` and leaves on the next refresh. A raw
+  `question` the helm has not framed shows as a plain card with the
+  worker's note and the same text box. PR kinds stay in the PRs section.
+  `#decision/<key>` opens the deck at that card. Pasting with Cmd-V or
+  Ctrl-V in the text box adds each image on the clipboard as an attachment
+  named `pasted-<time>.png` (the extension follows the image format), with
+  the same size, type, and count checks as a picked file; pasted text stays
+  text.
+- **The answer is a request.** An answer is a glass request of kind
+  `decision-answer`, stored as `~/.lobstah/requests/<id>.json` with its
+  files in `~/.lobstah/requests/<id>/`. The payload is the decision `key`,
+  `title`, `dispatch`, `lane`, `repo`, the `option`, the `text`, and the
+  stored `attachments`. `answer.json` in the decision's directory marks it
+  answered and names the request.
+- **The POST.** Send is a same-origin POST to `/requests` with the page's
+  token (header `x-lobstah-token`), the guard the **↗ open** button uses.
+  The body is `{ "kind": "decision-answer", "payload": { "key", "option",
+  "text", "files": [{ "name", "data" }] } }`, with file data in base64. The
+  server checks the kind, the key, that the option is one of the decision's
+  labels, the text length (at most 20000 characters), and each file's size
+  and type (an image must also start with its format's signature). It
+  writes the request and runs nothing. Answering a raw question's key
+  (`<lane>:<id>`) first stores it as a decision asked by `worker`.
+- **The event.** Writing the request posts a `decision-answer` notice. It
+  wakes the helm's `man wait` (and the Stop-hook park) once, as a
+  `decision-answer` event: the request `id`, `key`, `dispatch`, `title`,
+  `option`, `text`, `attachments` (the stored paths), `from`, and `at`. The
+  helm acts on it, usually with `lobstah send <dispatch> "<instruction>"`.
+  Answering does not message the worker.
+- **From the terminal.** `lobstah man answer <key> [--option <label>]
+  [--text <text>] [--attach <file>]...` answers the same way, with the same
+  checks.
+- **The pet.** The desktop pet shows a decision as its title only. A click
+  opens the glass at the card and acks the item for the pet
+  (`lobstah attention ack <key> --by pet`). The card stays in the glass until
+  the decision is answered or withdrawn.
+- **Cull.** `lobstah cull` removes a decision once its answer is older than
+  the retention window, with the `decision-answer` request and its files. A
+  standing decision is never culled.
+
 ### 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
+verdict. It advances a "reported through" cursor when it prints, 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.
+A catch is reported once the helm's `man wait` watcher delivers its event or
+`man report` prints it. The glass's `unreported` badge means no helm received
+that catch. A `man wait` timeout and `man wait --peek` only peek at the delta;
+a digest lost with a dead background task re-surfaces on the next timeout.
+The Stop-hook's standing-attention reminder does not mark a catch reported.
 
 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 wait loop.** A delivered `man wait` event (exit 0) advances the helm's
+  cursor through the event time. A timeout (exit 3) prints the delta when
+  something changed without advancing the cursor — see the loop idiom below.
 - **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.
@@ -357,6 +657,12 @@ before the worker reads it; `man tend` then shows the dispatch as
 A newer `needs-decision` from the worker stands again. Set `remindSecs = 0`
 for pure at-most-once.
 
+A send still waiting on its reply stands in the `man haul` block as
+`sent · <id> · <first line> · <age>`. It is listed once, then every
+`remindSecs` until the worker's next note answers it. `man tend` shows it on
+the dispatch as `awaiting reply · <age>`, and the glass dispatch modal shows
+it under the inbox.
+
 **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
@@ -486,6 +792,8 @@ lobstah soak --wait             # hookless sessions: listen in the foreground
                                 # (re-runs need no flags — identity is the
                                 # worktree, else the session id); exit 3 =
                                 # quiet, run it again
+lobstah soak --link <url>       # store this session's link for the glass's ↗ open button
+lobstah focus <trap>           # focus a live trap from the CLI
 lobstah stow                    # sign off; an open catch requeues, unread
                                 # messages bounce back to the helm; removes
                                 # the worktree when soak created it
@@ -493,6 +801,14 @@ lobstah stow --keep             # sign off and keep the worktree
 lobstah soak --name amber-gull  # choose or change this trap's two-word name
 ```
 
+`--link` accepts a Claude desktop session URL under `claude://claude.ai/`,
+a VS Code extension URL of the form
+`vscode://anthropic.claude-code/open?session=<id>`, or a Codex task URL of
+the form `codex://threads/<task-id>`. It rejects all other schemes and
+malformed links. The glass checks a stored link again before rendering it.
+`lobstah focus <trap>` accepts the trap id with or without `wt:` and reports
+the focus step or why it could not focus. It does not revive a signed-off trap.
+
 **Soak can create the worktree.** From a repo's primary checkout, or with
 `--repo <key>` from outside any configured repo, soak creates a linked
 worktree the same way a dispatch does. It fetches trunk, adds
@@ -523,8 +839,9 @@ worktree's HEAD commit and branch in evidence.
 `stow` removes a worktree only when soak created it and nothing in it exists
 elsewhere. It keeps the worktree and prints `worktree: kept` and a `reason:`
 when soak did not create the worktree, or when the worktree has uncommitted
-changes, untracked files that are not ignored, or commits on no remote
-branch. Ignored files do not block removal. Stow never forces a removal.
+changes, untracked files that are not ignored, commits its upstream lacks,
+or no upstream. Ignored files do not block removal. `stow --force` explicitly
+allows removal of unsaved checkout files; `--keep` still keeps the checkout.
 Stow runs the removal from the primary checkout, so it works from inside
 the worktree. On removal it prints `worktree: removed`, `path:`, and
 `returnTo: <primary checkout>`, with a help line `cd <primary>`. It
@@ -533,6 +850,8 @@ upstream: on some remote branch);
 otherwise it prints `branchKept: <branch> (<reason>)`. A deleted branch
 prints as `branchDeleted:`. `stow --wt <id>` follows the same rules. The
 SessionEnd hook (`lobstah stow --quiet`) signs off and keeps the worktree.
+Releasing a claim whose last report is `done` or `failed` moves it to `done/`;
+only an unfinished catch requeues (a cancelled catch finalizes as failed).
 
 **Identity is the worktree.** Sign-on anchors a short trap id and two-word
 name in `.lobstah-trap` and prints both, such as `amber-gull (wt:c32a245d)`; the address
@@ -545,6 +864,15 @@ same live trap in `dispatch --for`, `send`, and `stow --wt`. Unknown names
 list known names and never turn addressed bait into headless work. The id
 remains the key in dispatch and claim records.
 
+A dispatch shows its trap by name wherever it names the trap that claimed
+it, ran it, or is addressed to it, including notes such as
+`claimed by crisp-heron`. The name comes from the live registration, else
+from the name registry, so a signed-off trap keeps its name. A trap with no
+known name shows as `wt:<id>`. `lobstah status <id>` and `lobstah catch <id>`
+print `trap: crisp-heron (wt:68c5da5f)` and write notes the same way.
+`man tend`'s tables print the name alone. In the glass, the name carries
+`wt:<id>` as its hover text, and a click opens that trap's modal.
+
 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
@@ -574,14 +902,118 @@ resolves the trap from the working directory, else from the session id. A
 trap that works for an hour without reporting is not swept while it beats.
 `[soak].beat = false` turns the hook off.
 
+`lobstah soak` prints `title: <trap name>` at sign-on. When `soak --wait`
+delivers work, it prints `title: <name> · <short first brief line>`.
+`report done` and `report failed` print `title: <trap name>` again. The
+brief text has control and terminal escape sequences removed and is capped
+at 40 characters. A trap skill sets an available session-title tool to each
+printed title, without retrying a refusal. Stow leaves the current title
+in place.
+
 Liveness has two failure shapes with two remedies: a registration that
 parked before and went quiet (no park, report, or beat) past `[soak].ttlSecs` is a **ghost trap** —
-swept, catch requeued, noticed, its worktree kept; one that **never parked** is a **defective
+swept and noticed. An unfinished catch requeues; a `done` or `failed` catch
+finalizes in `done/`, never becoming orphaned bait. A soak-created worktree
+is removed only when Git verifies a clean checkout with no commits absent
+from its upstream. Dirty, unpushed, no-upstream, or unreadable checkouts stay.
+The ghost notice includes the path, branch, modified-file count and
+unpushed-commit count (or `unknown` when inspection fails). Other worktrees
+stay in place. After the daemon's own tick gap exceeds `[soak].ttlSecs`,
+it grants a full TTL after resume before sweeping any traps, allowing
+sessions to renew their heartbeats. 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.
 
+### Reserving a trap before its session starts
+
+```bash
+lobstah trap reserve --repo <key>       # reserve a trap; prints its name, id, and a one-time ticket
+        [--harness claude|codex]        # print only that harness's start command
+        [--name amber-gull]             # choose the name
+        [--deadline 180]                # seconds the session has to sign on (default 180)
+lobstah soak --ticket <ticket>          # in the new session: sign on as the reserved trap
+lobstah stow --wt amber-gull            # withdraw a reservation no session has redeemed
+```
+
+`trap reserve` picks the two-word name and the `wt:` id before any session
+exists and writes a **starting** reservation (`soaking/<id>.starting`) with a
+deadline. `dispatch --for <name>` works on it at once: the work waits, as it
+does for any addressed trap. `man tend` and the glass show the trap as
+`starting`.
+
+The output holds a one-time ticket and the command that starts the session in
+the repo's primary checkout:
+
+```bash
+cd <repo> && CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 claude "/lobstah:soak --ticket <ticket>"
+cd <repo> && codex '$lobstah:trap soak --ticket <ticket>'
+```
+
+Nothing starts the session for you: a person runs the command. The session's
+soak redeems the ticket, from `--ticket` or from the `LOBSTAH_TRAP_TICKET`
+environment variable. It creates a worktree named after the reserved id,
+signs on under the reserved name and id, and deletes the reservation. The
+ticket then redeems nothing. A spent ticket left in `LOBSTAH_TRAP_TICKET` is
+ignored; a spent `--ticket` is refused, except in the session that redeemed
+it. A session that already mans a trap cannot redeem a ticket.
+
+A reservation still unredeemed at its deadline **fails**: the daemon posts one
+`trap-start-failed` notice, and the glass shows the trap as `start failed`
+with the reason. Work addressed to it stays queued. The ticket still redeems
+after the deadline. `lobstah stow --wt <name>` withdraws the reservation; its
+addressed work is then orphaned bait and the helm gets a `bait-orphaned`
+notice.
+
+### Asking for a trap from the glass
+
+The Traps tab and the deck's traps block have a **+ New trap** button. It
+opens a small form: a repo (from the configured repo keys) and a harness
+(`claude` or `codex`). Submitting it files a **trap request**: the glass POSTs
+`{ kind: "trap-request", payload: { repo, harness } }` to `/requests` with
+the same same-origin and page token guard as the open-window button. The
+server checks the repo and harness, writes `~/.lobstah/requests/<id>.json`
+(kind `trap-request`), and runs nothing. `/requests` refuses a body larger
+than eight attachments (`[limits].attachmentMaxBytes` each, as base64) plus
+room for text, with 413. After it reads the kind, it refuses a `trap-request`
+larger than 4 KB with 413.
+
+A request wakes the helm's `man wait` (and the Stop-hook park) as a
+`trap-request` event with the request's id, repo, and harness. An open
+request also wakes a helm that signs on later. The glass shows it at once as a
+greyed card: `requested · <repo> · <harness> · waiting for the helm`, or
+`waiting for a helm` when no helm is signed on.
+
+```bash
+lobstah trap requests                  # open trap requests
+lobstah trap reserve --request <id>    # reserve what the request asks for, and close it
+```
+
+`trap reserve --request <id>` takes the repo and harness from the request,
+records the request on the reservation, and closes the request. The card
+becomes the starting card, then the live trap when the session signs on.
+
+Every starting card shows the start command `trap reserve` prints, with a copy
+button: paste it into a terminal to start the session by hand. The ticket in
+it is kept in `soaking/<id>.ticket` (mode 0600) until the reservation is
+redeemed or withdrawn. The glass sends it only to a page on this machine's
+own glass address, only on the starting card, and no notice or log carries
+it.
+
+### The terminal tab name
+
+At sign-on, soak names the session's terminal tab after the trap. It finds the
+tab by the tty recorded in the registration's window: a Terminal.app tab gets
+the name as its custom title, an iTerm2 session gets it as its session name.
+Other terminals are left alone. `lobstah stow` clears the name.
+`LOBSTAH_TERMINAL_TITLE=0` turns naming off.
+
+Claude Code writes its own title to the tab, and in Terminal.app that title
+replaces the custom title. `CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1` on the
+command that starts Claude Code stops that for that one process; the start
+command `trap reserve` prints sets it. Codex also sets the terminal title.
+
 ### Culling and disk space
 
 Worktrees are 1 to 8 GB each. `lobstah cull` sweeps what is finished: `done/`
@@ -590,9 +1022,9 @@ whose dispatch is finished or gone, stale state files, merged or closed PR
 records, and orphaned acks. It never touches queued or active work, and
 `git worktree remove` keeps each dispatch's branch. A worktree that soak
 created counts as in use while a trap registration anchors it. After that,
-the cull and the daemon's retention and free-space culls treat it like any
-other worktree that no dispatch owns: it ages out after
-`[limits].retentionDays`. A worktree that follow-ups
+the cull and the daemon's retention and free-space culls can remove it only
+when the same clean-and-pushed safety check passes; unsaved soak checkouts
+remain protected even without a registration. A worktree that follow-ups
 reused is one worktree shared by the chain: it stays while any dispatch in
 the chain is queued or active, and it ages from the newest dispatch that
 used it.