lobstah 0.3.2 → 0.5.0

package/docs/configuration.md

@@ -60,6 +60,28 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 | `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. |
 
+## `[helm]` — the orchestrator seat (`lobstah man helm`)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `ttlSecs` | `1800` | Heartbeat age past which a helm registration is stale: the next `man helm` claims it without `--take`. The park and `man brief` heartbeat it. |
+| `reportSecs` | `900` | Minimum seconds between park-delivered digests for a helm session. The digest is also change-gated — quiet grounds deliver nothing regardless of cadence. |
+
+## `[grounds.*]` — helm territories
+
+One helm per grounds; a repo belongs to at most one grounds (`man helm`
+refuses on overlap or an unknown repo key). With no `[grounds.*]` configured
+there is one implicit `fleet` grounds covering every repo — the partition
+only exists when asked for.
+
+```toml
+[grounds.base]
+repos = ["homebase", "matcha"]
+
+[grounds.aequitas]
+repos = ["lobstah", "lavish"]
+```
+
 ## `[pickup]` — tracker loops (`lobstah pick`)
 
 | Key | Default | Meaning |

package/docs/lobsterman.md

@@ -18,6 +18,17 @@ 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.
 
+**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,
+a Codex session (hooks since v0.114), or anything with a terminal via the
+foreground loop (`man wait` for the lobsterman, `soak --wait` for workers)
+holds the same seat with the same verbs. Workers are equally mixed:
+dispatches pick their harness per item (`--harness claude|codex`), so a
+Codex helm can run Claude workers and the reverse. Sign-on records which
+harness took the helm, and `swap` moves an in-flight dispatch across
+harnesses mid-stream — the worktree, not the conversation, is the durable
+layer.
+
 ## Set it up
 
 1. Install lobstah, configure your repos, start the daemon
@@ -95,6 +106,64 @@ view](pickup.md#merge-view) pickup persists each tick, so PR state is at most
 one poll interval stale without tend making a single network call. `--json`
 emits the full report for dashboards and scripts to render.
 
+### The spyglass
+
+`lobstah glass [--port <n>]` serves tend as a live web page on 127.0.0.1
+(default port 4949): the fleet verdict and attention questions, every
+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. It is strictly read-only and consumes no
+cursor: looking through the glass changes nothing, so it needs no helm and
+threatens nothing. Links out are copyable commands (`lobstah attach`,
+`claude --resume`), never click-to-exec — localhost HTTP is reachable by
+any webpage, so the glass exposes no endpoint that acts.
+
+This is where "is the agent alive?" belongs: the helm's heartbeat age on a
+page, not periodic proof-of-life turns in a transcript.
+
+### The periodic report
+
+`lobstah man tend` is the full picture on demand; `lobstah man report` is the
+**delta** since the last acknowledged report — catches landed (with their
+notes and PRs), attention newly arisen, what still waits, and the fleet
+verdict. It advances a "reported through" cursor when it prints — the
+explicit acknowledgment — so nothing is ever reported twice, and it says
+`no change` when the delta is empty rather than re-dumping state. Standing
+unanswered questions appear under `still-waiting` without counting as
+change — reminders (`remindSecs`) own re-firing those.
+
+Delivery is at-least-once by construction: the carriers that might not be
+read (a `man wait` timeout in a background task) only **peek** at the delta,
+so a digest lost with a dead task re-surfaces on the next timeout; only
+`man report` (or a hook-delivered park digest, which lands in-context by
+construction) marks it handled.
+
+Every carrier shares the cursor (per grounds, for a helm):
+
+- **The wait loop.** A `man wait` timeout (exit 3) prints the delta when
+  something changed, so a looping session gets periodic fleet reports for
+  free — see the loop idiom below.
+- **The park.** A helm session's Stop-hook park delivers the digest as a wake
+  at `[helm].reportSecs` cadence — including the landed-then-idle case, where
+  the last catches finish and nothing is left in flight to wake for.
+- **Direct call.** Anything with a clock — a gateway heartbeat, a cron — runs
+  `lobstah man report` and forwards the output when it is not `no change`.
+  Escalating a report to a human (a phone push) is the gateway layer's job,
+  not lobstah's.
+
+The loop idiom needs no harness scheduler, because the timer is lobstah's own
+blocking wait:
+
+```
+lobstah man wait --timeout 900
+# exit 0 → an event printed; handle it, then loop
+# exit 3 → timeout; the delta digest printed above it when something changed
+```
+
+A session running this loop reports into its own transcript whether or not a
+human is watching — come back later and the transcript is the report.
+
 ## Getting woken instead of asked
 
 Three escalation tiers, least to most invasive. All are built on
@@ -214,6 +283,46 @@ 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.
 
+## The helm: signing on as the orchestrator
+
+Soak enlists workers; `lobstah man helm` enlists the one who dispatches to
+them. Sign-on prints the **charter** — the persona and scope fences, written
+in Standard Technical English: triage and dispatch but never do the work,
+leave running catches to the daemon, judge the catch not the keystrokes, stay
+inside your grounds, report deltas not dumps. `man brief` re-injects the
+charter at every session start, so it survives restarts and compaction
+without anyone re-running anything. A helm registration also arms the
+Stop-hook park by itself — no `.lobstah-man` marker, no env var — and gates
+the park-delivered digest above.
+
+**One helm per grounds, enforced.** A **grounds** is a named territory: the
+subset of configured repos one orchestrator oversees (`[grounds.*]`; with
+none configured, one implicit `fleet` grounds covers every repo). A repo
+belongs to at most one grounds, so two orchestrators can never dispatch into
+the same territory. The registration is one file per grounds — the data model
+cannot hold two:
+
+- Sign-on against a **live** foreign holder refuses with guidance;
+  `--take` is the only force path, and it is deliberate: the displaced
+  session finds a stand-down notice at its next park and stops orchestrating.
+- A **stale** holder (heartbeat past `[helm].ttlSecs`) is claimable outright —
+  a dead orchestrator holds nothing.
+- `lobstah man relieve` steps down; a relieved session never re-takes on its
+  own.
+- The rule is strict: once a helm is claimed, `man wait` and `man report`
+  are reserved for the helm session (identify with `--session`), and no
+  other session parks as a lobsterman — those verbs consume the helm's
+  wakes and cursor. A grounds-scoped call is stricter still: it belongs to
+  that grounds' own helm, never a neighboring one. `man tend`/`man brief`
+  stay open to everyone; a stale helm reserves nothing. Workers never run
+  `man` verbs at all — their hookless park is `soak --wait`.
+- An identified `man wait` heartbeats the helm while it waits (waiting is
+  liveness) and defaults its digest to the helm's own grounds.
+- Consumption is grounds-partitioned: a helm's `man wait` and park consume
+  only events and notices for its own grounds' repos (events whose repo is
+  unknowable stay visible to all helms). Two helms never eat each other's
+  wakes.
+
 ## Soaking: a live session volunteers as a worker
 
 Workers are usually traps lobstah sets itself — fresh headless sessions in
@@ -226,22 +335,40 @@ get.
 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
+lobstah soak --wait             # hookless sessions: listen in the foreground
+                                # (re-runs need no flags — identity is the
+                                # worktree); exit 3 = quiet, run it again
+lobstah stow                    # sign off; an open catch requeues, unread
+                                # messages bounce back to the helm
 ```
 
