lobstah 0.6.9 → 0.7.0

package/docs/configuration.md

@@ -16,6 +16,7 @@ keys of that section.
 | `notifyVerbs` | `["needs-decision", "blocked", "done", "failed"]` | Which verbs fire `notifyCommand`. |
 | `attentionKinds` | `["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"]` | Which kinds `man tend`, the glass, and the desktop pet show. `decision` is a question the helm put to the human with `lobstah man ask`; the glass shows it as a card to answer, and it hides the raw `question` it frames. Without `decision`, framed decisions do not show and raw questions do. `pr:draft`, `landed`, and `report` 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. |
+| `readySettleSecs` | `600` | `pr:ready` stands after continuously meeting the ready conditions on the same head for this many seconds. Any not-ready observation or new head resets the timer. Each attention read re-evaluates expiry from the persisted start, even without a new forge event. `0` restores immediate ready attention; other `pr:*` kinds are unchanged. |
 
 ## `[repos.<key>]` — workspace definitions
 
@@ -109,6 +110,7 @@ send a continuation.
 | `ttlSecs` | `1800` | Heartbeat age past which a registration is a ghost trap: the sweep removes it and requeues an unfinished catch, finalizes done/failed in `done/`, or finalizes a cancelled catch as failed. A fresh `lobstah report` or beat counts as liveness. If the daemon's own tick gap exceeds this TTL, it grants a full TTL after resume before sweeping any traps. |
 | `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. |
 | `signOffGraceSecs` | `600` | After a trap signs off, its address is held this long: messages to it wait for a re-soak of the same worktree instead of bouncing, `send` to it queues with a warning, and work addressed to it raises no `bait-orphaned` notice. After the grace the daemon bounces the held messages. `0` bounces at sign-off. |
+| `terminal` | unset | The terminal app a thrown trap opens in: `terminal` (Terminal.app) or `iterm` (iTerm2). A trap's roster profile (`man roster set <trap> --terminal`) overrides it. Unset, `man throw` uses the app the trap last signed on from, else Terminal.app. `man throw` opens the trap's session there through AppleScript (macOS only); the app needs Automation permission for the terminal that runs `man throw`. |
 | `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`)
@@ -221,5 +223,5 @@ See [pickup.md](pickup.md) for the loop semantics these keys drive.
 |---|---|
 | `LOBSTAH_HOME` | The instance root (default `~/.lobstah`). Multiple instances = multiple homes; one daemon per home, enforced. |
 | `LOBSTAH_MAN` | `=1` designates a session as the lobstah man for the `man haul` Stop hook. |
-| `LOBSTAH_TRAP_TICKET` | A `trap reserve` ticket. `lobstah soak` redeems it and signs the session on as the reserved trap. `--ticket` takes precedence. |
+| `LOBSTAH_TRAP_TICKET` | A ticket `man throw` reserved. `lobstah soak` redeems it and signs the session on as the reserved trap. `--ticket` takes precedence. |
 | `LOBSTAH_TERMINAL_TITLE` | `=0` stops soak from naming the terminal tab after the trap, and stow from clearing it. |

package/docs/man.md

@@ -473,7 +473,9 @@ 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. Its tabs are On deck, Dispatches, Traps,
-PRs, Reports, and Notices. The Reports tab lists every report, unacked first,
+PRs, Reports, Notices, and Stats. The Stats tab shows catches per day as a
+53-week heatmap, with today, this week, the total, and the top traps; it
+reads `stats.json` from `GET /data/stats` and sends nothing. 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
@@ -919,8 +921,8 @@ lobstah focus <trap>           # focus a live trap from the CLI
 lobstah stow                    # sign off; an open catch requeues, unread
                                 # messages wait [soak].signOffGraceSecs for a
                                 # re-soak, then bounce back to the helm;
-                                # removes the worktree when soak created it
-lobstah stow --keep             # sign off and keep the worktree
+                                # keeps the worktree
+lobstah stow --remove           # sign off and remove the worktree soak created
 lobstah soak --name amber-gull  # choose or change this trap's two-word name
 ```
 
