lobstah 0.2.1 → 0.3.1

package/dist/runner.js

@@ -767,6 +767,10 @@ function parse(toml, { maxDepth = 1e3, integersAsBigInt } = {}) {
 }
 
 // packages/core/dist/config.js
+var DEFAULT_SOAK = {
+  deferSecs: 90,
+  ttlSecs: 1800
+};
 var DEFAULT_LIMITS = {
   maxConcurrent: 2,
   choreConcurrent: 1,
@@ -801,6 +805,7 @@ function loadConfig() {
     repos,
     harness: raw.harness ?? {},
     limits: { ...DEFAULT_LIMITS, ...raw.limits ?? {} },
+    soak: { ...DEFAULT_SOAK, ...raw.soak ?? {} },
     notifyCommand: raw.notifyCommand ? String(raw.notifyCommand) : void 0,
     notifyVerbs: Array.isArray(raw.notifyVerbs) ? raw.notifyVerbs.map(String) : void 0,
     remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0

package/docs/configuration.md

@@ -53,6 +53,13 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 | `wallClockSecs` | `3600` | Hard per-dispatch ceiling, enforced by the runner. |
 | `choreRetentionDays` | `7` | Completed chores age out of `chores/done/`. |
 
+## `[soak]` — soaking sessions (`lobstah soak`)
+
+| 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. |
+
 ## `[pickup]` — tracker loops (`lobstah pick`)
 
 | Key | Default | Meaning |

package/docs/lobsterman.md

@@ -141,9 +141,10 @@ trapline; every orchestrator-facing command lives under `lobstah man`).
 Install it from the project you'll run the lobsterman in:
 
 ```bash
-# Easiest: the Claude Code plugin ships the hook + the lobsterman skill +
-# /lobstah, no settings edits — /plugin marketplace add aequitas-labs/lobstah,
-# /plugin install lobstah@lobstah. Or wire the hook by hand:
+# Easiest: the plugin ships the hooks + the lobsterman skill, no settings
+# edits — /plugin marketplace add aequitas-labs/lobstah, then
+# /plugin install lobstah@lobstah (Claude Code and Codex v0.114+; Codex asks
+# for a one-time hook trust review). Or wire the Claude hook by hand:
 lobstah man init            # merges the Stop hook into .claude/settings.local.json
 lobstah man init --shared   # …or the committed .claude/settings.json
 lobstah man init --global   # …or once into ~/.claude/settings.json — any
@@ -173,11 +174,11 @@ the haul context as the work order for that turn.
 The trade-offs, honestly. While parked, the turn never ends, so the terminal
 shows a running hook. Each wake appends a turn to the context, and long
 shifts eventually compact. Without the gate, the hook parks every session in
-the project. And parking is Claude-specific: it needs a turn-end hook that
-can block and inject a continuation. Claude Code's Stop hook can. Codex's
-fire-and-forget notify hook cannot. The workers can still be any harness —
-only the liaison must be Claude Code. Tier 2 is the right default. Tier 3 is
-for a dedicated, long-lived liaison session.
+the project. And parking needs a turn-end hook that
+can block and inject a continuation. Claude Code's Stop hook can, and so can
+Codex's since its hooks system landed (v0.114+; older Codex only has the
+fire-and-forget notify hook, which cannot). Tier 2 is the right default.
+Tier 3 is for a dedicated, long-lived liaison session.
 
 **Delivery guarantee.** Attention wakes are at-least-once with backoff. An
 unanswered question is reported immediately. While it still stands, it
@@ -201,6 +202,35 @@ Zero tokens between events and works anywhere a shell does; the cost is that
 each event gets a fresh context rather than a continuing liaison
 conversation.
 
+## Soaking: a live session volunteers as a worker
+
+Workers are usually traps lobstah sets itself — fresh headless sessions in
+fresh worktrees. A **soaking** session is the inverse: an interactive thread
+already in the water volunteers to take bait, keeping its warm context, its
+visible terminal, and whatever authenticated tooling a headless spawn can't
+get.
+
+```bash
+lobstah soak --session <id>     # from a worktree — the primary checkout is
+                                # never claimable, so sign on from a linked
+                                # worktree (git worktree add ../side -b side)
+lobstah stow --session <id>     # sign off; an open catch requeues
+```
+
+The session id comes from the plugin's session-start brief (`lobstah man
+brief` announces it into the conversation). Once soaking, the same Stop hook
+that parks a lobsterman parks the worker: at turn end it waits for bait,
+claims it, and wakes with the brief. While it works a catch, the park wakes
+it for `lobstah send` messages and cancels instead.
+
+Routing follows ownership: `dispatch --for session:<id>` targets one trap;
+unaddressed bait for a matching repo prefers a parked trap for
+`[soak].deferSecs` before the daemon spawns headless; a watch continuation
+for a chain a soaking session claimed is addressed back to that session. A
+registration whose heartbeat lapses past `[soak].ttlSecs` is a **ghost
+trap** — swept, its catch requeued. Nobody is conscripted: only a session
+that ran `soak` ever receives work.
+
 ## What the daemon gives your liaison for free
 
 - Parallel work that can't collide — worktree per dispatch.

package/docs/pickup.md

@@ -92,12 +92,30 @@ The three loops are tracker-agnostic and drive whichever sources are configured.
 | Rule | Trigger | Descriptor |
 |---|---|---|
 | Issue pickup | Assigned to the configured identity, in the configured start state | Implementation brief from the issue |
-| Review pickup | Open PR authored by the configured identity with `CHANGES_REQUESTED`, or a human review newer than HEAD | Address-review brief from the feedback |
-
-A review dispatch sets `followUp` to the implementation dispatch's UUID,
-forking that session so the feedback lands on the context that made the
-choices. A rebase chore starts cold on purpose — the conflict is about commits
-the original session never saw.
+| Feedback pickup | Human feedback on an open PR that maps back to a dispatch | Address-feedback brief; the agent reads the live thread |
+
+A dispatch reports `done` when its PR opens, so the reviewer's side of the
+conversation has to re-enter the queue as its own work. Feedback pickup
+covers all of it: a `CHANGES_REQUESTED` review on any sha (a review of a
+slightly stale head still asks for changes), a comment review with a body,
+an inline review-thread comment, or a conversation comment — always from
+someone other than the configured identity, never a lobstah marker comment.
+`APPROVED` reviews are the merge loop's signal, not feedback.
+
+The PR maps back to a dispatch two ways: a `lobstah/<uuid>` branch names it
+directly, and any other branch — a soaked session's PR — resolves through
+the PR URL its worker reported as evidence (`report done --pr <url>`). A PR
+that maps to neither is not lobstah's to answer.
+
+Each feedback **round** is keyed by the newest feedback event, so a new
+comment after a round completes opens the next round, while the same standing
+feedback never double-dispatches. Rounds on one PR serialize — a round that
+arrives while the previous one runs buffers until it finishes — and each
+round sets `followUp` to the latest session in the chain (the previous
+round, else the implementation dispatch), so feedback lands on the context
+that made the choices; a fully culled chain starts cold and reads the thread
+like anyone else. A rebase chore starts cold on purpose — the conflict is
+about commits the original session never saw.
 
 ### Claiming
 
@@ -339,7 +357,7 @@ Pickup's three loops and the daemon absorb that whole layer:
 | Fleet-script job | Fate |
 |---|---|
 | Poll tracker, dispatch assigned issues | Dispatch loop, issue rule |
-| Watch PRs for review feedback | Dispatch loop, review rule |
+| Watch PRs for review feedback | Dispatch loop, feedback rule |
 | Per-dispatch outcome checks and cron re-arms | Daemon supervision + `report` |
 | Merge approved PRs | Merge loop |
 | Detect in-progress issues nothing backs | Dead/wedged half → daemon; tracker-drift half → reconciliation loop |

package/docs/vocabulary.md

@@ -137,3 +137,39 @@ Delivery is level-triggered and at-least-once, like dispatch attention:
 events stand until the owner consumes them. One continuation dispatch in
 flight per watch; later events buffer and fork from the latest session in
 the chain.
+
+## Soaking contract
+
+A **soaking trap** is a live interactive session that volunteered as a worker
+through `lobstah soak` — the validated write path; nothing else touches
+`soaking/`. Sub-agent workers are the traps lobstah sets itself; a soaking
+session is a trap already in the water, and dispatch drops bait into it
+before building a new one. **Owner:** `packages/core/src/soak.ts`.
+**Enforcement:** sign-on is refused from a repo's primary checkout (never
+claimable) and when another session already soaks the same worktree.
+
+| Word | Meaning |
+| ---- | ------- |
+| `soak` | Sign a session on: it parks at turn end (Stop hook) and takes matching bait from the work queue. `--one` stows after the first catch. |
+| `stow` | Sign a session off; an open catch goes back to the queue (a cancelled one finalizes as failed). |
+| bait address | `--for session:<id>` on a dispatch targets one soaking session. Addressed bait waits for its trap until the registration is gone; unaddressed bait defers to a parked matching trap for `[soak].deferSecs`, then the daemon spawns headless. |
+| catch | The active dispatch a soaking session claimed (`claim.json` in the active dir). One catch per trap; one active item per worktree. The daemon never spawns or restarts it — the session's reports are its liveness. |
+| ghost trap | A registration whose heartbeat lapsed past `[soak].ttlSecs` — a lost trap that keeps fishing. The sweep hauls it out and requeues its catch. A fresh report on the catch keeps a mid-turn session out of the sweep. |
+
+Delivery routes by ownership, same as watches: a continuation for a chain
+claimed by a live soaking session is addressed back to that session; once it
+ghosts, the same bait forks headless. Sessions are never conscripted — a
+thread works bait only after opting in.
+
+## Exit codes
+
+The CLI's exit-code contract, aligned with axi.md P6. **Owner:**
+`apps/cli/src/main.ts` (`UsageError`) and `apps/cli/src/usage.ts` (the
+registry that decides what parses).
+
+| Code | Meaning |
+| ---- | ------- |
+| `0` | Success — including definitive empty results. |
+| `1` | Error: the command was well-formed but could not do its job. |
+| `2` | Usage mistake: unknown command, flag, or subverb. The error names the offender and prints the command's usage card. Flags in a free-text tail (a `send` message, a `report` note) are never validated — prose may contain anything. |
+| `3` | `man wait --timeout` elapsed with nothing to report. Its own code so `while lobstah man wait` loops still terminate on timeout while `2` stays unambiguous. |

package/package.json

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