lobstah 0.5.11 → 0.5.13

package/docs/configuration.md

@@ -14,7 +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)). |
+| `attentionKinds` | `["question", "pr:ready", "pr:review", "pr:conflict", "pr:checks"]` | Which kinds `man tend`, the glass, and the desktop pet show. `pr:draft` and `landed` are valid opt-in kinds. An explicit list is used unchanged. Unknown kinds are errors. See the [attention contract](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
@@ -26,9 +26,11 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
 | `path` | yes | The git clone worktrees are allocated from (`~/` expands). |
 | `trunk` | yes (default `main`) | Branch dispatches start from (`origin/<trunk>`). |
 | `origin` | no | Enables clone-on-first-use when `path` doesn't exist. |
-| `setup` | no | Commands run in each fresh worktree, in order (e.g. `["pnpm install"]`). |
+| `setup` | no | Commands run in each fresh worktree, in order (e.g. `["pnpm install"]`). A follow-up that reuses its origin's worktree does not run them again unless a lockfile at the worktree root (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, `go.sum`, and others) or the commands changed since they last ran there. |
+| `scratch` | no | Repo-relative paths (e.g. `["tmp", ".cache"]`) whose untracked files do not count as uncommitted changes when a follow-up decides whether to reuse its origin's worktree. Tracked changes anywhere, and untracked files elsewhere, still do. |
 | `env` | no | Environment merged into every dispatch for this repo. |
 | `pickup` | no (`false`) | Opt this repo into `[pickup.github]` multi-repo mode. Explicit per repo — nothing becomes pickable by being configured. |
+| `pushEarly`, `draftPr`, `checkpointOnStop` | no (inherit `[limits]`) | Override remote preservation for this repo's headless dispatches. |
 
 `[repos.<key>.harness]` — per-repo harness defaults: `default` (`claude` \|
 `codex`), `model`, `effort`.
@@ -53,15 +55,28 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 
 | Key | Default | Meaning |
 |---|---|---|
-| `maxConcurrent` | `2` | Work-lane dispatches running at once. |
-| `choreConcurrent` | `1` | Chore-lane ceiling (rebases and other machine-originated runs). |
-| `wedgeThresholdSecs` | `600` | No tool activity for this long while alive = wedged → killed and forked with a nudge. |
+| `maxConcurrent` | `2` | Headless work-lane runners the daemon may run at once. Trap-claimed catches use their own sessions and do not spend these slots. |
+| `choreConcurrent` | `1` | Headless chore-lane runner ceiling (rebases and other machine-originated runs). |
+| `wedgeThresholdSecs` | `600` | No tool activity for this long while alive = wedged → killed and forked with a nudge. Also the age past which `status`, `ls`, `man tend`, and the glass show a dispatch's activity line as stale. |
 | `maxRestartAttempts` | `2` | Bounded restart ladder for dead and wedged runners. |
-| `wallClockSecs` | `3600` | Hard per-dispatch ceiling, enforced by the runner. |
+| `wallClockSecs` | `3600` | Initial active-work window. Progress extends it, up to `maxWallClockSecs`; time paused with `report paused --waiting-on` does not count. |
+| `maxWallClockSecs` | `4 × wallClockSecs` | Hard active-work ceiling across restarts. |
+| `pushEarly` | `true` | For a new chain, push each new committed HEAD to its non-trunk branch on `origin` within 10 seconds. A rejected push is noted and retried only after HEAD moves. A follow-up whose chain already has a PR does not push automatically; its worker pushes to the existing PR's head branch. |
+| `draftPr` | `true` | For a new chain, after first push, adopt an existing PR or open one draft PR when `gh` is available. A follow-up with a chain PR keeps that PR and its watch; it does not open another. |
+| `checkpointOnStop` | `true` | Before a nonterminal stop, checkpoint eligible tracked and untracked files. A new chain then pushes; a follow-up with a chain PR leaves the checkpoint local for its worker to push. Ignored files and secret/build denylist paths are excluded. Set all three switches to `false` for prior runner behavior. |
+
+A runner extends its active-work window when a fresh activity event or new HEAD
+shows progress at the boundary. The elapsed budget and current window are
+persisted across restarts; a pause with `--waiting-on` does not spend active
+time. At the hard ceiling, the status verb remains `failed` for compatibility,
+but its note starts `budget:` and tells the man what work was saved and to
+send a continuation.
 | `backgroundWaitSecs` | `1800` | A turn that ends without a report is held open this long while background work the worker started is still running (a push behind a slow pre-push gate); the harness wakes the worker when it settles. Heartbeats keep the wedge detector off the wait. Keep it below `wallClockSecs`, which still ends the run. |
 | `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`. |
 | `retentionDays` | `0` (off) | The daemon culls finished dispatches (done and failed) older than this many days: their `done/` entries, worktrees, state files, and stale PR records and acks. Branches are kept. A dispatch whose PR is still open is kept. Queued and active dispatches are never culled. The pass runs at most once per hour and culls at most 10 dispatches per pass, so it cannot stall the claim loop. Suggested: `14`, the same window as `lobstah cull`. |
+| `releaseOnMerge` | `false` (off) | When a PR watch records `merged` for a PR, the daemon's next cull pass removes the worktree of the dispatch that owns the PR, and of every dispatch in its follow-up chain that ran on that PR (its own worktree or a shared one). It uses the retention cull's removal path, its hourly throttle, and its limit of 10 per pass, and runs even when `retentionDays` is `0`. It releases a worktree only when every dispatch in the chain is finished (done or failed) and none is queued or active, `git status --porcelain` is empty, and after a fetch `git branch -r --contains HEAD` is not empty. Otherwise it keeps the worktree, records why, and `lobstah doctor`'s `disk` row shows `kept: unpushed work`; the next pass checks again. Uncommitted changes and unpushed commits are never deleted. A PR closed without merge releases nothing. A trap's worktree is never released. Branches (local and remote), `done/` entries, state, and evidence are kept; `lobstah catch` prints `worktree: released on merge (<time>)`. One `worktree-released` notice per pass lists what was released. |
+| `reuseWorktree` | `true` | A follow-up (`--follow-up <id>`) runs in the worktree of the newest dispatch in its chain whose worktree still exists, on the branch and HEAD where that dispatch stopped. Trunk is fetched; `setup` runs again only if a lockfile changed. It reuses only when the worktree is clean (untracked files under the repo's `scratch` paths excepted), belongs to the same repo, and no other dispatch runs in it; otherwise it allocates a fresh worktree as usual. A dirty worktree is never cleaned or reset. The first status note says which: `reusing worktree of <origin>` or `fresh worktree (<reason>)`. A lock file in the worktree's git dir (`lobstah.lock`) keeps a second runner out; a lock whose dispatch has finished is stale. A shared worktree is kept by the cull and the free-space guard while any dispatch in the chain is queued or active, and it ages from the newest dispatch that used it. `false` allocates a fresh worktree for every dispatch. Headless dispatches only: a trap works in its own worktree. |
 | `minFreeGB` | `0` (off) | Free space the worktrees volume (`~/.lobstah/worktrees`) must have before the daemon claims work, because each claim creates a worktree (1 to 8 GB). Below the limit, the daemon first removes finished worktrees, oldest first, until the limit is met or none are left (this runs even when `retentionDays` is `0`; open-PR and live worktrees are kept, branches are kept). If space is still short, the work stays in the queue and is not failed: `man tend` and the glass show it as `held: 3.2 GB free, needs 10 GB`. The daemon checks again on every tick. One `disk-held` notice marks the start of a hold and one `disk-cleared` notice marks its end. Suggested: `10`. |
 
 ## `[soak]` — soaking sessions (`lobstah soak`)
@@ -69,7 +84,9 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 | Key | Default | Meaning |
 |---|---|---|
 | `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. |
+| `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, and so does a fresh beat. |
+| `beat` | `true` | The post-tool hook (`lobstah soak beat`) refreshes a soaking session's liveness and writes its catch's activity, at most once per 30 seconds per trap. With `false` the hook does nothing, and a trap's liveness comes from its reports and its park only. |
+| `pausedTtlSecs` | `86400` (24 hours) | A trap whose catch last reported `paused` is kept out of the ghost sweep this long after the report. `report paused --until <iso|duration>` sets the expiry instead. After it, the sweep removes the trap as usual, and the notice says the pause expired. |
 
 ## `[helm]` — the orchestrator seat (`lobstah man helm`)
 
@@ -90,6 +107,10 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 | Key | Default | Meaning |
 |---|---|---|
 | `maxForksPerCycle` | `3` | The most continuation (CI-fix) dispatches one watch cycle of `lobstah pick` may fork. Each watch over the cap is held: its events stay buffered, `man tend` and `lobstah watch` list it as `held`, one `watch-held` notice names the held watches, and it forks nothing until `lobstah watch release <key>` (or `--all`). |
+| `autoRepair` | `true` | On a dispatch-owned PR, fork a repair follow-up for a conflict, failed current check, or requested review changes. `false` leaves check-event delivery and attention as before. |
+| `conflicts` | `true` | Repair conflicts when `autoRepair` is on. Set `false` to show conflict attention without a repair. |
+| `checks` | `true` | Repair failed current checks when `autoRepair` is on. Set `false` to show check attention without a repair. |
+| `maxRepairsPerPr` | `2` | Maximum repair follow-ups for one PR head SHA. When the limit is reached and the issue remains, `pr:conflict`, `pr:checks`, or `pr:review` attention names the limit. |
 
 ## `[grounds.*]` — helm territories
 
@@ -111,6 +132,7 @@ repos = ["lobstah", "lavish"]
 | Key | Default | Meaning |
 |---|---|---|
 | `pollSecs` | `45` | Poll cadence. Outbound only — no webhooks, ever. |
+| `liveComment` | `true` | Keep one editable, marked status comment per dispatch. Routine edits are capped at once per minute; human-needed and terminal transitions still post a fresh notification comment. Falls back to transition comments if editing is unavailable. |
 | `notifyCommand` | — | Pickup's own hook, fired on tracker-report transitions with `LOBSTAH_KEY`, `LOBSTAH_UUID`, `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_PR_URL`. |
 
 ### Token sources (both trackers)

package/docs/design.md

@@ -702,7 +702,7 @@ with [Preact](https://preactjs.com) and [htm](https://github.com/developit/htm)
 
 Components are pure functions of the store. A new snapshot re-renders the
 page and Preact's reconciliation changes only the DOM whose data changed:
-rows, cards, and lobs are keyed, so an unchanged row keeps its node, an open
+rows, cards, stack groups, and lobs are keyed, so an unchanged row keeps its node, an open
 modal keeps its nodes across ticks, and scroll positions stay where the
 reader left them — no per-section hashing or manual node preservation. Only
 the active tab's section renders.

package/docs/harness/claude-code.md

@@ -33,9 +33,13 @@ row, and the session-start brief says when the plugin is behind.
 | ----- | ------------ |
 | SessionStart hook (`lobstah man brief`) | Prints the session id and a one-line fleet state. A session that is neither helm nor trap gets the two sign-on commands, with the id filled in. |
 | Stop hook (`lobstah man haul`) | At turn end, blocks with standing attention, or with the command to arm a watcher while work is in flight. Inert unless the session holds the helm or is soaking. |
-| SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends. |
+| PostToolUse hook (`lobstah soak beat`) | After every tool call in a soaking session: refreshes the trap's liveness and writes its catch's activity (the tool name and its primary target, redacted). At most once per 30 seconds per trap. No network, no git; always exits 0, errors go to `~/.lobstah/logs/beat.log`. Inert when not soaking or with `[soak].beat = false`. |
+| SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends and keeps its worktree. |
 | `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken. |
-| `trap` skill | The worker: soaking from a linked worktree, the `wt:` address, the six report verbs. |
+| `trap` skill | The worker: soaking (in a linked worktree, or in one that soak creates), the `wt:` address, the six report verbs, and `paused --waiting-on` before waiting on something external (for ume, the non-blocking push when the await cannot run as a tracked background task). |
+
+`lobstah send <id> "<instruction>"` steers live or queued work and wakes a
+finished dispatch as a follow-up.
 
 Slash commands, each a shortcut for a CLI verb:
 
@@ -44,7 +48,7 @@ Slash commands, each a shortcut for a CLI verb:
 | `/lobstah:helm [grounds]` | `lobstah man helm` |
 | `/lobstah:relieve` | `lobstah man relieve` |
 | `/lobstah:tend` | `lobstah man tend` |
-| `/lobstah:soak` | `lobstah soak` (from a linked worktree) |
+| `/lobstah:soak` | `lobstah soak` |
 | `/lobstah:stow` | `lobstah stow` |
 
 Claude Code also loads the `man` and `trap` skills on its own when you ask

package/docs/harness/codex.md

@@ -34,9 +34,10 @@ says when the plugin is behind.
 | ----- | ------------ |
 | SessionStart hook (`lobstah man brief`) | Prints the session id and a one-line fleet state. A session that is neither helm nor trap gets the two sign-on commands, with the id filled in. |
 | Stop hook (`lobstah man haul`) | Parks the session at turn end while work is in flight and wakes it when something needs attention. Inert unless the session holds the helm or is soaking. |
-| SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends. |
-| `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken. |
-| `trap` skill | The worker: soaking from a linked worktree, the `wt:` address, the six report verbs. |
+| PostToolUse hook (`lobstah soak beat`) | After a tool call in a soaking session: refreshes the trap's liveness and writes its catch's activity. Needs Codex 0.117.0+ (see [below](#post-tool-hook-what-codex-has)). Older Codex ignores the event, and a trap's liveness then comes from its reports and its park only. |
+| SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends and keeps its worktree. |
+| `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken, and sending a follow-up to finished work. |
+| `trap` skill | The worker: soaking (in a linked worktree, or in one that soak creates), the `wt:` address, the six report verbs, and `paused --waiting-on` before external waits. |
 
 There are no slash commands: the Codex plugin layout has no commands
 directory. The skills run the same `lobstah` commands as the README
@@ -60,6 +61,41 @@ command. The desktop task's supplied skill catalog names
 `lobstah:lobsterman` and `lobstah:trap`; *the desktop picker and its exact
 inserted mention remain to be verified from the desktop UI*.
 
+## Post-tool hook: what Codex has
+
+Codex has a `PostToolUse` hook event, with the same `hooks.json` shape as
+Claude Code. Verified in the openai/codex source at commit `e07e58c`:
+
+- `codex-rs/hooks/src/lib.rs` lists `PostToolUse` among the hook event names,
+  and `codex-rs/config/src/hook_config.rs` maps the `PostToolUse` key.
+- The stdin payload (`PostToolUseCommandInput`, `codex-rs/hooks/src/schema.rs`)
+  carries `session_id`, `cwd`, `hook_event_name`, `tool_name`, `tool_input`,
+  and `tool_response`: the fields `lobstah soak beat` reads.
+- It arrived in 0.117.0 for shell commands only (openai/codex#15531), gained
+  `apply_patch` and MCP tools in 0.124.0 (#18391, #18385), and other local
+  function tools in 0.135.0 (#23757).
+- It does not fire for hosted tools such as web search, and it fires only
+  when the tool call succeeds (a shell command that exits non-zero still
+  counts).
+
+Docs: <https://developers.openai.com/codex/hooks>.
+
+So on Codex 0.117.0+ a trap beats after its tool calls, like a Claude Code
+trap. On 0.114 to 0.116, Codex has no post-tool hook: a trap's liveness
+comes from its reports and its park only, and a long stretch of work
+without a report can be swept after `[soak].ttlSecs`.
+
+## Waiting on something external
+
+Before a trap waits on a review, PR, deploy, person, or other external event,
+it reports `paused "<note>" --waiting-on <kind> --link <url>`. Resume with a
+`working` report. A Codex task cannot run an await as a tracked background
+task: use the external tool's non-blocking form and end the turn. See
+[Waiting on](../vocabulary.md#waiting-on).
+
+`lobstah send <id> "<instruction>"` steers live or queued work and wakes a
+finished dispatch as a follow-up.
+
 ## The session id and `--session`
 
 Codex exports no session-id variable, so the CLI cannot find the id on its
@@ -68,11 +104,13 @@ brief prints the task id. Pass it on first sign-on:
 
 ```bash
 lobstah man helm --session <task-id>      # the helm
-lobstah soak --session <task-id>          # a trap, from a linked worktree
+lobstah soak --session <task-id>          # a trap
 ```
 
 After sign-on, the Stop hook gets the id from Codex on stdin. A trap's
-identity is its worktree, so `lobstah soak --wait` needs no flags. Outside
+identity is its worktree, so `lobstah soak --wait` in that worktree needs no
+flags. Outside the trap's worktree, `soak --wait`, `report`, and `stow`
+take `--session <task-id>`. Outside
 the hook, `man wait`, `man report`, and `man relieve` still take
 `--session <task-id>`.
 

package/docs/man.md

@@ -17,6 +17,13 @@ you ⇄ liaison (interactive Claude Code / Codex session)
 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.
+Headless runners preserve new-chain committed work on `origin` as HEAD moves
+and open one draft PR when `gh` is available. On a nonterminal stop they
+checkpoint eligible worktree files and push once more. A follow-up whose
+chain already has a PR keeps that PR and its watch. It does not push or open
+a second PR automatically; its worker pushes to the existing PR's head
+branch. The final status note names the saved branch, commit, and PR, so the
+lobstah man can send a continuation without losing work.
 
 **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,
@@ -45,7 +52,11 @@ the background, dispatch it with the `lobstah` CLI instead of doing it inline:
 - `lobstah dispatch --repo <key> --brief-text "<full brief>"` — returns an id.
   Write briefs that stand alone; the worker has no other context.
 - `lobstah status [<id>]`, `lobstah ls` — check progress when I ask, not on a loop.
-- `lobstah send <id> "<instruction>"` — steer a running dispatch.
+- `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>`.
 - `lobstah cancel <id>` — stop one.
 - A dispatch reporting `needs-decision` is waiting on ME — surface its question
   immediately, then `lobstah send` my answer.
@@ -70,6 +81,21 @@ use by hand. So the crew is inspectable with tools you already have:
   the Claude/Codex desktop apps' session lists) show dispatch sessions too —
   they're stored where the harness always stores them.
 
+A follow-up (`lobstah dispatch --follow-up <id>`) resumes the origin's
+conversation and, by default, its worktree too: it runs in the checkout of
+the newest dispatch in its chain, on the branch and HEAD where that dispatch
+stopped, without a second dependency install. It allocates a fresh worktree
+instead when that checkout has uncommitted changes, is gone, or another
+dispatch runs in it; its first status note says which (`reusing worktree of
+<origin>` or `fresh worktree (<reason>)`). `lobstah catch` prints the
+`worktree` a dispatch ran in, and `worktreeOf` when it reused one.
+`[limits].reuseWorktree = false` turns reuse off. Normally, use
+`lobstah send <id> "<instruction>"` for a continuation: it delivers to the
+live or queued member of the chain, or creates a follow-up of the newest
+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.
+
 Attach refuses while a dispatch is `working` (two writers, one session);
 follow the logs or `send` instead, or cancel and then attach.
 
@@ -108,6 +134,26 @@ 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.
 
+The work table's `activity` column shows what each live dispatch is doing
+now, with its age: `Edit src/a.ts (12s ago)`. It comes from the runner's
+event stream (headless) or the post-tool hook (a trap), never from the
+worker's reports, so it stays current when the worker forgets to report.
+Past `[limits].wedgeThresholdSecs` it reads `stale: … (14m ago)`. A long
+silence is shown, not escalated: it raises no attention and no notice. The
+worker's verb and note stay the primary line. `lobstah status <id>` prints
+the same line as `activity:`, and `lobstah ls` has an `activity` column. See
+[Activity](vocabulary.md#activity).
+
+A worker that waits on something outside lobstah (a ume review, a PR
+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).
+
 ### PR state after done
 
 A dispatch reports `done` when its PR opens; `report done --pr <url>`
@@ -143,18 +189,27 @@ watches that already exist. `prs sync` refreshes existing PR watches only.
 
 The first check of a new watch is a baseline:
 
-- An open PR: checks that already failed show in the PR record and in tend,
-  but they fork no CI-fix dispatch. Only a check that fails after the
-  baseline, or a failed check on a new head sha, forks one.
+- An open PR: the first observation records its checks and merge state, but
+  starts no repair. Later observations may start a bounded repair on a PR
+  lobstah owns.
 - A merged or closed PR: the check records `MERGED` or `CLOSED` in the PR
   record and retires the watch. It forks nothing and raises no attention. A
   `pr-merged` / `pr-closed` notice is posted once only when the PR ended in
   the last 24 hours.
 
 One watch cycle forks at most `[watch].maxForksPerCycle` continuations
-(default 3). Watches over the cap are held and listed as `held` in
-`man tend` and `lobstah watch`. `lobstah watch release <key>` (or `--all`)
-lets them fork again.
+(default 3). Generic watches over the cap are held and listed as `held` in
+`man tend` and `lobstah watch`. PR repairs wait for the next cycle.
+`lobstah watch release <key>` (or `--all`) releases held watches.
+
+For a dispatch-owned PR, the watch repairs conflicts, failed current checks,
+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.
+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.
 
 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
@@ -164,15 +219,25 @@ 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
+**PR order.** Every PR list uses one order: the glass PRs tab, the On deck
+PR stacks, `lobstah prs`, and the `stack #…` lines and the `work` table of
+`man tend`. Open stacks come first, then finished ones. Within each group, the
+stack whose newest PR was first seen last is on top. Within a stack, PRs are
+in stack position. A PR sorts by its record's `firstSeenAt`, then by number.
+A new observation does not change the order. The order changes when a PR
+opens, merges, closes, or changes its base so that it joins or leaves a
+stack. When two PRs share a head branch, the parent is the one first seen
+last. The attention list is in standing order: the time each condition
+started. `observedAt` is shown as the time of the last check.
+
+An observed PR joins tend's attention list by kind. `pr:ready` needs a
+mergeable, non-draft PR with no failed, pending, or unknown current checks.
+`pr:conflict` and `pr:checks` appear for an owned PR only when repair is off,
+blocked, or exhausted; their notes say why. Requested review changes on an
+owned PR follow the same repair rule. Unresolved review questions remain
+`pr:review` attention. Drafts are not attention by default; users can add
+`pr:draft` to `attentionKinds`. The glass and desktop pet use the same list.
+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.
 
@@ -302,6 +367,23 @@ 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.
 
+**The pet's read.** Every six seconds the pet runs `lobstah attention --json`.
+It prints `{ "attention": [...] }`: the same items, with the same fields, that
+`man tend --json` puts under `attention`, and nothing else. If that command
+fails (an older CLI exits 2 on the unknown flag), the pet runs
+`man tend --json` instead. The pet reads the child's output while the child
+runs, so a report of any size works. Each read may take 10 seconds; then the
+pet stops the child and keeps its current windows. After three failed reads in
+a row it writes one line with the reason to `~/.lobstah/logs/pet.log`, and one
+more line when reads work again. After every read it writes
+`~/.lobstah/pet/state.json`. `lobstah doctor` reads that file for its `pet`
+row: installed or not, running or not, and whether the last read worked:
+
+```
+pet  ok    installed; running (pid 812); last read worked 4s ago (`lobstah attention --json`, 3 walking)
+pet  warn  installed; running (pid 812); last read failed 2s ago, 3 in a row: `lobstah attention --json` timed out; `lobstah man tend --json` timed out; last worked 5m ago
+```
+
 **Wrapper loop.** An outer loop blocking on `wait` can spawn one fresh
 headless turn per event:
 
@@ -393,23 +475,77 @@ visible terminal, and whatever authenticated tooling a headless spawn can't
 get.
 
 ```bash
-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 soak                    # in a linked worktree: sign it on; in a
+                                # repo's primary checkout: create a linked
+                                # worktree and sign that on
                                 # (the id: --session, else hook stdin, else
                                 # $CLAUDE_CODE_SESSION_ID)
+lobstah soak --repo <key>       # outside any configured repo: create a
+                                # worktree for <key> and sign it on
 lobstah soak --wait             # hookless sessions: listen in the foreground
                                 # (re-runs need no flags — identity is the
-                                # worktree); exit 3 = quiet, run it again
+                                # worktree, else the session id); exit 3 =
+                                # quiet, run it again
 lobstah stow                    # sign off; an open catch requeues, unread
-                                # messages bounce back to the helm
+                                # messages bounce back to the helm; removes
+                                # the worktree when soak created it
+lobstah stow --keep             # sign off and keep the worktree
+lobstah soak --name amber-gull  # choose or change this trap's two-word name
 ```
 
-**Identity is the worktree.** Sign-on anchors a short trap id in
-`.lobstah-trap` and prints the trap's address (`wt:<id>`); the address
+**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
+`~/.lobstah/worktrees/soak-<trap>` on a new branch `lobstah/soak-<trap>`
+from `origin/<trunk>`, and runs the repo's `setup` commands. Without
+`--repo`, soak run outside a configured repo fails with an error that names
+`--repo`. In a linked worktree, `--repo` must match that worktree's repo.
+Soak prints `worktree: <path>`, `created: true`, and `branch:`. When the
+session is not inside the worktree, it also prints
+`instruction: cd <path> and work in that directory from now on`, and its
+help lines carry `--session <id>`. The session changes into that directory
+before it takes work. If creation fails (setup fails, the
+`[limits].minFreeGB` check fails, or trunk cannot be fetched), soak signs
+nothing on, removes the partial worktree and its branch, and prints the
+cause. The address is `wt:<trap>`. The registration records
+`createdWorktree: true`, and `.lobstah-trap` records `createdBy: "soak"`,
+the session id, the repo, and the branch.
+
+Soak is idempotent. A session that already mans a trap re-uses it when it
+runs `soak` or `soak --wait` outside a linked worktree: the trap is resolved
+from the session id, and no second worktree is created. A worktree that soak
+created for the same session and repo is also re-used after a ghost sweep.
+From outside the worktree, `soak --wait`, `report`, and `stow` find the
+trap by session id (`--session <id>`, or `$CLAUDE_CODE_SESSION_ID`), and
+`send session:<id>` addresses it. With `--session`, or from inside the worktree, `report done` records the
+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.
+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
+deletes the branch only when every commit on it is on its upstream (with no
+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.
+
+**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
 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
+name is reserved across all traps known to this lobstah home, including
+stowed and swept traps. `--name` sets or changes it; malformed and taken
+names are refused. The bare name, `wt:<name>`, and `wt:<id>` all address the
+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.
+
+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:
@@ -430,9 +566,17 @@ 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.
 
+A soaking session proves it is alive three ways: its park heartbeat, its
+reports, and its **beat**. The plugin's post-tool hook runs
+`lobstah soak beat` after tool calls: at most once per 30 seconds it
+refreshes the trap's beat and writes the claimed catch's activity. The hook
+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.
+
 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
+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
 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
@@ -444,7 +588,14 @@ Worktrees are 1 to 8 GB each. `lobstah cull` sweeps what is finished: `done/`
 entries older than the window (`--older-than <days>`, default 14), worktrees
 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.
+`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
+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.
 
 Without `--apply` it is a dry run: it measures each target and prints the
 sizes. A worktree is measured with one `du -sk`; where `du` is missing
@@ -476,8 +627,24 @@ The daemon can do this on its own. Two `[limits]` keys turn it on
   note column, and one `disk-held` notice reaches the helm. When space
   returns, one `disk-cleared` notice follows and claiming resumes.
 
-`lobstah doctor` prints a `disk` row: free space on the worktrees volume, both
-limits, and the count and age of the worktrees a cull could remove.
+A third key, `releaseOnMerge`, frees a worktree as soon as its PR merges
+instead of waiting out `retentionDays`. When a PR watch records `merged`, the
+next cull pass removes the worktree of the dispatch that owns the PR and of
+every dispatch in its follow-up chain that ran on that PR. It checks first:
+every dispatch in the chain is finished, the worktree is clean, and its HEAD
+is on the remote after a fetch. A worktree that fails a check is kept and
+listed as `kept: unpushed work`. A PR closed without merge releases nothing,
+and a trap's worktree is never released. Branches and the dispatch record
+stay; `lobstah catch` says `worktree: released on merge (<time>)`. One
+`worktree-released` notice per pass lists what went.
+
+`lobstah doctor` prints a `disk` row: free space on the worktrees volume, the
+limits, the count and age of the worktrees a cull could remove, and any
+merged PR's worktree that `releaseOnMerge` kept, with the reason:
+
+```
+disk  warn  412.3 GB free on ~/.lobstah/worktrees; minFreeGB 10; retentionDays 14; 3 cullable worktree(s), oldest 9d; releaseOnMerge on; kept: unpushed work (1 worktree(s) of merged PRs: 6a1f0c2e HEAD is not on the remote)
+```
 
 ## What the daemon gives your liaison for free
 

package/docs/pickup.md

@@ -54,6 +54,16 @@ fire-and-forget, never blocking the loop. Point it at whatever the host
 already has (a Slack helper, `openclaw message send`); lobstah stays free of
 messaging vendors.
 
+**Live status.** With `[pickup].liveComment = true` (the default), pickup
+creates one marked, editable comment per dispatch on Linear or GitHub. It
+shows the current verb, waiting reason/link, latest activity and staleness,
+elapsed time, attempt, branch, last commit, commits ahead of trunk, and draft
+PR when known. Pickup edits it at most once per minute unless the verb changes,
+and does not rewrite it when the underlying status is unchanged. A
+`needs-decision`, `blocked`, `failed`, or `done` transition also gets a new
+comment so humans are notified. If the tracker cannot edit the live comment,
+pickup continues with the older transition-comment behavior.
+
 **No LLM in the loop.** Issue-to-descriptor translation is mechanical. Judgment
 about an ambiguous issue belongs to the dispatched agent, which reports
 `needs-decision` — not to pickup. Fleet setups that wake an LLM to poll a