@@ -967,15 +969,20 @@ 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, 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` keeps the worktree by default: it prints `worktree: kept` and
+`reason: stow keeps the worktree; --remove removes it`, and a later
+`man throw` brings the trap back in it. `stow --remove` 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, commits its upstream lacks, or no upstream. Ignored
+files do not block removal. `stow --remove --force` explicitly allows removal
+of unsaved checkout files; `--force` alone refuses. `--keep` is accepted and
+changes nothing.
 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
+`returnTo: <primary checkout>`, with a help line `cd <primary>`. Before
+removal, the checkout's HEAD goes to the trap's protected ref. 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
@@ -1080,43 +1087,46 @@ enlistment** — noticed with its diagnosis (usually a missing Stop hook →
 Nobody is conscripted: only a worktree whose session ran `soak` ever
 receives work.
 
-### Reserving a trap before its session starts
+### Starting a new trap
 
 ```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 man throw --new --repo <key> [--count N] [--harness claude|codex]
+                                        # start N fresh traps; wait until each listens
+lobstah man throw --new --repo <key> --count 3 --dry-run
+                                        # what would start; launches nothing
+lobstah soak --ticket <ticket>          # what the new session runs: 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`.
+`man throw --new` (the helm's) picks a two-word name and a `wt:` id for each
+fresh trap before any session exists and writes a **starting** reservation
+(`soaking/<id>.starting`) with a deadline (`--timeout`, default 180 seconds).
+`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:
+The harness comes from `--harness`, else `[repos.<key>.harness].default`,
+else `[harness].default`; the model and effort from the same tables. The
+terminal is `[soak].terminal`, else Terminal.app. Throw opens the start
+command in a new tab in the repo's primary checkout:
 
 ```bash
-cd <repo> && CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 claude "/lobstah:trap soak --ticket <ticket>"
+cd <repo> && CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 claude '/lobstah:trap 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
+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 throw that sees no sign-on by its deadline withdraws the reservation and
+posts `trap-start-failed`. A reservation found unredeemed at its deadline by
+the daemon (one throw did not wait for) **fails** the same way: the glass
+shows the trap as `start failed` with the reason, and work addressed to it
+stays queued. `lobstah stow --wt <name>` withdraws a reservation; its
 addressed work is then orphaned bait and the helm gets a `bait-orphaned`
 notice.
 
@@ -1140,20 +1150,125 @@ 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
+lobstah man throw --new --request <id>   # start 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.
+`man throw --new --request <id>` takes the repo and harness from the request
+(flags may repeat them, never contradict them), records the request on the
+reservation, and closes the request with the result. The card becomes the
+starting card, then the live trap when the session signs on.
+
+Every starting card shows a start command with a copy button: paste it into a
+terminal to start the session by hand if the throw's terminal could not open.
+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 roster, and what a throw would do
+
+Every trap that signs on gets a **roster** record
+(`~/.lobstah/roster/<trapId>.json`). A registration lasts while a session
+mans the trap, and the signed-off hold lasts for the mail grace. The roster
+record stays through stow, the end of the grace, a ghost sweep, and `cull`.
+It keeps the trap's name, repo, worktree, branch and HEAD, harness, session,
+the registration's model and config, and why the trap left. Its name is the
+trap's name: a trap that signs on again in its worktree keeps it, from any
+session.
+
+Before stow, a ghost sweep, or `cull` removes a trap's checkout, lobstah
+writes the checkout's HEAD to the **protected ref**
+`refs/lobstah/traps/<trapId>` in the repository. It is not a branch:
+removing the worktree or deleting its branch leaves the ref and its commit in
+place.
 
-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.
+```bash
+lobstah man roster                                  # every trap the roster keeps
+lobstah man roster set <trap> --harness codex --model <m> --terminal iterm --config effort=high
+                                                    # save how a throw starts it; `default` or `key=` clears
+lobstah man throw <trap> [--timeout <secs>]         # bring one trap back; wait until it listens
+lobstah man throw --all                             # every eligible trap in your grounds, at once
+lobstah man throw --repo <key>                      # every eligible trap of one repo
+lobstah man throw --new --repo <key> --count N      # N fresh traps (see "Starting a new trap")
+lobstah man throw --dry-run <trap>... | --all | --repo <key> | --new ...
+                                                    # what a throw would do; launches nothing (--plan too)
+lobstah man roster forget <trap> [--force]          # remove a stowed trap's record, worktree, and ref
+```
+
+`man throw --dry-run` (or `--plan`) launches nothing and writes nothing. Each
+row says what a throw would do and why:
+
+- `resume`: the harness reopens the saved session (`claude --resume`, `codex
+  resume`) in the trap's checkout.
+- `cold`: a new session under the same name, id, and checkout. The reason is
+  one of: no saved history for the session, a session that ran in an app (the
+  Claude desktop app's Code tab, the VS Code extension, the Codex app), or a
+  saved profile whose harness is not the one that wrote the session.
+- `skip`: the trap is live or starting (reserved).
+- `unresolved`: a throw would refuse. The repo is no longer configured or now
+  points at another repository, the record is incomplete, the checkout is
+  gone and no protected ref keeps its revision, or the path now anchors
+  another trap. A trap stowed before the roster existed is listed here until
+  a session soaks in its worktree once.
+
+`checkout` is `kept` (the checkout is adopted as it is) or `recreate` (it is
+added back at the protected revision). The harness, model, config, and
+terminal come from the saved profile, else from the trap's last sign-on. The
+terminal is the profile's, else `[soak].terminal`, else the app the trap last
+signed on from, else Terminal.app. `--all` and `--repo` stay inside the
+grounds: `--grounds`, else the caller's helm grounds, else every repo.
+
+`man throw <trap>` does what its plan row says, for one trap (the helm's
+verb). A `skip` refuses: a trap that is live, or already starting, is never
+launched twice. Otherwise:
+
+1. It reserves the trap under its **own** id and name, in its own worktree.
+   The reservation is created exclusively, so a second throw refuses until
+   the first returns or times out. `--for <name>` keeps working throughout.
+2. A `recreate` checkout is added back at `refs/lobstah/traps/<id>` on the
+   trap's recorded branch, with the repo's `setup`. An existing branch is
+   used only when it still contains that revision; a throw never resets a
+   branch. A kept checkout is used as it is, dirty or not.
+3. It opens the start command in the terminal (Terminal.app or iTerm2,
+   through AppleScript, macOS only). `resume` reopens the saved session from
+   the directory its history is keyed by (Claude keys transcripts by the
+   directory the session started in); `cold` starts a new session in the
+   worktree. The profile's model and config become harness flags (`--model`,
+   `--effort`, `--permission-mode` for Claude; `-m`, `model_reasoning_effort`
+   for Codex); a setting with no flag is named as not applied. The first
+   prompt redeems the ticket, so the session signs on as the same trap.
+4. It returns when the trap has signed on and parked, and prints whether it
+   resumed or started cold, and why. Past `--timeout` (default 180 seconds)
+   it withdraws the reservation, so a late session cannot take the trap,
+   posts `trap-start-failed`, and leaves the roster unchanged.
+
+**Batches.** `man throw --all` throws every eligible trap in the grounds
+(`--grounds`, else the caller's helm grounds, else every repo); `--repo`
+narrows to one repo; `--new --count N` starts N fresh ones. Every launch runs
+at once, with no limit, and the batch waits for all of them. It prints one
+row per trap: `resumed`, `cold`, or `new` (with why), `skipped` (live,
+starting, or unresolved, with why), or `failed` (with why). One trap failing
+does not stop the others, and the command exits 1 when any failed.
+
+**Notices.** A trap's start wakes the helm once: `trap-available`, when the
+trap is listening. Its reservation (`trap-starting`), sign-on
+(`trap-signed-on`), and sign-off (`trap-stowed`) are quiet: tend, the
+digest's `traps` table, and the glass show them. A ghost sweep of an idle
+trap is quiet the same way; a ghost sweep of a trap that held a catch wakes.
+A batch posts no `trap-available` per trap: when every throw has settled it
+posts one `trap-batch` notice with the counts and the names that failed. A
+trap that failed to start (`trap-start-failed`) and work addressed to a trap
+that is gone (`bait-orphaned`) still wake.
+
+**Forget.** `man roster forget <trap>` (the helm's) takes a stowed trap off
+the roster for good. It refuses a live or starting trap. It also refuses, and
+names the work, when the trap holds anything that exists nowhere else:
+modified or untracked files in its checkout, or commits (in the protected
+ref, the checkout, or its branch) that are on no remote branch and not merged
+to trunk. `--force` forgets anyway. Otherwise it removes the worktree soak
+created (one it did not create stays, minus its anchor), deletes
+`refs/lobstah/traps/<id>`, bounces held messages, and frees the name. A
+branch that still holds commits on no remote is kept even with `--force`.
 
 ### The sign-on title
 
@@ -1188,7 +1303,7 @@ Other terminals are left alone. `lobstah stow` clears the name.
 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.
+command `man throw` opens sets it. Codex also sets the terminal title.
 
 ### Culling and disk space
 

package/docs/vocabulary.md

@@ -396,7 +396,7 @@ evidence).
 | descriptor `pr` | `{ url, headRefName?, headSha? }`: the existing PR a dispatch works on. A PR repair and a pickup rebase chore carry it. The runner pushes no branch and opens no PR for such a dispatch; its worker pushes to the PR's head branch. |
 | push rule | What a repair or rebase brief tells its worker: push only to the PR's head branch; on a non-fast-forward rejection, fetch, rebase the commits onto the moved head again, and push with `--force-with-lease` on the head just fetched, at most three times; a hook failure from a real test or type error is not retried; when it cannot push, report `failed "push rejected: <rejection text>; moved head <sha>"` and leave the PR as it was. That report marks the PR's repair `blocked` at the moved head and posts a `push-failed` notice. |
 | 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 (with `title`, read on every check; a title change is not a state change) 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. |
+| 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 (with `title`, read on every check; a title change is not a state change) 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 `stack-ready` aggregation and quiet stacked `pr:ready` items, 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
@@ -467,18 +467,21 @@ worktree is refused (the session lock); a stale one is adopted.
 | ---- | ------- |
 | `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. |
 | `soak title-set` (alias `trap title-set`) | Confirm this session applied the title sign-on printed (`step: Apply this title: <title>`). The registration records `titleSet` and `titleSetAt` and drops `titlePending`; sign-on is complete. Until then, SessionStart and Stop remind the session once per turn, at most three times. A trap runs `soak title-set`: Claude Code's worktree isolation refuses a command line containing `trap`. |
-| `stow` | Sign the trap off (in the worktree, or elsewhere by session id: `--session <id>` or `$CLAUDE_CODE_SESSION_ID`); an unfinished catch requeues, done/failed finalizes in `done/`, and a cancelled catch finalizes as failed. Unread messages are held for `[soak].signOffGraceSecs` (default 600): they deliver if the same worktree re-soaks in time, else the daemon bounces them to the helm (at once when stow removed the worktree or the grace is `0`). 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, commits absent from its upstream, or no upstream. `--force` explicitly allows discarding unsaved checkout files; `--keep` still keeps it. 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 only when the ending session is the trap's registered session (another session in the worktree ending is a no-op) and keeps the worktree; SessionEnd cannot tell a restart or compaction from an exit (Claude Code's `reason` is `clear`, `resume`, `logout`, `prompt_input_exit`, or `other`; Codex's is always `other`), so the grace covers a session that signs on again. |
+| `stow` | Sign the trap off (in the worktree, or elsewhere by session id: `--session <id>` or `$CLAUDE_CODE_SESSION_ID`); an unfinished catch requeues, done/failed finalizes in `done/`, and a cancelled catch finalizes as failed. Unread messages are held for `[soak].signOffGraceSecs` (default 600): they deliver if the same worktree re-soaks in time, else the daemon bounces them to the helm (at once when stow removed the worktree or the grace is `0`). 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 keeps the worktree (`worktree: kept`, `reason: stow keeps the worktree; --remove removes it`), so `man throw` can bring the trap back in it; `--keep` is accepted and changes nothing. `--remove` removes the worktree when soak created it (`createdWorktree: true`) and prints `worktree: removed`, `path:`, and `returnTo:`; it still keeps it (`worktree: kept`, `reason:`) when soak did not create it, or when it holds uncommitted changes, untracked files that are not ignored, commits absent from its upstream, or no upstream. `--remove --force` explicitly allows discarding unsaved checkout files; `--force` alone refuses. 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 only when the ending session is the trap's registered session (another session in the worktree ending is a no-op) and keeps the worktree; SessionEnd cannot tell a restart or compaction from an exit (Claude Code's `reason` is `clear`, `resume`, `logout`, `prompt_input_exit`, or `other`; Codex's is always `other`), so the grace covers a session that signs on again. |
 | sign-off grace | For `[soak].signOffGraceSecs` after a trap signs off (`~/.lobstah/signed-off/<trap>.json`), its address is held: `send wt:<trap>` queues and warns instead of refusing, held messages wait, and work addressed to it raises no `bait-orphaned` notice. A re-soak of the same worktree releases the hold; after the grace, the daemon bounces the held messages (`message-bounced`). |
 | 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. |
 | hook command | `lobstah hook session-start\|stop\|post-tool-use\|session-end`: the command each plugin hook runs. Each detects the session's role (helm, trap, or neither) and runs what `man brief`, `man haul`, `soak beat`, and `stow --quiet` run; those stay as aliases. Stop, PostToolUse, and SessionEnd are inert for a session with neither role; SessionStart announces the session id to every session. |
 | beat | `lobstah soak beat` (`lobstah hook post-tool-use`), 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 the registration, requeues only unfinished catches, finalizes done/failed in `done/`, and posts a `trap-ghosted` notice. It removes a soak-created checkout only when clean and pushed to its upstream; dirty, unpushed, no-upstream, or unreadable checkouts stay, protected from later culls too. The notice includes path, branch, modified-file and unpushed-commit counts, or `unknown` when unavailable. A kept anchor preserves the address on re-soaking. A fresh report or 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)). A daemon tick gap longer than the soak TTL starts one full TTL of resume grace before any ghost sweep. |
+| ghost trap | A registration whose heartbeat **and** beat lapsed past `[soak].ttlSecs` **after having parked at least once**. The sweep removes the registration, requeues only unfinished catches, finalizes done/failed in `done/`, and posts a `trap-ghosted` notice: quiet (digest and glass only) for an idle trap, a wake for one that held a catch. It removes a soak-created checkout only when clean and pushed to its upstream; dirty, unpushed, no-upstream, or unreadable checkouts stay, protected from later culls too. The notice includes path, branch, modified-file and unpushed-commit counts, or `unknown` when unavailable. A kept anchor preserves the address on re-soaking. A fresh report or 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)). A daemon tick gap longer than the soak TTL starts one full TTL of resume grace before any ghost sweep. |
 | defective enlistment | A stale registration that **never parked** — signed on but never listened (usually no Stop hook). Not swept: the helm gets a `trap-defective` notice with the remedy (`soak --wait`), and the registration stays so the address keeps protecting its work. |
-| reserved trap | A trap `lobstah trap reserve` created before any session signs on as it: a name, a `wt:` id, and a one-time ticket, shown as `starting`. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. Unredeemed past its deadline, it fails with a `trap-start-failed` notice and its work stays queued. `stow --wt <name>` withdraws it. |
-| trap request | A trap the human asked for from the glass's **+ New trap** button: a `trap-request` request in `requests/<id>.json` with a repo and a harness. It wakes the helm as a `trap-request` event; the helm reserves it with `trap reserve --request <id>`, which closes it. |
-| notice | The helm's attention channel for non-status events (`~/.lobstah/notices/`): reservations (`trap-starting`), reservations that did not start (`trap-start-failed`), trap requests from the glass (`trap-request`), 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`), worktrees released after their PR merged (`worktree-released`, one per cull pass), a repair or rebase that could not push to its PR's branch (`push-failed`), repairs stopped on a PR that made no progress (`repair-stopped`), and a human's answer to a decision (`decision-answer`; its ref is the request id in `~/.lobstah/requests/`). 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; a first park (`trap-listening`) is consumed without waking anyone. tend always shows the recent tail. |
+| reserved trap | A trap `man throw` reserved before its session signs on: a name, a `wt:` id, and a one-time ticket, shown as `starting`. `man throw --new` reserves a fresh id and name; `man throw <name>` reserves an existing roster trap under its own id and name, in its own worktree (the reservation records the worktree). A trap has at most one reservation, so a second throw refuses. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. A throw that sees no sign-on by its timeout withdraws the reservation; one found unredeemed past its deadline fails with a `trap-start-failed` notice and its work stays queued. `stow --wt <name>` withdraws it. A reservation made by a batch throw records the batch, and so does the registration its sign-on makes. |
+| trap roster | One durable record per trap that ever signed on (`~/.lobstah/roster/<trapId>.json`): canonical name, repo and its git common directory, worktree, soak branch, last branch and HEAD, harness, session, the registration's model and config, window and link (navigation hints only), state (`live`, `stowed`, `ghosted`), when and why it left, its last catch, and a saved profile (harness, model, config, terminal) set with `man roster set`. Sign-on writes it; stow and the ghost sweep update it before the registration goes. Stow, the end of the sign-off grace, a ghost sweep, and `cull` never remove it. The roster's name is the trap's name: a trap that signs on again keeps it. A roster record never makes a trap live or claimable. `man roster` lists it; `man throw` reads it; `man roster forget` removes it. |
+| protected ref | `refs/lobstah/traps/<trapId>` in the trap's repository: the trap's last HEAD, written at sign-on and before stow, a ghost sweep, or `cull` removes the checkout. It is not a branch, so worktree removal and branch cleanup leave it and its commit in place. A missing checkout is recreated from it. A trap checkout whose revision cannot be written there is not removed by a ghost sweep or cull. |
+| trap request | A trap the human asked for from the glass's **+ New trap** button: a `trap-request` request in `requests/<id>.json` with a repo and a harness. It wakes the helm as a `trap-request` event; the helm starts it with `man throw --new --request <id>`, which takes the request's repo and harness and closes it. |
+| notice | The helm's attention channel for non-status events (`~/.lobstah/notices/`): reservations (`trap-starting`), reservations that did not start (`trap-start-failed`), trap requests from the glass (`trap-request`), sign-ons, a trap free to take work (`trap-available`), a batch throw settled (`trap-batch`), 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`), worktrees released after their PR merged (`worktree-released`, one per cull pass), a repair or rebase that could not push to its PR's branch (`push-failed`), repairs stopped on a PR that made no progress (`repair-stopped`), and a human's answer to a decision (`decision-answer`; its ref is the request id in `~/.lobstah/requests/`). 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. A trap's start wakes once, with `trap-available` when it is listening; `trap-starting`, `trap-signed-on`, `trap-stowed`, `trap-listening` (older homes), a ghost of an idle trap, and a batch member's `trap-available` are quiet: consumed without waking anyone, shown in tend, the glass, and (sign-offs and idle ghosts) the digest's `traps` table. A batch throw wakes once, with `trap-batch` when every throw settled: counts, and the names that failed. tend always shows the recent tail. |
+| stack-ready notice | One wake for an all-ready PR stack, with the PRs in bottom-first merge order. Stacked per-PR ready items remain quiet; unchanged heads do not re-notify as the bottom PRs merge. |
 
 Delivery routes by ownership, same as watches: a continuation for a chain
 claimed by a live trap is addressed back to that trap and stays sticky.
@@ -496,14 +499,20 @@ hold two; a live foreign holder refuses sign-on without `--take`. The rule
 is strict: once a helm is claimed, the orchestrator verbs that consume helm
 state (`man wait`, `man report`, the lobstah man park) are reserved for the
 helm session — any other caller is refused with guidance (or, for the hook,
-silently ignored). Read verbs (`man tend`, `man brief`) and the enlistment
-verbs stay open. A stale helm reserves nothing.
+silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
+`man roster`) and the enlistment verbs stay open; `man roster set`,
+`man roster forget`, and `man throw` are the helm's. A stale helm reserves nothing.
 
 | Word | Meaning |
 | ---- | ------- |
 | lobstah man | One interactive session that takes the helm for a grounds, triages the fleet, dispatches work, and answers traps; `lobstah man` also names its CLI command group. |
 | `helm` | Sign a session on as the orchestrator for one grounds. Prints the charter and enables the Stop hook without a marker file. Re-running from the same session is an idempotent re-sign. |
 | watcher registration | `~/.lobstah/watchers/<session-id>.json` stores a `man wait` or `soak --wait` process's PID and heartbeat. The waiter refreshes it while running and removes it on exit; a heartbeat older than five seconds is stale, and a second waiter for the same session refuses. |
