lobstah 0.7.10 → 0.8.0

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.
@@ -157,6 +157,7 @@ send a continuation.
157
157
 
158
158
  | Key | Default | Meaning |
159
159
  |---|---|---|
160
+ | `codexStartSecs` | `600` | Seconds a Codex throw waits for sign-on and first park. Positive whole number; `man throw --timeout` overrides it. Other harnesses default to 180 seconds. A Codex timeout keeps its ticket valid for late sign-on and fences a duplicate launch; `stow --wt <trap>` withdraws it before retrying. |
160
161
  | `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. |
161
162
  | `claimIdleNoticeSecs` | `180` | Grace period after a trap claims a dispatch before the daemon raises a `trap-claim-idle` notice if the worker has not reported. Fresh park or tool heartbeats do not acknowledge delivery. The notice does not release the claim; the original brief is re-delivered at the trap's next park, including after it resumes under a new session id. |
162
163
  | `acceptWharfStarts` | `false` | Opt this boat into helm-authorized trap start requests from the hosted glass. The daemon starts only its configured harness in a configured repo, refuses unknown repos, and never starts an expired request. Manual hosted `soak` and `man throw --new --repo` also use the daemon broker; traps receive only dispatch-scoped tokens. |
@@ -178,6 +179,7 @@ send a continuation.
178
179
  | `idleWorkingNoticeSecs` | `60` | Explicitly idle trap whose last report is working: wake the helm with its full note. A live session-owned background wait exempts it. Tool activity or a new report clears it; reminders use the same backoff. `0` disables. |
179
180
  | `armGraceSecs` | `5` | Arm mode: when work is in flight and no live watcher is registered, the Stop hook polls this long for one before blocking — a `man wait` (or `soak --wait`) backgrounded just before the turn ended is usually still starting. A stale registration gets the same window. |
180
181
  | `todoStaleDays` | `3` | Open helm todos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
182
+ | `chat` | `"full"` | Default chat detail: `"full"` or `"brief"`. Brief mode points at cards instead of repeating detail and keeps routine wakes quiet. `lobstah man chat brief\|full [--grounds <name>]` or glass Settings overrides it for that grounds' signed-on helm, effective next turn, without a restart or config edit. The override stays with the seat on re-sign/takeover and ends when relieved. |
181
183
 
182
184
  ## `[wait]` — quiet helm and trap waiters
183
185
 
@@ -189,7 +191,7 @@ send a continuation.
189
191
 
190
192
  The defaults wait 900, 900, 900, 1800, 3600, 7200, then 14400 seconds.
191
193
  History is stored per session across re-arms. An event or user prompt resets
192
- that session; a dispatch or send resets all this boat's waiters. A prompt the
194
+ that session; routine writes and unchanged reminders do not. A prompt the
193
195
  harness injects when a background task finishes (a `<task-notification>`,
194
196
  which is how a backgrounded `man wait` or `soak --wait` ending quietly comes
195
197
  back) is not a user prompt and does not reset. Already-armed
@@ -326,6 +328,7 @@ outside `~/.lobstah/worktrees`: `lobstah cull`, the retention cull,
326
328
  | Key | Default | Meaning |
327
329
  |---|---|---|
328
330
  | `pollSecs` | `45` | Poll cadence. Outbound only — no webhooks, ever. |
331
+ | `watches` | off for reviews-only; on otherwise | Poll registered watches and their follow-up jobs. Reviews-only setups do not start unrelated watch work; explicit `true` opts in. |
329
332
  | `liveComment` | `true` | Keep one editable, marked status comment per dispatch. Routine edits are capped at once per minute; human-needed and terminal transitions still post a fresh notification comment. Falls back to transition comments if editing is unavailable. |
330
333
  | `pools` | `[]` | Pool names (`["codeclaw"]`). An issue dispatch for repo R runs in the first listed `[pools.<name>]` whose `repo` is R. Review rounds are follow-ups and keep their chain's worktree rule. |
331
334
 
@@ -356,18 +359,20 @@ secret:
356
359
  Two modes. **Single-repo**: name the forge repo explicitly. **Multi-repo**:
357
360
  omit `repo`/`key` and the `[repos.*]` table becomes the source of truth —
358
361
  every repo with `pickup = true` and a GitHub `origin` is polled, its lobstah
359
- key reused as the routing key. Opt-in is per repo, never implied.
362
+ key reused as the routing key. Opt-in is per repo, never implied. With no repo opted in, the identity/token can still serve reviews; no tracker pickup runs.
360
363
 
361
364
  | Key | Default | Meaning |
362
365
  |---|---|---|
366
+ | `publish` | `false` (`true` for auto-review) | The glass draft/publish toggle, including on-demand jobs. Switching it changes auto-draft ↔ auto-review. Each job remembers whether publishing was enabled when it started. |
363
367
  | `identity` | required | The bot login work is assigned to / authored by. |
364
368
  | `repo` | single-repo mode | `owner/name`. Omit for multi-repo mode. |
365
369
  | `key` | single-repo mode | Lobstah repo key for dispatches and rebase chores. |
366
370
  | `startLabel` | `lobstah` | Label + assignee + open = pickup. |
367
371
  | `claimedLabel` | `lobstah:claimed` | Applied on claim. |
372
+ | `issues`, `feedback` | explicit opt-ins | Enable issue or PR-feedback pickup independently. Setting either makes unspecified loops off. Legacy configs with neither retain both loops on, with a doctor/pre-install warning. `prFeedback` remains an alias for `feedback`. |
368
373
 
369
374
  `[pickup.github.overrides.<key>]` — multi-repo per-repo overrides:
370
- `startLabel`, `claimedLabel`, and a nested `merge` table layered over
375
+ `startLabel`, `claimedLabel`, `issues`, `feedback`, and a nested `merge` table layered over
371
376
  `[pickup.github.merge]`.
372
377
 
373
378
  ### `[pickup.github.merge]` — off by default
@@ -385,25 +390,90 @@ See [pickup.md](pickup.md) for the loop semantics these keys drive.
385
390
 
386
391
  ## `[reviews]` — review requests (`lobstah pick`), off by default
387
392
 
388
- When someone asks `[pickup.github].identity` for a review, `lobstah pick`
393
+ Run `lobstah setup reviews` (optional `--identity <login>`) to derive the GitHub login, write a self-contained notify configuration, enable review notifications, and install pick. It refuses to install reviews-only polling while issue/feedback pickup is also enabled.
394
+
395
+ When someone asks `[reviews].identity` for a review, `lobstah pick`
389
396
  files a review item ([pickup.md](pickup.md), "Review requests"). It searches
390
- as that identity, with its token. Any key except `enabled`, `repos` and
391
- `maxPerDay` can be overridden per repo under `[repos.<key>.reviews]`.
397
+ as that identity, with its token source, independently of `[pickup.github]`. Identity defaults to `gh api user`; the token source defaults to `gh auth token`. Existing pickup credentials remain a fallback. Mode, publish, cost bounds, and skip rules can be overridden per repo under `[repos.<key>.reviews]`; those overrides win over `[reviews]`. The glass repo filter scopes the mode switch and Publish toggle to that repo; All repos edits the global default. `lobstah doctor` shows each repo’s effective mode before pick is installed.
392
398
 
393
399
  | Key | Default | Meaning |
394
400
  |---|---|---|
395
401
  | `enabled` | `false` | Opt-in. Off means no search call at all. |
396
402
  | `repos` | `"configured"` | `"configured"`: only PRs in a `[repos.*]` origin. `"any"`: every repo the token can see. |
397
- | `work` | `"trap"` | Who drafts the review: `"off"`, `"trap"` (a free trap of that repo, then headless after `trapWaitSecs`), or `"headless"`. |
398
- | `post` | `"draft"` | `"draft"`: stage the draft as the identity's pending review on the PR, to edit and send from the review tool. `"auto"`: post the draft as a comment-only review once drafted. lobstah never approves or requests changes. |
403
+ | `mode` | `"notify"` | `"notify"`: silent requests in Reviews; `"on-demand"`: only the glass Review action starts a round; `"auto-draft"`: new requests get trap drafts staged pending; `"auto-review"`: new requests get drafts published as REQUEST_CHANGES with blockers, COMMENT otherwise; approve verdicts wait for a click. |
404
+ | `publish` | `false` (`true` for auto-review) | The glass draft/publish toggle, including on-demand jobs. Switching it changes auto-draft ↔ auto-review. Each job remembers whether publishing was enabled when it started. |
405
+ | `identity` | `gh api user` | The reviewer login. |
406
+ | `tokenCommand`, `tokenFile`, `tokenEnv` | `gh auth token` | Token sources, using the same precedence as pickup. |
407
+ | `work` | legacy | `"off"` maps to on-demand, `"trap"`/`"headless"` map to auto-draft; explicit mode wins. The worker choice still applies to automatic jobs. |
408
+ | `post` | legacy | `"draft"` stages pending; `"auto"` maps to auto-review. Explicit mode/publish wins. Automatic publishing uses REQUEST_CHANGES for blockers or COMMENT; APPROVE requires a click in the glass. All publishing refuses stale drafts. |
399
409
  | `harness`, `model`, `effort` | repo, then `[harness]` | The review job's worker. |
400
410
  | `wallClockSecs`, `maxTurns`, `maxBudgetUsd` | `900`, `40`, unset | Cost bounds for one review job. |
401
411
  | `trapWaitSecs` | `600` | With `work = "trap"`: how long a job waits for a free trap. |
402
412
  | `maxPerDay` | `20` | Review jobs started per day. Past it, items file with no job. |
403
413
  | `skipAuthors`, `skipLabels` | `[]` | Requests on PRs by these authors or with these labels file an item but start no job. |
404
414
 
405
- The `review` attention kind is not in the default `attentionKinds`; add it to
406
- let review items walk in `man tend`, the glass, and the pet.
415
+ Requests land silently in the Reviews inbox with a tab count, never on deck or tend. Draft-ready and automatic-published notifications use `[hooks.notify]` and the pet, with a `#review-<encoded key>` link to the row. The hook gets `LOBSTAH_NOTE`, `LOBSTAH_VERB` (`draft-ready`, `needs-you`, `published`) and `LOBSTAH_URL` / `LOBSTAH_GLASS_URL`. Opening marks seen; a row action clears the notification and needs-you marker. Wharf notification delivery is deferred.
416
+
417
+ ## `[permissions]` — the Claude Code auto-mode profile
418
+
419
+ Traps and the helm run Claude Code in auto mode. `lobstah permissions apply`
420
+ merges lobstah's profile into your Claude Code user settings
421
+ (`$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`). That is
422
+ the only file Claude Code reads `autoMode.environment` from, apart from managed
423
+ settings and `--settings`.
424
+
425
+ The base profile adds context for Claude Code's classifier:
426
+ - lobstah's worktrees are your development checkouts;
427
+ - the helm doing what you asked in its chat is not a bypass;
428
+ - merges to trunk, production deploys, secrets, accounts and lobstah's own
429
+ permission controls stay yours.
430
+
431
+ It also allows `Read` and `Edit` on `<lobstah home>/worktrees/**`.
432
+ `[permissions]` adds to it:
433
+
434
+ ```toml
435
+ [permissions]
436
+ environment = ["**Trusted GitHub orgs**: acme and acme-labs are the user's own orgs."]
437
+ allow = ["Bash(wrangler dev *)"]
438
+ deny = ["Bash(vercel env pull *)"]
439
+
440
+ [permissions.codex]
441
+ forbidden = [["vercel", "env", "pull"]]
442
+ allow = [["wrangler", "dev"]]
443
+ ```
444
+
445
+ | Key | Meaning |
446
+ |---|---|
447
+ | `environment` | Prose entries added to `autoMode.environment`, e.g. trusted orgs, cloud accounts, or env-pull policy. |
448
+ | `allow`, `deny` | Claude Code permission rules (`Tool` or `Tool(specifier)`) added to `permissions.allow` / `permissions.deny`. These are resolved before the classifier. |
449
+ | `codex.forbidden`, `codex.prompt`, `codex.allow` | Codex command rules, each an argv prefix (`["gh", "pr", "merge"]`). A Codex `allow` runs the command outside Codex's sandbox, so these are never translated from the Claude rules. |
450
+
451
+ **Codex.** Codex has its own home: `$CODEX_HOME`, else `~/.codex`. When it exists, the same verbs also change two things there:
452
+ - **The auto reviewer's added policy.** This is `[auto_review].extra_policy` in `config.toml`, which Codex's reviewer reads alongside its own policy. lobstah writes a block between `<!-- lobstah:begin … -->` and `<!-- lobstah:end -->` holding the same three facts and `environment`.
453
+ - Text outside the markers is yours and stays.
454
+ - lobstah edits only the key's own lines, keeping comments, key order and the string's quoting. It parses the file before and after; anything else changing refuses the write.
455
+ - **`rules/lobstah.rules`.** This file is wholly lobstah's. It holds the base rules plus `[permissions.codex]`:
456
+ - forbidden: `lobstah grant`, `lobstah trap grant|bypass` and `lobstah permissions apply|remove`;
457
+ - prompt: `gh pr merge`.
458
+ - `codex execpolicy check` loads every rule before the file is put in place.
459
+
460
+ `remove` deletes `rules/lobstah.rules` and lobstah's block. Neither verb sets `approvals_reviewer` or `approval_policy`: `man throw` already starts Codex traps with `--approve-for-me`.
461
+
462
+ **What each form does:**
463
+ - Bare `lobstah permissions` shows the diff and writes nothing.
464
+ - `apply` merges, keeping every existing key and rule. A new
465
+ `autoMode.environment` starts with `"$defaults"`, so Claude Code's built-in
466
+ context stays.
467
+ - `remove` takes lobstah's entries out.
468
+ - Both `apply` and `remove` back up the previous file to
469
+ `<lobstah home>/backups/`, ask before writing (`--yes` skips the question),
470
+ and refuse inside an agent's shell.
471
+
472
+ lobstah records the entries it added in `<lobstah home>/claude-permissions.json`,
473
+ so a re-run after editing `[permissions]` removes only lobstah's own stale
474
+ entries. `lobstah doctor` reports whether the profile is applied and current.
475
+ There is one Claude Code user settings file, so there is one `[permissions]`
476
+ table rather than one per grounds.
407
477
 
