lobstah 0.5.12 → 0.5.13

package/docs/configuration.md

@@ -61,9 +61,9 @@ 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` | 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` | 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. |
-| `draftPr` | `true` | After first push, adopt an existing PR or open one draft PR when `gh` is available. |
-| `checkpointOnStop` | `true` | Before a nonterminal stop, checkpoint eligible tracked and untracked files, then push. Ignored files and secret/build denylist paths are excluded. Set all three switches to `false` for prior runner behavior. |
+| `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

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

@@ -34,9 +34,9 @@ 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. |
 | 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. |
+| 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, 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). |
+| `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.
@@ -48,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

@@ -35,9 +35,9 @@ 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. |
 | 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. |
+| 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 from a linked worktree, the `wt:` address, the six report verbs, and `paused --waiting-on` before external waits. |
+| `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
@@ -104,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,11 +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 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; the final status note names the
-saved branch, commit, and PR, so the man can send a continuation without
-losing work.
+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,
@@ -217,6 +219,17 @@ 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.
 
+**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,
@@ -354,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:
 
@@ -445,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:
@@ -485,13 +569,14 @@ 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. A trap
-that works for an hour without reporting is not swept while it beats.
+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 (no park, report, or beat) past `[soak].ttlSecs` is a **ghost trap** —
-swept, catch requeued, noticed; one that **never parked** is a **defective
+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
@@ -503,7 +588,11 @@ 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. A worktree that follow-ups
+`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.

package/docs/vocabulary.md

@@ -277,7 +277,7 @@ evidence).
 | `merged` / `closed` | Terminal; the check sets `done`, and the watch retires once delivered. Emitted only on an open → terminal change, never on the first observation. |
 | evidence `pr` | `{ url, number, state, draft, reviewDecision, mergeStateStatus, headSha, checks: { total, passed, failed, pending, unknown? }, review: { unresolvedThreads, changesRequested, lastReviewAt }, observedAt }`. Check counts use only the latest run per check name and app/workflow. `CANCELLED` and `STALE` latest runs are unknown, not failed. The PR record also stores repair status, attempts, and reason. `prBadge` shows `repairing: conflict (attempt 1 of 2)` while a repair is in flight; tend, `catch`, and the glass share the badge. |
 | checks unknown | Without `Checks: read`, the check re-reads the PR without `statusCheckRollup`: the PR state is recorded, `checks.unknown` is `no permission`, and the check's output carries the permission `error`. `pr:ready` never stands on unknown checks. |
-| 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. |
+| 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>`), `dispatches` (the ids whose watch observed it; empty for a human's or a culled PR), and `firstSeenAt` (the time of the first observation; written once, never rewritten). `firstSeenAt`, then the PR number, is the order of every PR list. A record from before `firstSeenAt` existed sorts by number at the earliest `firstSeenAt` in the set, and its next observation writes that time as its `firstSeenAt`. **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 records work events,
 then the repair planner decides whether to follow up. One repair runs per PR
@@ -325,19 +325,21 @@ 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.
+`packages/core/src/soak.ts`. **Enforcement:** sign-on from a repo's primary
+checkout, or with `--repo <key>` from outside any configured repo, creates a
+linked worktree (`~/.lobstah/worktrees/soak-<trap>`, branch
+`lobstah/soak-<trap>`) and signs that on; a live foreign session in an owned
+worktree is refused (the session lock); a stale one is adopted.
 
 | Word | Meaning |
 | ---- | ------- |
-| `soak` | Sign the worktree's trap on and take matching work. `--session` is needed only on first sign-on. `--one` stows after the first catch. `--wait` registers a watcher and waits for work; a quiet timeout exits 3. Workers never run `man` verbs. |
-| `stow` | Sign the trap off (run it in the worktree); an open catch requeues (a cancelled one finalizes as failed) and unread messages bounce to the helm. A trap always stows itself freely; stowing someone else's (`--wt`) is steering — the claimed helm's alone. Stow closes the seat, never the session: an opted-in session can only be asked to stop, and a still-looping worker re-enlists visibly (`trap-signed-on`). |
+| `soak` | Sign the worktree's trap on and take matching work. From a primary checkout, or with `--repo <key>` from outside any configured repo, it first creates a linked worktree like a dispatch does (fetch trunk, new branch from `origin/<trunk>`, `setup` commands), prints `worktree:`, `created: true`, `branch:`, and, when the session is elsewhere, `instruction: cd <path> ...`; the session works in that directory. If creation fails, nothing is signed on and the partial worktree and branch are removed. `--repo` in a linked worktree must match its repo. A session that already mans a trap re-uses it (resolved from the session id) and never gets a second worktree. `--session` is needed only on first sign-on. `--one` stows after the first catch. `--wait` registers a watcher and waits for work; a quiet timeout exits 3. Workers never run `man` verbs. |
+| `stow` | Sign the trap off (in the worktree, or elsewhere by session id: `--session <id>` or `$CLAUDE_CODE_SESSION_ID`); 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`). By default stow removes the worktree when soak created it (`createdWorktree: true`) and prints `worktree: removed`, `path:`, and `returnTo:`; `--keep` leaves it. It keeps the worktree (`worktree: kept`, `reason:`) when soak did not create it, or when it holds uncommitted changes, untracked files that are not ignored, or commits on no remote branch; it never forces a removal. The branch is deleted (`branchDeleted:`) only when all its commits are on its upstream (with no upstream: on some remote branch); otherwise `branchKept: <branch> (<reason>)`. `--wt` follows the same rules. The SessionEnd hook (`stow --quiet`) signs off and keeps the worktree. |
 | 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. |