-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.
+**Identity is the worktree.** Sign-on anchors a short trap id in
+`.lobstah-trap` and prints the trap's address (`wt:<id>`); 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
+registration as the liveness principal. Once soaking, the same Stop hook
+that parks a lobsterman parks the worker: at turn end it delivers messages
+first, then claims bait and wakes with the brief. While it works a catch,
+the park wakes it for `lobstah send` messages and cancels instead.
+
+Routing follows ownership, and **addressed work is sticky**:
+`dispatch --for wt:<trap>` waits for that trap and never falls back to a
+headless spawn — if the trap ghosts, the orphan surfaces as a helm notice
+(re-address, release, or cancel; `cancel` finalizes unclaimed queue items
+with an audit record). Delivery stamps a receipt into evidence. Unaddressed
+bait for a matching repo prefers a parked trap for `[soak].deferSecs`, then
+the daemon spawns headless. Conversational steering goes through
+`send wt:<trap> "..."` — a message, not bait: no branch, no catch, sender
+stamped, bounced to the helm when undeliverable.
+
+Liveness has two failure shapes with two remedies: a registration that
+parked before and went quiet past `[soak].ttlSecs` is a **ghost trap** —
+swept, catch requeued, noticed; one that **never parked** is a **defective
+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
+receives work.
 
 ## What the daemon gives your liaison for free
 

package/docs/vocabulary.md

@@ -140,26 +140,53 @@ 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.
+A **trap** is a worktree that volunteered as a worker seat through
+`lobstah soak` — the validated write path; nothing else touches `soaking/`.
+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.
 
 | 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. |
+| `soak` | Sign the worktree's trap on: it parks at turn end (Stop hook) and takes matching work. `--session` only on first sign-on; re-runs infer everything from the anchor file. `--one` stows after the first catch. `--wait` parks in the foreground — the hookless path: work prints plain, a quiet timeout exits 3, re-running re-arms. 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`). |
+| 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. |
+| ghost trap | A registration whose heartbeat 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 on the catch keeps a mid-turn session out of the 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. |
+| 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. 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. |
 
 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.
+claimed by a live trap is addressed back to that trap and stays sticky.
+Sessions are never conscripted — a thread works bait only after opting in,
+and nothing addressed is ever silently rerouted.
+
+## Helm contract
+
+The **helm** is the orchestrator seat: one interactive session signed on as
+the lobsterman for its grounds through `lobstah man helm` — the validated
+write path; nothing else touches `helm/`. Soak enlists workers; helm enlists
+the one who dispatches to them. **Owner:** `packages/core/src/helm.ts`.
+**Enforcement:** one registration file per grounds — the data model cannot
+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 lobsterman 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.
+
+| Word | Meaning |
+| ---- | ------- |
+| `helm` | Sign a session on as the orchestrator for one grounds. Prints the charter, arms the Stop-hook park without a marker file, and gates the periodic digest. Re-running from the same session is an idempotent re-sign. |
+| `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. |
+| charter | The helm's persona and scope fences, in Standard Technical English. Printed at sign-on and re-injected by `man brief` at every session start, so it survives restarts and compaction. |
+| digest | The delta since the reported-through cursor: catches landed, attention arisen, still-waiting, fleet verdict. Carried by `man report`, a `man wait` timeout, and — for a helm session, at `[helm].reportSecs` cadence — the park itself. Change-gated: an empty delta is never delivered. |
 
 ## Exit codes
 

package/package.json

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