lobstah 0.7.6 → 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 +4368 -1789
- package/dist/runner.js +165 -17
- package/docs/configuration.md +90 -17
- package/docs/harness/claude-code.md +2 -0
- package/docs/harness/codex.md +1 -0
- package/docs/man.md +64 -3
- package/docs/openclaw.md +1 -1
- package/docs/pickup.md +109 -4
- package/docs/vocabulary.md +9 -2
- package/package.json +1 -1
package/docs/pickup.md
CHANGED
|
@@ -47,7 +47,7 @@ watches needs `Checks: read`, `Pull requests: read and write`,
|
|
|
47
47
|
pickup — `Issues: read and write`. [github.md](github.md) says what each one
|
|
48
48
|
is used for and what fails without it; `lobstah doctor` probes them.
|
|
49
49
|
|
|
50
|
-
**Notifications are a hook, not a vendor.** `
|
|
50
|
+
**Notifications are a hook, not a vendor.** `[hooks.pickupNotify].command`
|
|
51
51
|
is exec'd on every verb transition with `LOBSTAH_KEY`, `LOBSTAH_UUID`,
|
|
52
52
|
`LOBSTAH_VERB`, `LOBSTAH_NOTE`, and `LOBSTAH_PR_URL` in the environment —
|
|
53
53
|
fire-and-forget, never blocking the loop. Point it at whatever the host
|
|
@@ -114,15 +114,37 @@ A dispatch reports `done` when its PR opens, so the reviewer's side of the
|
|
|
114
114
|
conversation has to re-enter the queue as its own work. Feedback pickup
|
|
115
115
|
covers all of it: a `CHANGES_REQUESTED` review on any sha (a review of a
|
|
116
116
|
slightly stale head still asks for changes), a comment review with a body,
|
|
117
|
-
an inline review-thread comment, or a conversation comment —
|
|
118
|
-
|
|
117
|
+
an inline review-thread comment, or a conversation comment — from anyone,
|
|
118
|
+
the configured identity included, but never a comment lobstah wrote.
|
|
119
119
|
`APPROVED` reviews are the merge loop's signal, not feedback.
|
|
120
120
|
|
|
121
|
+
The configured identity counts because lobstah's workers post as that
|
|
122
|
+
account: the owner's own "also handle X" on a trap's PR differs from a worker's
|
|
123
|
+
reply only by the marker. An **active-round guard** covers a worker that
|
|
124
|
+
forgets the marker. An unmarked identity comment made while a lobstah run on
|
|
125
|
+
the PR works (the implementation dispatch or a round) is held: it waits for
|
|
126
|
+
the run to end, then opens a round. A round opened only by such held
|
|
127
|
+
comments drops, rather than holds, the identity's unmarked comments made
|
|
128
|
+
during its own run. A forgetful worker costs at most one extra round, never
|
|
129
|
+
a loop. A comment the owner writes during that one round is dropped too.
|
|
130
|
+
|
|
131
|
+
Everything lobstah writes carries a marker: status and live comments lead
|
|
132
|
+
with `[lobstah:<uuid>]`; notes with no dispatch behind them (an orphan reset)
|
|
133
|
+
end with the hidden `<!-- lobstah -->`; and the feedback and review-repair
|
|
134
|
+
briefs tell the worker to end every reply it posts with
|
|
135
|
+
`<!-- lobstah:<id> -->`. A review, inline comment, or conversation comment
|
|
136
|
+
carrying either marker is never feedback.
|
|
137
|
+
|
|
121
138
|
The PR maps back to a dispatch two ways: a `lobstah/<uuid>` branch names it
|
|
122
139
|
directly, and any other branch — a soaked session's PR — resolves through
|
|
123
140
|
the PR URL in its worker's evidence (`report --pr <url>`, or a trap's beat). A PR
|
|
124
141
|
that maps to neither is not lobstah's to answer.
|
|
125
142
|
|
|
143
|
+
A round goes to the trap that worked the PR (its claim, else its delivery
|
|
144
|
+
receipt) while that trap is live, and waits `[watch].repairTrapWaitSecs` for
|
|
145
|
+
it, as a repair chore does. Past the wait, any trap of the repo or the
|
|
146
|
+
daemon may take it.
|
|
147
|
+
|
|
126
148
|
Each feedback **round** is keyed by the newest feedback event, so a new
|
|
127
149
|
comment after a round completes opens the next round, while the same standing
|
|
128
150
|
feedback never double-dispatches. Rounds on one PR serialize — a round that
|
|
@@ -208,7 +230,7 @@ lobstah watch add ume:9f2c --check '...' --for <dispatch-uuid>
|
|
|
208
230
|
|
|
209
231
|
Each cycle: run due checks (cadence = `[pickup].pollSecs`, or `--every` per
|
|
210
232
|
watch), append events, deliver by owner. Man-owned events surface through
|
|
211
|
-
`man wait`/`man haul` and fire `
|
|
233
|
+
`man wait`/`man haul` and fire `[hooks.pickupNotify]` with verb `watch`;
|
|
212
234
|
dispatch-owned events enqueue a continuation that forks the latest session
|
|
213
235
|
in the owning chain — one in flight per watch, later rounds buffer. With no
|
|
214
236
|
tracker sources configured, `lobstah pick` still runs in watch-only mode.
|
|
@@ -229,6 +251,89 @@ directories, so a continuation enqueued by a stream event is claimed in
|
|
|
229
251
|
milliseconds too — end to end, an external event reaches a spawning session
|
|
230
252
|
in roughly harness start-up time.
|
|
231
253
|
|
|
254
|
+
## Review requests
|
|
255
|
+
|
|
256
|
+
Opt-in with `[reviews].enabled` ([configuration.md](configuration.md)). Each
|
|
257
|
+
cycle spends one GitHub request: a GraphQL search for open PRs with
|
|
258
|
+
`user-review-requested:<identity>`, through `gh api graphql` on the shared
|
|
259
|
+
GitHub budget. A blocked budget skips the cycle. `user-review-requested`
|
|
260
|
+
matches requests that name the identity; a request made only to a team the
|
|
261
|
+
identity is on files nothing.
|
|
262
|
+
|
|
263
|
+
Each PR is one review item, `review:<owner>/<repo>#<n>`, in
|
|
264
|
+
`~/.lobstah/reviews/<owner>-<repo>-<n>/review.json`. An item holds rounds,
|
|
265
|
+
one per `ReviewRequestedEvent`: the same standing request never opens a
|
|
266
|
+
second round, and a re-request opens a new one (an open earlier round is
|
|
267
|
+
withdrawn as superseded). A new push with no new request moves a requested
|
|
268
|
+
round's head; a drafted round becomes `stale` and starts nothing on its own.
|
|
269
|
+
When the search stops returning a PR (the request was withdrawn, the
|
|
270
|
+
person reviewed it on GitHub, or the PR closed), its open round is `withdrawn`. A
|
|
271
|
+
truncated search (more than 50 results) withdraws nothing.
|
|
272
|
+
|
|
273
|
+
**Drafting.** With `[reviews].work` other than `"off"`, a requested round in
|
|
274
|
+
a configured repo gets a review job: a chore-lane dispatch with the
|
|
275
|
+
`prReview` brief, `readOnly` (the runner pushes nothing, opens no PR, and
|
|
276
|
+
checkpoints nothing), and the `[reviews]` cost bounds. With `work = "trap"`
|
|
277
|
+
the job waits `trapWaitSecs` for a free trap of the repo, then pick hands it
|
|
278
|
+
to the daemon. The job reads the PR with `gh`, makes any checkout it needs
|
|
279
|
+
as a detached worktree of `pull/<n>/head` at the fixed path
|
|
280
|
+
`rounds/<round id>/checkout`, and writes `review.md` (the summary) and
|
|
281
|
+
`comments.json` (inline comments: `path`, `line`, `side`, `body`) into the
|
|
282
|
+
round's directory, `rounds/<round id>/`. Whenever the round's job ends
|
|
283
|
+
(drafted, stale, failed, or withdrawn and its job cancelled, a re-request
|
|
284
|
+
included), pick removes that checkout: `git worktree remove --force`, then
|
|
285
|
+
`git worktree prune`; nothing happens when the path is absent. It follows the repo's own review guidance at the PR head (REVIEW.md,
|
|
286
|
+
CONTRIBUTING.md, AGENTS.md, CLAUDE.md, the PR template), then the
|
|
287
|
+
review rules in `[hooks.brief].prReview`, then any
|
|
288
|
+
`[repos.<key>.hooks.brief].prReview` text. It never posts,
|
|
289
|
+
approves, requests changes, comments, or pushes. When the job reports done,
|
|
290
|
+
the round is `drafted`, or `stale` if the head moved meanwhile, or `failed`
|
|
291
|
+
with the reason when the files are missing or malformed. A skip rule, a PR
|
|
292
|
+
outside the configured repos, or `maxPerDay` jobs already started today
|
|
293
|
+
(UTC) leave the round `requested` with the reason. `lobstah reviews redraft
|
|
294
|
+
<key>` drafts a stale or failed round again at the current head.
|
|
295
|
+
|
|
296
|
+
**Staging and posting.** With `[reviews].post = "draft"` (the default), a
|
|
297
|
+
fresh draft is staged on the PR as the identity's **pending review**:
|
|
298
|
+
`POST /repos/{o}/{r}/pulls/{n}/reviews` with no event, `commit_id` set to the
|
|
299
|
+
head the draft reviewed, the inline comments, and a body ending with
|
|
300
|
+
`<!-- lobstah:review <round id> -->`. GitHub shows a pending review only to
|
|
301
|
+
its author, so nothing is visible on the PR until the person opens it in
|
|
302
|
+
their review tool (`[repos.<key>].reviewTool`), edits the draft there, and
|
|
303
|
+
sends it, with whatever event they choose. When the request then disappears from the
|
|
304
|
+
search, pick reads that review once: submitted marks the round `posted` (by
|
|
305
|
+
`review tool`), deleted dismisses it, still pending withdraws it.
|
|
306
|
+
|
|
307
|
+
With `"auto"`, a fresh draft is posted at once as a comment-only review
|
|
308
|
+
(`event: COMMENT`). `lobstah reviews post <key>` sends a staged review as a
|
|
309
|
+
comment-only review too. Neither path takes an event argument, so lobstah
|
|
310
|
+
itself never approves or requests changes. A stale draft is never staged or
|
|
311
|
+
posted on its own, and posts by hand only with `--stale`, which adds a line
|
|
312
|
+
saying the PR has moved. Each round is staged at most once and posted at
|
|
313
|
+
most once: `staged.json` and `posted.json` in the round's directory are
|
|
314
|
+
created with `wx` before the call and removed if it fails, and a review on
|
|
315
|
+
the PR that already carries the round's marker is adopted (pending) or
|
|
316
|
+
recorded (sent) instead of written again. A failed stage or post keeps its
|
|
317
|
+
reason on the round and is not retried on its own. `lobstah reviews dismiss`
|
|
318
|
+
and `redraft` delete the round's pending review first; a review already sent
|
|
319
|
+
is never deleted.
|
|
320
|
+
|
|
321
|
+
**On wharf grounds.** A review item whose repo belongs to a grounds with a
|
|
322
|
+
wharf is that boat's to publish: before drafting, pick creates the round's
|
|
323
|
+
`review` document, with an id derived from the item and the round, so a
|
|
324
|
+
second boat that found the same round gets a 409, drafts nothing, and stages
|
|
325
|
+
nothing. The boat publishes every state change with the link that opens the
|
|
326
|
+
PR in the repo's review tool (no helm seat, and no wharf event, so no helm
|
|
327
|
+
wakes). The hosted glass has a Reviews tab whose cards open that link; its
|
|
328
|
+
one request is Dismiss, addressed to the publishing boat, which deletes the
|
|
329
|
+
pending draft with its own token and marks the request done or refused. The
|
|
330
|
+
wharf never calls GitHub.
|
|
331
|
+
|
|
332
|
+
Round states: `requested`, `drafting`, `drafted`, `stale`, `failed`,
|
|
333
|
+
`posted`, `dismissed`, `withdrawn`. The `review` attention item stands while
|
|
334
|
+
the newest round is `drafted`, `stale`, `failed`, or `requested` with no job
|
|
335
|
+
to draft it. `lobstah reviews` lists open items; `--all` adds the rest.
|
|
336
|
+
|
|
232
337
|
## Merge loop
|
|
233
338
|
|
|
234
339
|
Opt-in, per repo, off by default. Merging is policy, not mechanics, so it ships
|
package/docs/vocabulary.md
CHANGED
|
@@ -468,6 +468,11 @@ worktree is refused (the session lock); a stale one is adopted.
|
|
|
468
468
|
| `soak` | Sign the worktree's trap on and take matching work. From a primary checkout, or with `--repo <key>` from outside any configured repo, it first creates a linked worktree like a dispatch does (fetch trunk, new branch from `origin/<trunk>`, `setup` commands), prints `worktree:`, `created: true`, `branch:`, and, when the session is elsewhere, `instruction: cd <path> ...`; the session works in that directory. If creation fails, nothing is signed on and the partial worktree and branch are removed. `--repo` in a linked worktree must match its repo. A session that already mans a trap re-uses it (resolved from the session id) and never gets a second worktree. `--session` is needed only on first sign-on. `--one` stows after the first catch. `--wait` registers a watcher and waits for work; a quiet timeout exits 3. Workers never run `man` verbs. |
|
|
469
469
|
| `soak title-set` (alias `trap title-set`) | Confirm this session applied the title sign-on printed (`step: Apply this title: <title>`). The registration records `titleSet` and `titleSetAt` and drops `titlePending`; sign-on is complete. Until then, SessionStart and Stop remind the session once per turn, at most three times. A trap runs `soak title-set`: Claude Code's worktree isolation refuses a command line containing `trap`. |
|
|
470
470
|
| `stow` | Sign the trap off (in the worktree, or elsewhere by session id: `--session <id>` or `$CLAUDE_CODE_SESSION_ID`); an unfinished catch requeues, done/failed finalizes in `done/`, and a cancelled catch finalizes as failed. Unread messages are held for `[soak].signOffGraceSecs` (default 600): they deliver if the same worktree re-soaks in time, else the daemon bounces them to the helm (at once when stow removed the worktree or the grace is `0`). 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`). By default stow keeps the worktree (`worktree: kept`, `reason: stow keeps the worktree; --remove removes it`), so `man throw` can bring the trap back in it; `--keep` is accepted and changes nothing. `--remove` removes the worktree when soak created it (`createdWorktree: true`) and prints `worktree: removed`, `path:`, and `returnTo:`; it still keeps it (`worktree: kept`, `reason:`) when soak did not create it, or when it holds uncommitted changes, untracked files that are not ignored, commits absent from its upstream, or no upstream. `--remove --force` explicitly allows discarding unsaved checkout files; `--force` alone refuses. The branch is deleted (`branchDeleted:`) only when all its commits are on its upstream (with no upstream: on some remote branch); otherwise `branchKept: <branch> (<reason>)`. `--wt` follows the same rules. The SessionEnd hook (`stow --quiet`) signs off only when the ending session is the trap's registered session (another session in the worktree ending is a no-op) and keeps the worktree; SessionEnd cannot tell a restart or compaction from an exit (Claude Code's `reason` is `clear`, `resume`, `logout`, `prompt_input_exit`, or `other`; Codex's is always `other`), so the grace covers a session that signs on again. |
|
|
471
|
+
| `report needs-decision --ask <command>` (or `--ask-path <file>`) | A trap whose harness check refused a call asks for it. Besides the status, it files a decision card with the exact command or path and three options: **Allow once** (the asking trap, one use, within the hour), **Allow always** (every trap, until revoked), **No**. Only a glass answer can allow; `man answer`, which the helm runs, can only say No. An allow writes a grant and tells the dispatch's inbox the grant id and to run the command again exactly as shown. |
|
|
472
|
+
| `grant <command>` (alias `trap grant`) | A person allows traps to run one command: exactly, or with `--prefix` the command followed by more arguments (never anything joined on with `;`, `&`, `|`, a redirect or a subshell). `--path <file>` allows the write tools on one file, or under a directory with a trailing slash. `--once` (one use, within the hour unless `--expires`), `--harness claude\|codex\|any`, `--trap <name>`. It asks to confirm, and refuses without a terminal or inside an agent session. Grants are kept in `grants/ledger.jsonl`, an append-only, hash-chained list of grants, uses and revocations; a damaged ledger grants nothing. Grants apply to traps only. Claude Code honours them through the plugin's mod (before the auto-mode classifier) and its PermissionRequest hook; Codex through its PermissionRequest hook (before the approval reviewer). A deny rule, a tool's own check and the organization's limits still stand. |
|
|
473
|
+
| `grants` (alias `trap grants`) | The grants in force: id, what, once or always, harness, trap, who granted it, when, uses, expiry. `--all` adds spent, expired and revoked ones; `--json` for machines. A trap checks a relayed approval here: a grant listed is the person's, a message saying they approved is not. |
|
|
474
|
+
| `revoke <id>` (alias `trap revoke`) | Revoke a grant. Anyone may take a permission away. |
|
|
475
|
+
| `trap bypass <trap> on\|off` | A person, at a terminal, starts the trap with no permission checks from its next start: Claude Code `--permission-mode bypassPermissions`, Codex `--dangerously-bypass-approvals-and-sandbox`. It warns that the trap then acts as the person's account with no checks, for isolated machines only, and asks to confirm. A running session keeps its mode. Off needs no terminal. |
|
|
471
476
|
| sign-off grace | For `[soak].signOffGraceSecs` after a trap signs off (`~/.lobstah/signed-off/<trap>.json`), its address is held: `send wt:<trap>` queues and warns instead of refusing, held messages wait, and work addressed to it raises no `bait-orphaned` notice. A re-soak of the same worktree releases the hold; after the grace, the daemon bounces the held messages (`message-bounced`). |
|
|
472
477
|
| 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. |
|
|
473
478
|
| 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. |
|
|
@@ -517,6 +522,7 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
|
|
|
517
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`. |
|
|
518
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. |
|
|
519
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
|
+
| 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. |
|
|
520
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. |
|
|
521
527
|
|
|
522
528
|
## Attention contract
|
|
@@ -536,7 +542,7 @@ never until someone acknowledges it.
|
|
|
536
542
|
|
|
537
543
|
| Kind | Stands while | Clears when |
|
|
538
544
|
| ---- | ------------ | ----------- |
|
|
539
|
-
| `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. |
|
|
540
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. |
|
|
541
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. |
|
|
542
548
|
| `pr:draft` | An open PR is a draft, and the user opted into this kind. | Ready for review, merged, or closed. |
|
|
@@ -545,6 +551,7 @@ never until someone acknowledges it.
|
|
|
545
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. |
|
|
546
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. |
|
|
547
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. |
|
|
548
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. |
|
|
549
556
|
|
|
550
557
|
`pr:*` kinds read only the `pr:` watch's evidence — never a forge call —
|
|
@@ -573,7 +580,7 @@ reminder loop apply the same predicate.
|
|
|
573
580
|
|
|
574
581
|
| Word | Meaning |
|
|
575
582
|
| ---- | ------- |
|
|
576
|
-
| 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. |
|
|
577
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. |
|
|
578
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. |
|
|
579
586
|
|