lobstah 0.1.2 → 0.2.1

package/docs/lobsterman.md

@@ -86,7 +86,11 @@ The verdict distinguishes states that look identical from the outside:
 Below the verdict: counts (queued, active, chores, done/failed last 24h), the
 unanswered questions with how long they have waited, and one row per work
 item — tracker key, its dispatch chain (original → swaps → review follow-ups),
-its PR, and the PR's merge-gate status. Gate status comes from the [merge
+its PR, the PR's merge-gate status, and any external source the chain is
+watching (a ume review session, a CI run). Watches join the same way the
+merge view does — from disk. A man-owned watch with unconsumed events counts
+as `needs-attention` with its age; a dispatch-owned one annotates its story
+(the wake is machinery's job, not the human's). Gate status comes from the [merge
 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.
@@ -94,11 +98,14 @@ emits the full report for dashboards and scripts to render.
 ## Getting woken instead of asked
 
 Three escalation tiers, least to most invasive. All are built on
-`lobstah man wait`: block until a dispatch needs attention, print the event and
-what to do next, exit. It is **level-triggered for attention states** — if a
-`needs-decision` is already standing when it starts, it returns immediately —
-so a gap between one watcher exiting and the next arming can never lose an
-event.
+`lobstah man wait`: block until a dispatch — or a watched external source
+(`lobstah watch add`, e.g. a ume review session) — needs attention, print the
+event and what to do next, exit. It is **level-triggered for attention
+states** — if a `needs-decision` or an unconsumed watch event is already
+standing when it starts, it returns immediately — so a gap between one
+watcher exiting and the next arming can never lose an event. When no pick
+process is running, `man wait` runs due watch checks itself, so watching
+works with every service stopped.
 
 **Tier 1 — a push for the human.** Set the daemon's hook and forget it:
 
@@ -134,6 +141,9 @@ 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:
 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

package/docs/pickup.md

@@ -156,6 +156,45 @@ with none of the webhook plumbing.
 
 ---
 
+## Watch loop
+
+Pick's third loop family: standing outbound polls on anything external with
+a CLI that can answer "anything new since cursor N?" — a ume review session,
+a CI run. Registration goes through `lobstah watch add <key> --check <cmd>`
+(the validated write path; the check contract and word set live in
+[vocabulary.md](vocabulary.md#watch-contract)):
+
+```bash
+# an interactive session pushes a plan for review, then stops blocking on it
+lobstah watch add ume:9f2c --check 'ume events 9f2c --since {cursor} --json'
+
+# a worker pauses on a review round; events fork a continuation of its chain
+lobstah watch add ume:9f2c --check '...' --for <dispatch-uuid>
+```
+
+Each cycle: run due checks (cadence = `[pickup].pollSecs`, or `--every` per
+watch), append events, deliver by owner. Man-owned events surface through
+`man wait`/`man haul` and fire `notifyCommand` with verb `watch`;
+dispatch-owned events enqueue a continuation that forks the latest session
+in the owning chain — one in flight per watch, later rounds buffer. With no
+tracker sources configured, `lobstah pick` still runs in watch-only mode.
+`man wait` runs due checks itself when no pick process is stamping them, so
+watches work with every service stopped.
+
+**Streams — the latency optimization.** `--stream <cmd>` names a long-lived
+process (spawned with `{cursor}` substituted) that emits the same event
+objects as NDJSON lines, plus bare `{"cursor": "N"}` checkpoints. Pick holds
+one child per streaming watch and delivers each line the moment it arrives —
+milliseconds instead of the poll interval. The queue contract's rule applies
+one layer up: **watch as an optimization, poll as the guarantee** — appends
+dedupe by `seq`, so the cadence check re-seeing a streamed event is a no-op,
+and a dead stream just means cadence-only until the next cycle respawns it.
+Stream and cadence events feed one serialized executor, so pick's state stays
+single-writer. The daemon completes the fast path: it fs.watches the queue
+directories, so a continuation enqueued by a stream event is claimed in
+milliseconds too — end to end, an external event reaches a spawning session
+in roughly harness start-up time.
+
 ## Merge loop
 
 Opt-in, per repo, off by default. Merging is policy, not mechanics, so it ships

package/docs/vocabulary.md

@@ -116,3 +116,24 @@ Bucket transitions are atomic renames; the directory *is* the state.
 | `ok`   | Works as configured. |
 | `warn` | Degraded or optional — dispatches may still run (e.g. one harness missing, daemon not running). |
 | `fail` | Broken configuration or missing requirement — fix before relying on lobstah. |
+
+## Watch contract
+
+A **watch** is a standing outbound poll on something external (a ume review
+session, a CI run) registered through `lobstah watch add` — the validated
+write path; nothing else touches `watches/`. **Owner:**
+`packages/core/src/watch.ts`. **Enforcement:** check output that doesn't
+parse records `lastError` and advances nothing.
+
+| Word | Meaning |
+| ---- | ------- |
+| `check` | Shell command exec'd with `{cursor}` substituted; prints `{ "cursor", "events"?, "done"? }` JSON. Read-only and idempotent — pick and an inline `man wait` coordinate only by the `lastCheckedAt` stamp. |
+| `cursor` | Opaque progress marker, advanced only from successful check output. The stream of record: a crashed watcher resumes from it losslessly. |
+| `owner` | Who the events belong to: `man` (surface via `man wait`/`man haul` + notify) or `dispatch:<uuid>` (fork a continuation of that chain). Events are never unowned work. |
+| `done` | The source is finished (session closed, run complete); the watch retires after its last events are consumed. |
+| `stream` | Optional long-lived NDJSON command held by pick for ms-latency delivery; a pure optimization — appends dedupe by `seq`, the check remains the guarantee. |
+
+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.

package/package.json

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