lobstah 0.2.0 → 0.3.0

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/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.0",
+  "version": "0.3.0",
   "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
   "license": "MIT",
   "author": "aequitas labs LLC",