408
478
  ## Environment
409
479
 
@@ -28,6 +28,47 @@ the CLI: plugin 0.5.10 goes with `lobstah` 0.5.10. After every
28
28
  `lobstah doctor` shows a `plugin codex` row, and the session-start brief
29
29
  says when the plugin is behind.
30
30
 
31
+ ## Thrown trap startup
32
+
33
+ Codex 0.160.1 blocks at **Hooks need review** before the first model turn
34
+ when any hook definition is new or changed. A longer throw timeout cannot
35
+ clear that picker. `man throw` supplies invocation-scoped `hooks.state`
36
+ hashes for the installed plugin's six exact `lobstah hook <event>` commands.
37
+ Thrown sessions also set `check_for_update_on_startup=false` for that
38
+ invocation, so an interactive update picker cannot hold the launch.
39
+ The launcher rejects a plugin definition containing another command; it
40
+ never uses `--dangerously-bypass-hook-trust`, edits saved trust, enables a
41
+ disabled hook, or approves repo/user/other-plugin hooks. Those still require
42
+ their normal review. Manually launched Codex sessions still use `/hooks`.
43
+
44
+ In 0.160.1, linked worktrees inherit project trust and hook declarations
45
+ from their primary checkout, including the primary hook source path. They
46
+ do not need blanket trust for `~/.codex/worktrees` or `~/.lobstah/worktrees`.
47
+ An untrusted primary project still needs its normal folder trust decision.
48
+ Auto-mode launches add only lobstah's home, ume's home (`UME_HOME`, otherwise
49
+ `~/.ume`), and the repository's git common directory as extra writable roots.
50
+ This lets ume write its push ledger without granting the rest of the home
51
+ directory.
52
+ `doctor` checks the additional `UserPromptSubmit` and `PermissionRequest`
53
+ hooks when declared; either can block startup even when the four lifecycle
54
+ hooks are already trusted. Its trust status reads saved configuration; the
55
+ throw's invocation overrides do not change that saved status.
56
+
57
+ Verified against the [0.160.1 startup review](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/tui/src/startup_hooks_review.rs),
58
+ [worktree config loader](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/config/src/loader/mod.rs),
59
+ and [hook-state merge](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/hooks/src/config_rules.rs).
60
+
61
+ ### Resume folder selection
62
+
63
+ Codex 0.160.1 shows **Working directory · resume** when the saved session cwd
64
+ and current launch cwd differ. Starting the process with a shell `cd` does
65
+ not answer that picker. Each generated Codex command now also passes
66
+ `--cd <launch-directory>`; returning traps always choose their own worktree,
67
+ even when their session history began in the primary checkout. This selects
68
+ the current directory for that invocation without saving a global preference.
69
+ New traps still start in the primary checkout, where their first `soak`
70
+ creates and enters the worktree.
71
+
31
72
  ## What the plugin adds