+| `man throw --dry-run` | What a throw would do for each selected trap (`--plan` is the same), read from the [trap roster](#soaking-contract): `resume` the saved session, `cold` (a new session under the same name, id, and checkout; the row says why: no saved history, an app session, a profile that changes harness), `skip` (live or starting), or `unresolved` (repo no longer configured or now another repository, record incomplete, checkout gone with no protected ref, or the path anchors another trap). Names select traps; `--all` selects every eligible trap in the grounds; `--repo` narrows. Each row shows harness, model, config, terminal (and where each came from), checkout (`kept` or `recreate`), revision, and held messages. Read-only: it launches and writes nothing. |
+| `man throw --all \| --repo <key> \| --new [--count N]` | A batch throw (the helm's): every eligible trap in the grounds, one repo's, or N fresh traps from the harness defaults (`--harness`, `--request <id>` for a glass trap request). Every launch runs at once, with no limit. One row per trap: `resumed`, `cold`, `new`, `skipped`, or `failed`, each with why; one failure does not stop the others, and the command exits 1 when any failed. The batch posts one `trap-batch` notice when it settles and no per-trap `trap-available`. `--dry-run` (or `--plan`) shows the plan and launches nothing. |
+| `man roster forget <name>` | Remove a stowed trap for good (the helm's): its worktree (one soak did not create stays, minus its anchor), its protected ref, its roster record, its held messages (bounced), and its name. Refuses a live or starting trap, and refuses, naming the work, when its checkout has unsaved files or its commits are on no remote branch and not merged to trunk; `--force` forgets anyway, keeping a branch that still holds such commits. |
+| `man throw <name>` | Bring one roster trap back and wait until it listens. The helm's. It follows the plan for that trap: a `skip` (live or starting) refuses, which fences a double launch; an `unresolved` refuses with its reason. Otherwise it reserves the trap under its own id and name, recreates a missing checkout from the protected ref on its recorded branch (an existing branch only when it still contains that revision; a kept checkout, dirty or not, is used as is), and opens the start command in the profile's terminal (Terminal.app or iTerm2, macOS): `resume` reopens the saved session from the directory its history is keyed by, `cold` starts a new one in the worktree; the first prompt redeems the ticket. It returns when the trap has signed on under its id and parked, printing which start happened and why. Past `--timeout` (default 180 s) it withdraws the reservation, posts `trap-start-failed`, and leaves the roster unchanged. Batches: see `man throw --all`. |
+| `man roster` | List the trap roster. `man roster set <trap> --harness\|--model\|--terminal <value>\|--config <key>=<value>` saves how a throw starts the trap; `default` (or `key=`) clears a field. |
 | `man haul --park` | Make the Stop hook wait for attention while work is in flight. `[helm].park = "block"` selects the same mode. In arm mode, the hook allows a stop with a live watcher or blocks with the arm command. |
 | `relieve` | Step down. `--take` on another session's `helm` is the only force path: it displaces a live holder deliberately and leaves them a stand-down notice, delivered once at their next park. A holder whose heartbeat lapsed past `[helm].ttlSecs` is stale and claimable without `--take`. |
 | grounds | A named territory: the subset of configured repos one helm oversees, from `[grounds.*]`. A repo belongs to at most one grounds (config error otherwise). No grounds configured means one implicit `fleet` grounds covering every repo. |
@@ -534,7 +543,8 @@ never until someone acknowledges it.
 | `pr:review` | An open PR has unresolved review questions, or requested changes that lobstah cannot repair, has exhausted, or is configured not to repair. | Every thread resolved and no changes requested, or merged / closed. |
 | `pr:checks` | An open PR has a failed latest check, and lobstah cannot repair it, has exhausted attempts, or is configured not to repair. | Green on the head, or merged / closed. |
 | `pr:conflict` | An open PR conflicts with its base, and lobstah cannot repair it, has exhausted attempts, or is configured not to repair. | The merge state leaves `DIRTY`, or merged / closed. |
-| `pr:ready` | An open, non-draft PR has no review condition, a mergeable state (`CLEAN`, `HAS_HOOKS`, or `UNSTABLE`), and no failed, pending, or unknown latest checks. It is approved or has at least one check. | Merged or closed, or the ready conditions stop holding. |
+| `pr:ready` | An open, non-draft PR has no review condition, a mergeable state (`CLEAN`, `HAS_HOOKS`, or `UNSTABLE`), and no failed, pending, or unknown latest checks. It is approved or has at least one check, continuously on the same head for `readySettleSecs` (default 600; `0` is immediate). Attention reads re-evaluate expiry without requiring a new forge event. In a trunk-rooted same-repo stack of two or more non-fork PRs, each ready item stays visible but quiet; the stack wakes once. | Merged or closed, or the ready conditions stop holding; any not-ready observation or new head resets settling. |
+| `stack-ready` | Every open member of a trunk-rooted same-repo base/head chain meets the identical `pr:ready` rule, including settling. Enabled with `pr:ready` (or explicitly with `stack-ready`). One notice and walking item per ready epoch, naming PRs bottom to top in merge order. Tend, digest, and the existing glass group also show partial readiness. Existing `pr:` watches discover missing links at their normal cadence; `lobstah watch add pr:<owner>/<repo>#<n>` follows a stack from any member. | Any member becomes unready or gets a new head; all ready again wakes once. Bottom-first merges and retargeting do not wake again for unchanged surviving heads. |
 | `report` | A filed report (`report --report`, `man file`) has no ack for this filing. Opt-in. Key `report:<lane>:<uuid>` or `report:helm:<grounds>:<rid>`. | Not cleared: it stays listed until culled. `lobstah attention ack <key>` acks it, and a newer report in the same chain acks the older; an acked report no longer walks. |
 
 `pr:*` kinds read only the `pr:` watch's evidence — never a forge call —
@@ -563,7 +573,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), `decision:<rid>`, `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`); for a ready PR, only when `pr:ready` began standing (its `standingSince`), so repeat observations of the same ready state keep the ack and ready → not ready → ready re-stands it once. |
+| 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), `decision:<rid>`, `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`); for a ready PR, only the head sha. A ready ack is kept across same-head CI flaps and draft toggles, without hiding checks, conflicts, or review attention during the flap. A new head re-stands ready once after settling. |
 | 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. |
 

package/package.json

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