-| beat | `lobstah soak beat`, run by the plugin's post-tool hook after every tool call. It resolves the trap from the working directory (files only: no git, no network), refreshes the trap's beat (`soaking/<trap>.beat`, separate from the registration), and writes the claimed catch's [activity](#activity). Throttled to one per 30 seconds per trap. Inert in a session that is not soaking, or with `[soak].beat = false`. Always exits 0; errors go to `logs/beat.log`. |
-| ghost trap | A registration whose heartbeat **and** beat 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 or a fresh beat keeps a working session out of the sweep. A fresh beat also holds the session lock. A catch whose last report is `paused` keeps its trap until the pause expires ([Waiting on](#waiting-on)). |
+| beat | `lobstah soak beat`, run by the plugin's post-tool hook after every tool call. It resolves the trap from the working directory, else from the session id (files only: no git, no network), refreshes the trap's beat (`soaking/<trap>.beat`, separate from the registration), and writes the claimed catch's [activity](#activity). Throttled to one per 30 seconds per trap. Inert in a session that is not soaking, or with `[soak].beat = false`. Always exits 0; errors go to `logs/beat.log`. |
+| ghost trap | A registration whose heartbeat **and** beat lapsed past `[soak].ttlSecs` **after having parked at least once**. The sweep removes it, requeues its catch, and posts a `trap-ghosted` notice; the worktree stays, and re-soaking restores the same address. A fresh report or a fresh beat keeps a working session out of the sweep. A fresh beat also holds the session lock. A catch whose last report is `paused` keeps its trap until the pause expires ([Waiting on](#waiting-on)). |
 | 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, PRs merged or closed, watches held over the fork cap (`watch-held`), failing (`watch-failing`), and recovered (`watch-recovered`), free-space holds (`disk-held`, `disk-cleared`), and worktrees released after their PR merged (`worktree-released`, one per cull pass). 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. |
 
@@ -417,6 +419,7 @@ 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`). |
+| pet state | `~/.lobstah/pet/state.json` — `{ pid, at, ok, command, reason, consecutiveFailures, items, lastOkAt }`. The desktop pet's one write: it rewrites the file after each attention read (about every six seconds). `command` is the command that worked (`attention --json`, or `man tend --json` from an older CLI). `reason` says why the last read failed (timed out, non-zero exit, output that does not decode). Only `lobstah doctor` reads it, for its `pet` row: running means `pid` is alive and `at` is less than two minutes old. |
 | budget stop | A headless runner's `failed` verb with a `budget:` note means its progress-extended active-work window reached the hard ceiling. This is out of time, not a code failure: the runner checkpoints eligible changes, pushes when enabled, names the saved branch/commit/draft PR, and invites `lobstah send <id> "continue"`. Paused `--waiting-on` time is excluded. |
 
 ## Exit codes

package/package.json

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