32
73
 
33
74
  | Piece | What it does |
package/docs/man.md CHANGED
@@ -943,6 +943,17 @@ gates the digest above.
943
943
  The lobstah man skill prints the glass URL. `[glass].port` sets the port;
944
944
  `LOBSTAH_GLASS_PORT` takes precedence.
945
945
 
946
+ **Compare chat detail at runtime.** `lobstah man chat brief` asks the helm to
947
+ point at a card in one line when it already carries the detail, keep wakes
948
+ with nothing new quiet, and answer direct questions directly. `lobstah man
949
+ chat full` restores normal output. Use `--grounds <name>` when needed. A
950
+ person at a terminal or that grounds' helm may toggle it; glass Settings
951
+ has the same switch per helm. `man tend` and the glass helm chip show the
952
+ current mode. The seat stores the override through re-sign and takeover;
953
+ relieving removes it. `[helm].chat` supplies the default (`"full"`). The
954
+ next prompt, `man wait`, or Stop-hook wake carries the change, including
955
+ a one-time full-mode notice to retire an earlier brief instruction.
956
+
946
957
  **One helm per grounds, enforced.** A **grounds** is a named territory: the
947
958
  subset of configured repos one orchestrator oversees (`[grounds.*]`; with
948
959
  none configured, one implicit `home` grounds covers every repo). A repo
