lobstah 0.1.1 → 0.2.0

package/docs/lobsterman.md

@@ -0,0 +1,211 @@
+# The lobsterman: a single-liaison session on lobstah
+
+The pattern: you talk to **one** interactive agent — the lobsterman — and it
+runs the fleet: dispatching work, supervising, escalating only real decisions.
+Lobstah supplies the machinery for doing that locally without the liaison
+burning tokens on supervision.
+
+## The shape
+
+```
+you ⇄ liaison (interactive Claude Code / Codex session)
+            │  lobstah dispatch / status / send / cancel   (CLI, TOON output)
+            ▼
+     lobstah daemon ── worktree-isolated dispatches, supervised for free
+```
+
+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.
+
+## Set it up
+
+1. Install lobstah, configure your repos, start the daemon
+   ([README](../README.md#install)).
+2. Start an interactive session anywhere and paste this into the project's
+   agent instructions (`AGENTS.md` / `CLAUDE.md`), or just say it:
+
+```markdown
+You are my liaison for delegated coding work. For any task that should run in
+the background, dispatch it with the `lobstah` CLI instead of doing it inline:
+
+- `lobstah dispatch --repo <key> --brief-text "<full brief>"` — returns an id.
+  Write briefs that stand alone; the worker has no other context.
+- `lobstah status [<id>]`, `lobstah ls` — check progress when I ask, not on a loop.
+- `lobstah send <id> "<instruction>"` — steer a running dispatch.
+- `lobstah cancel <id>` — stop one.
+- A dispatch reporting `needs-decision` is waiting on ME — surface its question
+  immediately, then `lobstah send` my answer.
+- `done` means brief fulfilled with a branch + commits; report the evidence
+  (`~/.lobstah/state/<id>.evidence`) and never merge anything yourself.
+```
+
+That's the whole integration — the CLI is self-documenting (`lobstah help`)
+and its TOON output is built to be read by agents.
+
+## Taking over a worker
+
+Every dispatch **is** a real harness session, running under the same CLI you
+use by hand. So the crew is inspectable with tools you already have:
+
+- `lobstah attach <id>` — opens the worker's own session, in its worktree:
+  `claude --resume <sessionId>` or `codex resume <threadId>` under the hood.
+  Full conversation context survives — ask it "what did you do?", redirect it,
+  or keep working in the worktree yourself.
+- `lobstah logs <id> --follow` — the normalized event stream, live.
+- Session pickers in the harness's own tooling (`claude --resume` with no id,
+  the Claude/Codex desktop apps' session lists) show dispatch sessions too —
+  they're stored where the harness always stores them.
+
+Attach refuses while a dispatch is `working` (two writers, one session);
+follow the logs or `send` instead, or cancel and then attach.
+
+`lobstah swap <id> [--harness codex] [--model ...]` hands an in-flight
+dispatch to a fresh session: same worktree, same brief, plus an auto-generated
+progress note with the commits so far and any uncommitted changes.
+Conversations do not cross harnesses. The worktree is the durable layer, so
+the handoff carries everything that matters. Use swap to move work between
+subscriptions, escape a rate limit, or re-roll a session that went sideways.
+
+## Tending the string
+
+`lobstah man tend` is the whole-fleet pass — the lobsterman working every trap
+in one sweep. It prints a verdict and the story of each piece of work, from a
+pure disk read: no forge calls, no tokens.
+
+The verdict distinguishes states that look identical from the outside:
+
+| Verdict | Meaning |
+| --- | --- |
+| `daemon-down` | No fresh heartbeat — nothing is being supervised. |
+| `stalled` | Work queued, capacity free, daemon alive, nothing claiming — actually broken. |
+| `needs-attention` | An unanswered `needs-decision`/`blocked` is standing, with its age. |
+| `working` | Dispatches active or queued, nothing waiting on a human. |
+| `idle` | Everything drained; the quiet is real. |
+
+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, 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.
+
+## Getting woken instead of asked
+
+Three escalation tiers, least to most invasive. All are built on
+`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:
+
+```toml
+notifyCommand = "ntfy pub my-topic \"$LOBSTAH_VERB $LOBSTAH_ID: $LOBSTAH_NOTE\""
+```
+
+**Tier 2 — a background watcher in the liaison session.** The liaison runs
+`lobstah man wait` as a background task; when it exits, the harness's task
+notification wakes the session, and the printed `next:` line tells the agent
+exactly what to do — including re-arming. One watcher per wake is inherent to
+background tasks; the level-trigger makes the re-arm race harmless. Add to the
+liaison instructions:
+
+```markdown
+After dispatching work, run `lobstah man wait` as a background task. When it
+completes, follow its `next:` instruction, then re-arm it.
+```
+
+**Tier 3 — park the session on a Stop hook (Claude Code only).** A Stop hook
+that blocks on `lobstah man wait`, so the session never
+really idles — it parks for free and continues the moment something needs it.
+What this buys over tier 2 is not the wake. Both wake on events, and both
+cost a turn per wake. The difference: the re-arm is **structural instead of
+instructed**. Tier 2 works only as long as the model remembers to re-arm the
+watcher after every wake. A forgotten re-arm, a crashed watcher, or an
+interrupted turn leaves the session deaf until a human speaks. The Stop hook
+fires at every turn end, no matter what the model did. Supervision cannot
+lapse through instruction drift, and a blind stop mid-shift is impossible.
+
+The hook is a CLI command — `lobstah man haul` (the lobsterman hauls the
+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
+                            # directory with a .lobstah-man file then parks
+lobstah man init --marker   # also touch .lobstah-man (per-directory gate)
+```
+
+Idempotent, and it only appends to `hooks.Stop` — existing hooks and settings
+are preserved verbatim. What it writes:
+
+```json
+{ "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "lobstah man haul", "timeout": 14400 }] }] } }
+```
+
+`haul` gates itself twice: only a designated session parks (launch it with
+`LOBSTAH_MAN=1 claude`, or `touch .lobstah-man` for a per-directory gate), and
+only while dispatches are in flight — conversational turns end free. On an
+event it blocks the stop with the event as context and tells the agent the
+session re-parks automatically; on timeout or any error it silently allows
+the stop, leaving tier 1 as the backstop past the horizon.
+
+Two habits worth adding to a lobsterman session's instructions: run
+`lobstah man wait --peek` at session start (a wake consumed by a session that
+died mid-handling is still standing state — peek resurfaces it), and treat
+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.
+
+**Delivery guarantee.** Attention wakes are at-least-once with backoff. An
+unanswered question is reported immediately. While it still stands, it
+re-fires as a reminder every `remindSecs` (top-level config, default 900). So
+a wake consumed by a session that died mid-handling resurfaces on its own.
+Answering ends the reminders naturally, because the answer produces a new
+status entry. Set `remindSecs = 0` for pure at-most-once.
+
+**Any-harness fallback — the wrapper loop.** Tiers 2 and 3 lean on Claude
+Code features (background-task notifications, the Stop hook). For any other
+harness — or no interactive session at all — an outer loop blocking on `wait`
+spawns one fresh headless turn per event:
+
+```sh
+while out=$(lobstah man wait); do
+  codex exec "A dispatch needs attention: $out — handle it with the lobstah CLI."
+done
+```
+
+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.
+
+## What the daemon gives your liaison for free
+
+- Parallel work that can't collide — worktree per dispatch.
+- A crew that survives crashes: dead runners respawn (bounded), wedged ones
+  are killed and forked with a nudge, and everything reconciles from disk
+  after a reboot.
+- An honest six-verb status contract, validated at the write path, so the
+  liaison never has to parse prose to know where things stand.

package/docs/openclaw.md

@@ -0,0 +1,76 @@
+# OpenClaw integration
+
+Lobstah plugs into an [OpenClaw](https://github.com/openclaw/openclaw) fleet at
+two seams: a **gateway plugin** that gives agents typed dispatch tools, and the
+**pickup loops** that replace hand-rolled tracker polling scripts. Core knows
+about neither — both just write the same descriptors into the same directory.
+
+## Install the plugin
+
+On the gateway host (which should also run `lobstah daemon`):
+
+```bash
+git clone https://github.com/aequitas-labs/lobstah
+cd lobstah && pnpm install && pnpm build
+openclaw plugins install ./apps/node
+```
+
+Once lobstah is on npm, this becomes a one-liner with no clone:
+
+```bash
+openclaw plugins install lobstah-openclaw-plugin
+```
+
+## What agents get
+
+Four tools, registered for every fleet agent:
+
+| Tool | Does |
+|---|---|
+| `lobstah_dispatch` | Queue a supervised dispatch (repo key, brief, optional harness/model/followUp) — returns the id |
+| `lobstah_status` | Reconciled state of one dispatch or a table of everything active |
+| `lobstah_send` | Drop an instruction into a running dispatch's inbox |
+| `lobstah_cancel` | Request cancellation |
+
+Operators get `/lobstah [id]` as a chat command — status without waking a model.
+
+An agent asked in chat to "fix the flaky login test in myapp" hands the work
+to lobstah and stays responsive. Later it answers "how's it going?" from
+`lobstah_status`. The daemon does the actual supervision the whole time, for
+zero tokens.
+
+## Replacing scheduler scripts with pickup
+
+A typical fleet setup polls the tracker from cron/launchd scripts, dispatches
+a headless agent, re-arms check-ins, and merges approved PRs from more
+scripts. `lobstah pick` replaces that whole layer with one process — see
+[pickup.md](pickup.md) for the loops and [the config](pickup.md#dispatch-loop).
+
+The division of labor that falls out:
+
+- **Pickup** owns issue/review dispatch, tracker status comments, drift
+  reconciliation, and (opt-in) merges.
+- **The daemon** owns worktrees, liveness, wedge detection, restarts.
+- **Fleet agents** keep the judgment work: triage, escalation policy,
+  answering humans — and reach lobstah through the plugin tools when a request
+  becomes a dispatch.
+- **Notifications** ride `notifyCommand` — point it at your existing Slack
+  helper; lobstah stays vendor-free.
+
+Token minting for GitHub Apps fits the `tokenCommand` source directly
+(installation tokens expire hourly):
+
+```toml
+[pickup.github]
+tokenCommand = "gh-app-token.sh my-app"
+```
+
+## Keeping both alive
+
+Two long-running commands on the host, under whatever supervises processes
+there already (launchd on macOS, systemd on Linux):
+
+```
+lobstah daemon      # supervisor — holds no credentials
+lobstah pick        # tracker loops — holds the tokens
+```

package/docs/pickup.md

@@ -0,0 +1,358 @@
+# Pickup — tracker add-on
+
+**Local work pickup from Linear and GitHub, without webhooks.**
+
+Pickup is a poll loop that runs beside the daemon. It polls trackers outbound,
+translates matching items into queue descriptors, translates state files back
+into tracker updates, and — where enabled — merges approved PRs. It is the
+fourth caller: core never learns it exists.
+
+```
+Linear / GitHub  <──poll──  apps/pick  ──writes──>  queue/
+                 <──report──            <──reads───   state/  evidence  events
+```
+
+---
+
+## Why polling is the product, not the compromise
+
+Every existing tracker-driven agent needs inbound networking — OAuth apps plus
+a tunnel, often sold as the hosted tier's headline feature. A webhook target
+cannot run on a laptop behind NAT that sleeps.
+
+A poll loop has zero inbound surface. No listener, no tunnel, no public
+exposure. Offline means it doesn't poll; wake means it catches up. Latency is
+the poll interval — 30–60 seconds against tasks measured in minutes.
+
+This is the queue contract's own rule applied one layer up: watch as an
+optimization, poll as the guarantee.
+
+## Boundary
+
+Pickup holds tracker credentials, so it lives in `apps/`, never `packages/core`
+— the same rule that governs the bridge and the node plugin. Core stays free of
+network, OAuth, and tracker vocabulary.
+
+**Secrets never live in the config file.** Each source configures a token
+*source*, in precedence order: `tokenCommand` (exec'd and cached ~5 minutes —
+the fit for hourly-expiring GitHub App installation tokens, e.g. a
+`gh-app-token.sh`-style minting script), `tokenFile` (read per call, so
+rotation just works), or `tokenEnv` (read per call, so a wrapper can refresh
+it). This mirrors OpenClaw's own secret-reference pattern: config carries a
+reference, never the secret.
+
+**Notifications are a hook, not a vendor.** `notifyCommand` under `[pickup]`
+is exec'd on every verb transition with `LOBSTAH_KEY`, `LOBSTAH_UUID`,
+`LOBSTAH_VERB`, `LOBSTAH_NOTE`, and `LOBSTAH_PR_URL` in the environment —
+fire-and-forget, never blocking the loop. Point it at whatever the host
+already has (a Slack helper, `openclaw message send`); lobstah stays free of
+messaging vendors.
+
+**No LLM in the loop.** Issue-to-descriptor translation is mechanical. Judgment
+about an ambiguous issue belongs to the dispatched agent, which reports
+`needs-decision` — not to pickup. Fleet setups that wake an LLM to poll a
+tracker pay tokens for a mechanical translation; a deterministic program is
+the right tool, and it keeps token cost proportional to real work.
+
+---
+
+## Architecture
+
+```
+apps/pick/
+  sources/
+    linear/        # API key or OAuth app actor token
+    github/        # PAT or GitHub App installation token
+  loops/
+    dispatch/      # issues + review feedback → descriptors
+    reconcile/     # tracker state ⟷ lobstah state, both directions
+    merge/         # opt-in: merge approved PRs, dispatch rebases on conflict
+```
+
+One source interface, four methods:
+
+```ts
+interface Source {
+  poll(): WorkItem[]                    // items matching the pickup rules
+  claim(item: WorkItem): boolean        // tracker-side state transition
+  report(id: string, verb: Verb, evidence: Evidence): void
+  inbound(id: string): Message[]        // new human comments since last poll
+}
+```
+
+A source translates tracker vocabulary to lobstah vocabulary and nothing else.
+The three loops are tracker-agnostic and drive whichever sources are configured.
+
+---
+
+## Dispatch loop
+
+### Pickup rules
+
+| 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.
+
+### Claiming
+
+The tracker-side state transition is the cross-machine mutex. Moving the issue
+to In Progress (or applying a claim label) is pickup's atomic rename: two
+machines polling the same workspace cannot double-dispatch, because exactly one
+claim succeeds.
+
+Pickup owns the mapping from tracker item to dispatch UUID, in its own state
+directory. This is the design's rule — whoever dispatched holds the mapping — and
+it is what lets `report` and `reconcile` correlate without anything on the
+tracker knowing lobstah's identifiers.
+
+### Routing and briefs
+
+The descriptor's `repo` key resolves from config. The tracker never carries
+machine detail:
+
+```toml
+[pickup.linear]
+assignField = "delegate"             # agent token: Linear assigns agents via delegate
+startState  = "Todo"
+route       = { ENG = "myapp" }      # team key → repo key
+```
+
+GitHub routing needs no map: with no `repo` named in `[pickup.github]`, every
+`[repos.<key>]` that opted in with `pickup = true` and has a GitHub `origin`
+is polled, and the repo key doubles as the routing key. Opt-in is explicit —
+being configured for dispatch never makes a repo pickable by itself.
+
+The brief is assembled from the item — title, description, comments to date —
+through an optional per-repo template. The issue is the durable instruction's
+source; `brief.md` in `active/<uuid>/` remains the durable instruction itself.
+
+### Reporting
+
+Six verbs map to tracker vocabulary. The mapping is per-source and total — a
+verb with no mapping is a config error at startup, not a silent drop.
+
+| Verb | Linear (default) | GitHub (default) |
+|---|---|---|
+| `working` | In Progress + progress comment | comment |
+| `needs-decision` | comment + `needs-human` label | comment + label |
+| `blocked` | comment + `blocked` label | comment + label |
+| `paused` | comment | comment |
+| `done` | attach PR link, move to In Review | comment with PR link |
+| `failed` | comment with evidence, back to Todo | comment with evidence |
+
+### Inbox bridging
+
+`inbound()` turns new human comments on a claimed item into
+`inbox/<uuid>/NNN.msg` records. The tracker becomes the steering surface: a
+comment on the Linear issue reaches the running agent through the same
+between-turns delivery as any other inbox message — tracker-native steering
+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
+disabled and its config is explicit about who qualifies.
+
+```toml
+[pickup.github.merge]
+enabled          = true
+method           = "squash"
+approvers        = ["alice"]        # the floor: always qualify, on every PR
+assigneeApproves = true                # PR assignees also qualify…
+restrictedLabels = ["risk:high"]       # …except on PRs carrying any of these labels
+scope            = "own"               # only PRs authored by the configured identity
+```
+
+**Who qualifies is monotone by construction.** The qualifying set is
+`approvers`, plus the PR's assignees when `assigneeApproves` is on and no
+restricted label is present. A restricted label collapses the set to
+`approvers` — labels revoke the assignee relaxation, they never grant, replace,
+or subtract from the floor. Multiple restricted labels therefore compose
+trivially (any one collapses), and no label combination can make a PR
+unmergeable by everyone. If a label ever needs its own named approvers, that is
+a future *additive* grant key, not a replacement — replacement is how a policy
+locks itself out.
+
+The loop's doctrine, in full:
+
+- **Re-validate at the moment of merge, not at the poll tick.** State shifts
+  between observation and action; the gate check runs against a fresh fetch
+  immediately before the merge call. Any failure aborts and reports — never
+  merge on stale data.
+- **Trust the forge's merge-state rollup.** GitHub's `mergeStateStatus` already
+  encodes required-check semantics — `BLOCKED` means a required check failed,
+  `UNSTABLE` means only non-required checks failed and GitHub itself would
+  allow the merge. Re-implementing check-pass logic client-side is how you
+  drift from the forge's own rules.
+- **Dedup by approval, not by PR.** A specific approval merges at most once; a
+  new push invalidates it and the gate waits for a fresh one.
+- **Stacks merge through the forge's stack-aware path.** A PR in a native
+  stack goes through GitHub's asynchronous stack merge API; a standalone PR
+  through the ordinary merge call. `method` is per repo and applies to both.
+- **`scope = "own"` is the safety default.** Pickup merges work it dispatched.
+  Widening to human-authored PRs is a deliberate config change.
+
+### Conflicts dispatch, cleanly-behind updates
+
+A PR behind its base splits deterministically:
+
+| Condition | Action |
+|---|---|
+| Behind, no conflict | Update the branch through the forge API, re-enter the gate next tick |
+| Behind, real conflict | Write a rebase chore — brief: rebase onto base, resolve, push — and re-enter the gate when it completes |
+
+Rebase chores go through the **chore lane** (`~/.lobstah/chores/`, defined in
+the [design's queue contract](design.md#queue-contract)), never the primary queue. Same descriptor schema,
+same daemon, same supervision — but their own directories and their own
+concurrency budget, so machine-generated maintenance can't crowd the work
+queue, and `lobstah ls` stays a list of things a human asked for.
+
+Chores report to no tracker. The merge loop consumes the chore's status file
+directly, holds its own PR-to-chore mapping, and bounds the attempt at one: a
+failed rebase comments on the PR, applies the `needs-human` label, and stops.
+The doctrine stays whole — the deterministic program handles everything
+mechanical, and the moment resolution requires judgment it becomes a
+supervised dispatch. It just doesn't become *work*.
+
+---
+
+## Reconciliation loop
+
+The daemon owns dead and wedged *processes*. It cannot own tracker drift — an
+item that claims In Progress while nothing anywhere backs it is invisible to a
+component that, by design, has no tracker knowledge. The classification rule
+holds one layer up: absence of signal never means fine.
+
+Every poll, diff both directions:
+
+| Drift | Detection | Action |
+|---|---|---|
+| Orphaned item | In Progress, attributed to pickup, no live or completed UUID behind it | Comment, reset to the start state |
+| Orphaned dispatch | UUID active for an item now closed, reassigned, or de-scoped | Cancel the dispatch, note it in evidence |
+| Lost report | Dispatch `done`/`failed`, tracker never updated | Replay the report — the state file is the durable record, the tracker write is the retryable notification |
+
+An orphan verdict requires a trustworthy mapping — see
+[Pickup state](#pickup-state): a missing table entry is `unknown` and triggers
+a rebuild, never a reset.
+
+**Residual, by honesty:** same-machine reconciliation cannot detect
+whole-machine death — the reconciler dies with the laptop. The stale
+`executor.json` heartbeat covers that case, but only for a remote reader — a
+second machine's pickup, or a remote dispatcher. This is parity with the
+cron-script fleets it replaces, whose watchers also died with their host.
+
+---
+
+## Merge view
+
+The merge loop is already fetching the forge's view of every candidate PR each
+tick — so it persists what it saw (`pickup/merge-view.json`): per open PR the
+head sha, mergeable state, and gate verdict (`waiting-approval`,
+`behind-updated`, `conflict-chore:<uuid>`, `rebase-failed`, `blocked`,
+`draft`), and per PR that *left* the open set, its disposition — one extra
+lookup answers whether it merged or closed, so "merged in the last 24h" is
+complete even when a human pressed the button.
+
+This is what lets a status view report PR state without its own forge calls:
+`lobstah man tend` and any dashboard read the file, at most one poll interval
+stale. Observational, not load-bearing — deleting it loses nothing but
+history. It exists only where the merge loop runs (merge enabled).
+
+---
+
+## Pickup state
+
+Pickup's own state — the tracker-item-to-UUID mapping the loops correlate
+through, the merge loop's PR-to-chore table, per-source poll cursors — lives
+under `~/.lobstah/pickup/`, written with the same atomic-rename discipline as
+everything else on disk.
+
+The mapping is load-bearing for all three loops, so it gets durability by
+design rather than by trust:
+
+- **Reconstructible.** Every report comment pickup writes to a tracker embeds
+  the dispatch UUID. A lost table rebuilds from the tracker trail plus
+  `state/` — the durable-record, retryable-notification rule applied to
+  pickup's own memory.
+- **Missing is `unknown`, never orphaned.** Reconciliation must not reset an
+  In Progress item because the table lacks an entry for it. A missing mapping
+  triggers a rebuild, and only a rebuilt table may declare an orphan. Losing a
+  file must never cancel live work.
+
+---
+
+## What pickup replaces
+
+The typical hand-rolled fleet is a pile of cron/launchd scripts. One polls
+the tracker and dispatches a headless agent. One watches PRs for review
+feedback. One merges approved PRs. One hunts for issues marked in-progress
+that nothing is working on. Each dispatch also re-arms its own cron check.
+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 |
+| 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 |
+| Triage, escalation policy, answering humans | Not pickup's. Judgment stays agent-side |
+
+---
+
+## Non-goals
+
+- No webhooks, no inbound listener, no tunnel — ever. Inbound networking is the
+  category's tax; not paying it is the point.
+- No LLM in any loop. The moment a loop needs judgment, it dispatches.
+- No triage. Pickup acts on items already assigned and staged; deciding what
+  deserves an agent is upstream of it.
+- No cross-tracker abstraction leakage into core. Sources normalize at the
+  pickup boundary; the queue contract stays tracker-free.