lobstah 0.7.7 → 0.7.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -6
- package/dist/main.js +3094 -1751
- package/dist/runner.js +137 -14
- package/docs/configuration.md +73 -19
- package/docs/man.md +25 -8
- package/docs/openclaw.md +1 -1
- package/docs/pickup.md +109 -4
- package/docs/vocabulary.md +4 -3
- package/package.json +1 -1
package/docs/vocabulary.md
CHANGED
|
@@ -522,7 +522,7 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
|
|
|
522
522
|
| `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`. |
|
|
523
523
|
| 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 `home` grounds covering every repo; explicit `home` or `fleet` names are unchanged. Internal detail: the implicit local grounds permanently uses storage ID `fleet` (files, embedded fields and report/ack keys), so old and new CLI/daemon versions share one authority without moving data. `--grounds fleet` aliases `home` with a notice; raw storage addresses remain valid and copyable. Wharf grounds have no legacy alias. |
|
|
524
524
|
| 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. |
|
|
525
|
-
|
|
|
525
|
+
| todo | A reminder the helm keeps for itself (`lobstah todo add`), stored per grounds in `todos/<grounds>.json`. Shown in `man tend`, `man report`, and the glass, and re-injected beside the charter by `man brief`. Traps keep none. |
|
|
526
526
|
| 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 — in blocking park mode, at `[helm].reportSecs` cadence — the park itself. Change-gated: an empty delta is never delivered. |
|
|
527
527
|
|
|
528
528
|
## Attention contract
|
|
@@ -542,7 +542,7 @@ never until someone acknowledges it.
|
|
|
542
542
|
|
|
543
543
|
| Kind | Stands while | Clears when |
|
|
544
544
|
| ---- | ------------ | ----------- |
|
|
545
|
-
| `question` | The dispatch's last status is `needs-decision` or `blocked`. Held (`held: true`; not in the pet, the glass, or
|
|
545
|
+
| `question` | The dispatch's last status is `needs-decision` or `blocked`. Held (`held: true`; not in the pet, the glass, or `[hooks.notify]`) while a live helm for its grounds has not ended a turn since it was filed. Hidden while a decision on the same dispatch, asked at or after it, is on disk (when `decision` is enabled). | Any newer status entry, or a message newer than it. |
|
|
546
546
|
| `decision` | The helm asked the human with `lobstah man ask` and no answer is recorded. Key `decision:<rid>`. | Answered (the glass or `man answer`), withdrawn (`man ask --withdraw`), or replaced by a newer ask on the same dispatch. |
|
|
547
547
|
| `landed` | The dispatch is `done` or `failed` after its grounds' reported-through cursor (the grounds listing the repo, else `home`; at most 24 h back). Opt-in. | `man report` (or the helm park's digest) advances the cursor. |
|
|
548
548
|
| `pr:draft` | An open PR is a draft, and the user opted into this kind. | Ready for review, merged, or closed. |
|
|
@@ -551,6 +551,7 @@ never until someone acknowledges it.
|
|
|
551
551
|
| `pr:conflict` | An open PR conflicts with its base, and lobstah cannot repair it, has exhausted attempts, or is configured not to repair. | The merge state leaves `DIRTY`, or merged / closed. |
|
|
552
552
|
| `pr:ready` | An open, non-draft PR has no review condition, a mergeable state (`CLEAN`, `HAS_HOOKS`, or `UNSTABLE`), and no failed, pending, or unknown latest checks. It is approved or has at least one check, continuously on the same head for `readySettleSecs` (default 600; `0` is immediate). Attention reads re-evaluate expiry without requiring a new forge event. In a trunk-rooted same-repo stack of two or more non-fork PRs, member readiness appears only inside the one stack item; the stack wakes once. | Merged or closed, or the ready conditions stop holding; any not-ready observation or new head resets settling. |
|
|
553
553
|
| `stack-ready` | Every open member of a trunk-rooted same-repo base/head chain meets the identical `pr:ready` rule, including settling. Enabled with `pr:ready` (or explicitly with `stack-ready`). One persistent item per stack, born at the bottom PR and carried by surviving membership through growth, restacks and merges. Member ready/watch items are grouped inside it, not separate lobsters; a member's human problem (`pr:conflict`, `pr:checks`, `pr:review`, `pr:draft`) also stands as that member's own item and walks by its own kind. Approval Gate failures never create an item. Links open the current top PR, with member links inside. Only an all-ready stack walks (pet, glass lob, helm wake); a partly ready one is a quiet standing row in tend (shown as `stack-waiting`), the digest, and the existing glass group, worded `stack waiting: <n> of <m> ready`, with a settling member written as `ready, confirming for <x> more min`. Existing `pr:` watches discover missing links at their normal cadence; `lobstah watch add pr:<owner>/<repo>#<n>` follows a stack from any member. | Any member becomes unready or gets a new head; all ready again wakes once. Growth replaces the notice and wakes once when the larger stack is ready. Bottom-first merges keep the item and ack without a wake for unchanged surviving heads; a remaining lone PR returns to normal behavior. Legacy duplicates collapse without a wake. |
|
|
554
|
+
| `review` | Someone asked `[pickup.github].identity` for a review, and the PR's newest round is `drafted`, `stale`, `failed`, or `requested` with no job to draft it ([pickup.md](pickup.md), "Review requests"). Opt-in, and only with `[reviews].enabled`. Key `review:<owner>/<repo>#<n>`. | The round is posted, dismissed, or withdrawn (the request was withdrawn or the PR closed), or a job starts drafting it. Its state hash covers the round, its state and its head, so an ack holds until one of them changes. |
|
|
554
555
|
| `report` | A filed report (`report --report`, `man file`) has no ack for this filing. Opt-in. Key `report:<lane>:<uuid>` or `report:helm:<grounds>:<rid>`. | Not cleared: it stays listed until culled. Opening it on the glass acks it (`by: glass`, the first time kept; no wake, and a CLI or API read does not), `lobstah attention ack <key>` acks it, and a newer report in the same chain acks the older; an acked report no longer walks, and `man tend`'s `viewed` column shows when it was acked. Refiling it stands it again until it is opened again. |
|
|
555
556
|
|
|
556
557
|
`pr:*` kinds read only the `pr:` watch's evidence — never a forge call —
|
|
@@ -579,7 +580,7 @@ reminder loop apply the same predicate.
|
|
|
579
580
|
|
|
580
581
|
| Word | Meaning |
|
|
581
582
|
| ---- | ------- |
|
|
582
|
-
| ack | `~/.lobstah/acks/<item-key>.json` — `{ key, kind, stateHash, at, by }`, written only by `lobstah attention ack` (removed by `unack`, by the CLI's `man tend` / `attention` when its `stateHash` goes stale, and by `cull` when the item is gone). **Display-only**: it hides the item from the desktop pet and the glass lobs while the item's `stateHash` is unchanged; `man tend --json` keeps the item with `acked: { at, by }`, and `man wait`, the park, reminders, and `
|
|
583
|
+
| ack | `~/.lobstah/acks/<item-key>.json` — `{ key, kind, stateHash, at, by }`, written only by `lobstah attention ack` (removed by `unack`, by the CLI's `man tend` / `attention` when its `stateHash` goes stale, and by `cull` when the item is gone). **Display-only**: it hides the item from the desktop pet and the glass lobs while the item's `stateHash` is unchanged; `man tend --json` keeps the item with `acked: { at, by }`, and `man wait`, the park, reminders, and `[hooks.notify]` never read acks. Item keys: `<lane>:<uuid>` (question, landed), `decision:<rid>`, `pr:<owner>/<repo>#<n>` (all of a PR's `pr:*` kinds — one ack covers them), `watch:<key>`. `stateHash` covers the status entry (question, landed) or the PR's head sha plus every evidence field a `pr:*` kind stands on (not `observedAt`); for a ready PR, only the head sha. A ready ack is kept across same-head CI flaps and draft toggles, without hiding checks, conflicts, or review attention during the flap. A new head re-stands ready once after settling. |
|
|
583
584
|
| pet state | `~/.lobstah/pet/state.json` — `{ pid, at, ok, command, reason, consecutiveFailures, items, lastOkAt }`. The desktop pet's one write: it rewrites the file after each attention read (about every six seconds). `command` is the command that worked (`attention --json`, or `man tend --json` from an older CLI). `reason` says why the last read failed (timed out, non-zero exit, output that does not decode). Only `lobstah doctor` reads it, for its `pet` row: running means `pid` is alive and `at` is less than two minutes old. |
|
|
584
585
|
| budget stop | A headless runner's `failed` verb with a `budget:` note means its progress-extended active-work window reached the hard ceiling. This is out of time, not a code failure: the runner checkpoints eligible changes, pushes when enabled, names the saved branch/commit/draft PR, and invites `lobstah send <id> "continue"`. Paused `--waiting-on` time is excluded. |
|
|
585
586
|
|