@@ -1185,7 +1196,8 @@ lobstah stow --wt amber-gull # withdraw a reservation no session has
1185
1196
 
1186
1197
  `man throw --new` (the helm's) picks a two-word name and a `wt:` id for each
1187
1198
  fresh trap before any session exists and writes a **starting** reservation
1188
- (`soaking/<id>.starting`) with a deadline (`--timeout`, default 180 seconds).
1199
+ (`soaking/<id>.starting`) with a deadline (`--timeout`; Codex defaults to
1200
+ `[soak].codexStartSecs`, 600 seconds, and other harnesses to 180 seconds).
1189
1201
  `dispatch --for <name>` works on it at once: the work waits, as it does for
1190
1202
  any addressed trap. `man tend` and the glass show the trap as `starting`.
1191
1203
 
@@ -1196,7 +1208,7 @@ command in a new tab in the repo's primary checkout:
1196
1208
 
1197
1209
  ```bash
1198
1210
  cd <repo> && CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 claude '/lobstah:trap soak --ticket <ticket>'
1199
- cd <repo> && codex '$lobstah:trap soak --ticket <ticket>'
1211
+ cd <repo> && codex -c 'tui.terminal_title=[]' '$lobstah:trap soak --ticket <ticket>'
1200
1212
  ```
1201
1213
 
1202
1214
  The session's soak redeems the ticket, from `--ticket` or from the
@@ -1207,9 +1219,11 @@ reservation. The ticket then redeems nothing. A spent ticket left in
1207
1219
  the session that redeemed it. A session that already mans a trap cannot
1208
1220
  redeem a ticket.
1209
1221
 
1210
- A throw that sees no sign-on by its deadline withdraws the reservation and
1211
- posts `trap-start-failed`. A reservation found unredeemed at its deadline by
1212
- the daemon (one throw did not wait for) **fails** the same way: the glass
1222
+ A Codex throw that sees no sign-on by its deadline keeps its ticket valid
1223
+ and fences a second launch. Check its terminal or withdraw it before retrying.
1224
+ Other harnesses withdraw the reservation and post `trap-start-failed`. The
1225
+ daemon marks an unredeemed reservation past its deadline as **failed**
1226
+ while retaining its ticket for late sign-on: the glass
1213
1227
  shows the trap as `start failed` with the reason, and work addressed to it
1214
1228
  stays queued. `lobstah stow --wt <name>` withdraws a reservation; its
1215
1229
  addressed work is then orphaned bait and the helm gets a `bait-orphaned`
@@ -1325,9 +1339,11 @@ launched twice. Otherwise:
1325
1339
  prompt redeems the ticket, so the session signs on as the same trap.
1326
1340
  Every start names its permission mode (see **Permission mode** below).
1327
1341
  4. It returns when the trap has signed on and parked, and prints whether it
1328
- resumed or started cold, and why. Past `--timeout` (default 180 seconds)
1329
- it withdraws the reservation, so a late session cannot take the trap,
1330
- posts `trap-start-failed`, and leaves the roster unchanged.
1342
+ resumed or started cold, and why. Codex uses `[soak].codexStartSecs`
1343
+ (default 600 seconds); other harnesses use 180 seconds. `--timeout`
1344
+ overrides either. A Codex timeout keeps its ticket and reservation for
1345
+ late sign-on; other harnesses withdraw the reservation and post
1346
+ `trap-start-failed`. Late first park announces the trap as available.
1331
1347
 
1332
1348
  **Permission mode.** A thrown trap starts in auto mode, cold or resumed,
1333
1349
  fresh or rostered:
@@ -1376,7 +1392,8 @@ so a live Codex trap shows the mode its throw started it in.
1376
1392
  (`--grounds`, else the caller's helm grounds, else every repo); `--repo`
1377
1393
  narrows to one repo; `--new --count N` starts N fresh ones. Every launch runs
1378
1394
  at once, with no limit, and the batch waits for all of them. It prints one
1379
- row per trap: `resumed`, `cold`, or `new` (with why), `skipped` (live,
1395
+ row per trap: `resumed`, `cold`, or `new` (with why), `starting` (a Codex
1396
+ timeout still awaiting sign-on or first park), `skipped` (live,
1380
1397
  starting, or unresolved, with why), or `failed` (with why). One trap failing
1381
1398
  does not stop the others, and the command exits 1 when any failed.
1382
1399
 
@@ -1385,8 +1402,9 @@ trap is listening. Its reservation (`trap-starting`), sign-on
1385
1402
  (`trap-signed-on`), and sign-off (`trap-stowed`) are quiet: tend, the
1386
1403
  digest's `traps` table, and the glass show them. A ghost sweep of an idle
1387
1404
  trap is quiet the same way; a ghost sweep of a trap that held a catch wakes.
1388
- A batch posts no `trap-available` per trap: when every throw has settled it
1389
- posts one `trap-batch` notice with the counts and the names that failed. A
1405
+ Timely arrivals in a batch post no individual `trap-available`: when every
1406
+ throw has settled it posts one `trap-batch` notice with the counts and the
1407
+ names that failed. A late first park posts its own `trap-available`. A
1390
1408
  trap that failed to start (`trap-start-failed`) and work addressed to a trap
1391
1409
  that is gone (`bait-orphaned`) still wake.
1392
1410
 
package/docs/pickup.md CHANGED
@@ -270,15 +270,15 @@ When the search stops returning a PR (the request was withdrawn, the
270
270
  person reviewed it on GitHub, or the PR closed), its open round is `withdrawn`. A
271
271
  truncated search (more than 50 results) withdraws nothing.
272
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
273
+ **Drafting.** `[reviews].mode = "notify"` starts no jobs. `"on-demand"` enables the glass Review action for requested, stale, or failed rounds and starts nothing automatically. `"auto-draft"` and `"auto-review"` start a review job for each requested round in
274
+ a configured repo: a chore-lane dispatch with the
275
275
  `prReview` brief, `readOnly` (the runner pushes nothing, opens no PR, and
276
276
  checkpoints nothing), and the `[reviews]` cost bounds. With `work = "trap"`
277
277
  the job waits `trapWaitSecs` for a free trap of the repo, then pick hands it
278
278
  to the daemon. The job reads the PR with `gh`, makes any checkout it needs
279
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
280
+ `rounds/<round id>/checkout`, and writes `review.md` (the summary),
281
+ `comments.json` (inline comments: `path`, `line`, `side`, `body`), and `verdict.json` (`verdict`: `approve`, `comment`, or `request_changes`; `blocking`: findings with `path`, positive `line`, and `body`) into the
282
282
  round's directory, `rounds/<round id>/`. Whenever the round's job ends
283
283
  (drafted, stale, failed, or withdrawn and its job cancelled, a re-request
284
284
  included), pick removes that checkout: `git worktree remove --force`, then
@@ -293,7 +293,7 @@ outside the configured repos, or `maxPerDay` jobs already started today
293
293
  (UTC) leave the round `requested` with the reason. `lobstah reviews redraft
294
294
  <key>` drafts a stale or failed round again at the current head.
295
295
 
296
- **Staging and posting.** With `[reviews].post = "draft"` (the default), a
296
+ **Staging and posting.** With `mode = "auto-draft"` or `publish = false` for an on-demand job, a
297
297
  fresh draft is staged on the PR as the identity's **pending review**:
298
298
  `POST /repos/{o}/{r}/pulls/{n}/reviews` with no event, `commit_id` set to the
299
299
  head the draft reviewed, the inline comments, and a body ending with
@@ -304,12 +304,8 @@ sends it, with whatever event they choose. When the request then disappears from
304
304
  search, pick reads that review once: submitted marks the round `posted` (by
305
305
  `review tool`), deleted dismisses it, still pending withdraws it.
306
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
307
+ With `mode = "auto-review"` (also legacy `post = "auto"`), pick publishes fresh drafts as REQUEST_CHANGES when there are blocking findings, otherwise COMMENT. An approve verdict is staged pending with a needs-you marker and always waits for the person’s Approve click; approval is never automatic. The glass Publish toggle selects draft or publish, including for on-demand jobs; the row action reads Review (draft) or Review (publish). The repo filter scopes both settings to `[repos.<key>.reviews]`, otherwise they change the global `[reviews]` default. Jobs started with publishing off stay draft-only even if the toggle changes later. Manual drafting respects `maxPerDay`, including retries of the same round. `lobstah reviews post <key>` explicitly sends a staged review as a
308
+ comment review. The glass shows Approve, Request changes, or Publish comment according to the verdict; Approve posts APPROVE with the summary as the identity, only on the person’s explicit click. The glass shows requester names/avatars cached from the same authenticated search; workflow requests show the PR author with an automatic badge. Cards and rows open the configured review tool; drafted rounds link to their pending review. Skip (formerly Dismiss) means “Handle it yourself; removes lobstah’s draft”: it deletes any staged pending review without declining the request on GitHub. Redraft starts a stale round again. Every row action acknowledges and clears its notification and needs-you marker; opening a row only marks it seen and dims it. A stale draft is never staged or posted, including by hand. Publishing checks the live PR head immediately before submission; a changed or closed PR requires a new draft. Each round is staged at most once and posted at
313
309
  most once: `staged.json` and `posted.json` in the round's directory are
314
310
  created with `wx` before the call and removed if it fails, and a review on
315
311
  the PR that already carries the round's marker is adopted (pending) or
@@ -330,9 +326,7 @@ pending draft with its own token and marks the request done or refused. The
330
326
  wharf never calls GitHub.
331
327
 
332
328
  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.
329
+ `posted`, `dismissed`, `withdrawn`. The Reviews tab is the inbox; it shows a count, and no review cards appear on deck or tend. Requests are silent. Only a completed draft (“Draft ready: #7 · request changes · 2 blocking”), an approve verdict needing the person, or an automatically published review notifies through `[hooks.notify]` and the pet. Notifications deep-link to the Reviews row; wharf notification delivery comes later. Generic review-job done notifications are suppressed to avoid duplicates. `lobstah reviews` lists open items; `--all` adds the rest.
336
330
 
337
331
  ## Merge loop
338
332
 
@@ -305,7 +305,8 @@ prints one `hooks claude` and one `hooks codex` row for each harness whose
305
305
  lobstah plugin is installed (`skip` otherwise). The row starts with the
306
306
  readiness of each role: the helm needs `Stop` and `SessionStart`; a trap
307
307
  needs all four (`helm ready, trap not ready (needs PostToolUse)`). Then, for
308
- each hook (`Stop`, `SessionStart`, `PostToolUse`, `SessionEnd`), it says:
308
+ each lifecycle hook (`Stop`, `SessionStart`, `PostToolUse`, `SessionEnd`),
309
+ plus Codex's `UserPromptSubmit` and `PermissionRequest` when declared, it says:
309
310
 
310
311
  - **installed**: the plugin's `hooks/hooks.json` declares it (`missing`
311
312
  otherwise), and whether the harness has it turned off (`installed but
@@ -482,7 +483,7 @@ worktree is refused (the session lock); a stale one is adopted.
482
483
  | beat | `lobstah soak beat` (`lobstah hook post-tool-use`), run by the plugin's post-tool hook after every tool call. It resolves the trap from the working directory, else from the session id (files only: no git, no network), refreshes the trap's beat (`soaking/<trap>.beat`, separate from the registration), and writes the claimed catch's [activity](#activity). Throttled to one per 30 seconds per trap. Inert in a session that is not soaking, or with `[soak].beat = false`. Always exits 0; errors go to `logs/beat.log`. |
483
484
  | ghost trap | A registration whose heartbeat **and** beat lapsed past `[soak].ttlSecs` **after having parked at least once**. The sweep removes the registration, requeues only unfinished catches, finalizes done/failed in `done/`, and posts a `trap-ghosted` notice: quiet (digest and glass only) for an idle trap, a wake for one that held a catch. It removes a soak-created checkout only when clean and pushed to its upstream; dirty, unpushed, no-upstream, or unreadable checkouts stay, protected from later culls too. The notice includes path, branch, modified-file and unpushed-commit counts, or `unknown` when unavailable. A kept anchor preserves the address on re-soaking. A fresh report or beat keeps a working session out of the sweep; a fresh beat also holds the session lock. A catch whose last report is `paused` keeps its trap until the pause expires ([Waiting on](#waiting-on)). A daemon tick gap longer than the soak TTL starts one full TTL of resume grace before any ghost sweep. |
484
485
  | 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. |
485
- | reserved trap | A trap `man throw` reserved before its session signs on: a name, a `wt:` id, and a one-time ticket, shown as `starting`. `man throw --new` reserves a fresh id and name; `man throw <name>` reserves an existing roster trap under its own id and name, in its own worktree (the reservation records the worktree). A trap has at most one reservation, so a second throw refuses. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. A throw that sees no sign-on by its timeout withdraws the reservation; one found unredeemed past its deadline fails with a `trap-start-failed` notice and its work stays queued. `stow --wt <name>` withdraws it. A reservation made by a batch throw records the batch, and so does the registration its sign-on makes. |
486
+ | reserved trap | A trap `man throw` reserved before its session signs on: a name, a `wt:` id, and a one-time ticket, shown as `starting`. `man throw --new` reserves a fresh id and name; `man throw <name>` reserves an existing roster trap under its own id and name, in its own worktree (the reservation records the worktree). A trap has at most one reservation, so a second throw refuses. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. A Codex throw timeout retains its ticket and reservation for late sign-on; other harnesses withdraw it; one found unredeemed past its deadline fails with a `trap-start-failed` notice and its work stays queued. `stow --wt <name>` withdraws it. A reservation made by a batch throw records the batch, and so does the registration its sign-on makes. |
486
487
  | trap roster | One durable record per trap that ever signed on (`~/.lobstah/roster/<trapId>.json`): canonical name, repo and its git common directory, worktree, soak branch, last branch and HEAD, harness, session, the registration's model and config, window and link (navigation hints only), state (`live`, `stowed`, `ghosted`), when and why it left, its last catch, and a saved profile (harness, model, config, terminal) set with `man roster set`. Sign-on writes it; stow and the ghost sweep update it before the registration goes. Stow, the end of the sign-off grace, a ghost sweep, and `cull` never remove it. The roster's name is the trap's name: a trap that signs on again keeps it. A roster record never makes a trap live or claimable. `man roster` lists it; `man throw` reads it; `man roster forget` removes it. |
487
488
  | protected ref | `refs/lobstah/traps/<trapId>` in the trap's repository: the trap's last HEAD, written at sign-on and before stow, a ghost sweep, or `cull` removes the checkout. It is not a branch, so worktree removal and branch cleanup leave it and its commit in place. A missing checkout is recreated from it. A trap checkout whose revision cannot be written there is not removed by a ghost sweep or cull. |
488
489
  | trap request | A trap the human asked for from the glass's **+ New trap** button: a `trap-request` request in `requests/<id>.json` with a repo and a harness. It wakes the helm as a `trap-request` event; the helm starts it with `man throw --new --request <id>`, which takes the request's repo and harness and closes it. |
@@ -515,9 +516,9 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
515
516
  | `helm` | Sign a session on as the orchestrator for one grounds. Prints the charter and enables the Stop hook without a marker file. Re-running from the same session is an idempotent re-sign. |
516
517
  | watcher registration | `~/.lobstah/watchers/<session-id>.json` stores a `man wait` or `soak --wait` process's PID and heartbeat. The waiter refreshes it while running and removes it on exit; a heartbeat older than five seconds is stale, and a second waiter for the same session refuses. |
517
518
  | `man throw --dry-run` | What a throw would do for each selected trap (`--plan` is the same), read from the [trap roster](#soaking-contract): `resume` the saved session, `cold` (a new session under the same name, id, and checkout; the row says why: no saved history, an app session, a profile that changes harness), `skip` (live or starting), or `unresolved` (repo no longer configured or now another repository, record incomplete, checkout gone with no protected ref, or the path anchors another trap). Names select traps; `--all` selects every eligible trap in the grounds; `--repo` narrows. Each row shows harness, model, config, terminal (and where each came from), checkout (`kept` or `recreate`), revision, and held messages. Read-only: it launches and writes nothing. |
518
- | `man throw --all \| --repo <key> \| --new [--count N]` | A batch throw (the helm's): every eligible trap in the grounds, one repo's, or N fresh traps from the harness defaults (`--harness`, `--request <id>` for a glass trap request). Every launch runs at once, with no limit. One row per trap: `resumed`, `cold`, `new`, `skipped`, or `failed`, each with why; one failure does not stop the others, and the command exits 1 when any failed. The batch posts one `trap-batch` notice when it settles and no per-trap `trap-available`. `--dry-run` (or `--plan`) shows the plan and launches nothing. |
519
+ | `man throw --all \| --repo <key> \| --new [--count N]` | A batch throw (the helm's): every eligible trap in the grounds, one repo's, or N fresh traps from the harness defaults (`--harness`, `--request <id>` for a glass trap request). Every launch runs at once, with no limit. One row per trap: `resumed`, `cold`, `new`, `starting` (Codex timed out but may still arrive), `skipped`, or `failed`, each with why; one failure does not stop the others, and the command exits 1 when any failed. The batch posts one `trap-batch` notice when it settles, suppressing per-trap `trap-available` for timely arrivals. A late first park announces availability separately. `--dry-run` (or `--plan`) shows the plan and launches nothing. |
519
520
  | `man roster forget <name>` | Remove a stowed trap for good (the helm's): its worktree (one soak did not create stays, minus its anchor), its protected ref, its roster record, its held messages (bounced), and its name. Refuses a live or starting trap, and refuses, naming the work, when its checkout has unsaved files or its commits are on no remote branch and not merged to trunk; `--force` forgets anyway, keeping a branch that still holds such commits. |
520
- | `man throw <name>` | Bring one roster trap back and wait until it listens. The helm's. It follows the plan for that trap: a `skip` (live or starting) refuses, which fences a double launch; an `unresolved` refuses with its reason. Otherwise it reserves the trap under its own id and name, recreates a missing checkout from the protected ref on its recorded branch (an existing branch only when it still contains that revision; a kept checkout, dirty or not, is used as is), and opens the start command in the profile's terminal (Terminal.app or iTerm2, macOS): `resume` reopens the saved session from the directory its history is keyed by, `cold` starts a new one in the worktree; the first prompt redeems the ticket. It returns when the trap has signed on under its id and parked, printing which start happened and why. Past `--timeout` (default 180 s) it withdraws the reservation, posts `trap-start-failed`, and leaves the roster unchanged. Batches: see `man throw --all`. |
521
+ | `man throw <name>` | Bring one roster trap back and wait until it listens. The helm's. It follows the plan for that trap: a `skip` (live or starting) refuses, which fences a double launch; an `unresolved` refuses with its reason. Otherwise it reserves the trap under its own id and name, recreates a missing checkout from the protected ref on its recorded branch (an existing branch only when it still contains that revision; a kept checkout, dirty or not, is used as is), and opens the start command in the profile's terminal (Terminal.app or iTerm2, macOS): `resume` reopens the saved session from the directory its history is keyed by, `cold` starts a new one in the worktree; the first prompt redeems the ticket. It returns when the trap has signed on under its id and parked, printing which start happened and why. Codex defaults to `[soak].codexStartSecs` (600 s), others to 180 s; `--timeout` overrides either. A Codex timeout retains its ticket and duplicate-launch fence for late sign-on. Other harnesses withdraw the reservation and post `trap-start-failed`. Batches: see `man throw --all`. |
521
522
  | `man roster` | List the trap roster. `man roster set <trap> --harness\|--model\|--terminal <value>\|--config <key>=<value>` saves how a throw starts the trap; `default` (or `key=`) clears a field. |
522
523
  | `man haul --park` | Make the Stop hook wait for attention while work is in flight. `[helm].park = "block"` selects the same mode. In arm mode, the hook allows a stop with a live watcher or blocks with the arm command. |
523
524
  | `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`. |
@@ -597,3 +598,8 @@ registry that decides what parses).
597
598
  | `1` | Error: the command was well-formed but could not do its job. |
598
599
  | `2` | Usage mistake: unknown command, flag, or subverb. The error names the offender and prints the command's usage card. Flags in a free-text tail (a `send` message, a `report` note) are never validated — prose may contain anything. |
599
600
  | `3` | `man wait --timeout` elapsed with nothing to report. Its own code so `while lobstah man wait` loops still terminate on timeout while `2` stays unambiguous. |
601
+
602
+
603
+ ### Session grants
604
+
605
+ `lobstah grant request --session <id>` (or `--trap <name>`, `--grounds <name>`) `--tools 'mcp__browser__*' [--hosts a,b] [--for 15m] --reason "why"` asks in glass; it never grants. Chris chooses Allow for the requested duration, Allow for 1h, or Deny. A real terminal can use `lobstah grant --session <id> --tools <name|glob>` with the same options and confirmation. Windows start at approval, default to 15m, and cannot exceed 4h. Bash requires `--command '<prefix>'` and keeps the existing no-joiner/no-redirect rules. URL hosts are pinned exactly when present; URL-less clicks/screenshots ride the session window. Grant/config/settings edits and self-grant commands are excluded. The existing permission card also offers a 15-minute tool-family window for its asking session. `lobstah grants` and the glass show expiry, use count and the latest 20 tool/time/host records (no typed text or URL paths/queries); Revoke takes effect immediately. Hooks request an allow; harness restrictions still apply.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lobstah",
3
- "version": "0.7.10",
3
+ "version": "0.8.0",
4
4
  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
5
5
  "license": "MIT",
6
6
  "author": "aequitas labs LLC",