lobstah 0.8.4 → 0.8.5

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.
@@ -16,6 +16,46 @@ keys of that section.
16
16
  | `remindSecs` | `900` | An unanswered `needs-decision`/`blocked` re-fires to `man wait`/`man haul` on this interval until answered. `0` = report once only. |
17
17
  | `readySettleSecs` | `600` | `pr:ready` stands after continuously meeting the ready conditions on the same head for this many seconds. Any not-ready observation or new head resets the timer. Each attention read re-evaluates expiry from the persisted start, even without a new forge event. `0` restores immediate ready attention; other `pr:*` kinds are unchanged. |
18
18
 
19
+ ## `[traps.<name>]` — repo-less workers
20
+
21
+ A named profile serves exactly one grounds, without git, repo setup or a
22
+ worktree. Profiles are separate per grounds. `soak --trap <name> --session
23
+ <id>` signs on the current session; `dispatch --for trap:<name>` queues
24
+ sticky work for that profile. Configured catches accept reports and files,
25
+ not PR evidence. Tool approval stays with the harness Auto reviewer.
26
+
27
+ ```toml
28
+ [traps.desk]
29
+ harness = "claude"
30
+ surface = "claude-desktop"
31
+ grounds = "fleet" # implicit grounds: fleet or its display name home
32
+ maxInstances = 1 # live, stowed, ghosted and pending instances
33
+ # cwd = "~/Desktop/desk" # optional existing plain folder, no git required
34
+
35
+ [traps.ops]
36
+ harness = "codex"
37
+ surface = "terminal"
38
+ terminal = "tmux" # optional: terminal, iterm or tmux
39
+ maxInstances = 1
40
+ grounds = "fleet"
41
+ ```
42
+
43
+ `harness`, `surface` and `grounds` are required. `claude-desktop` requires
44
+ Claude; `terminal` supports Claude and Codex. `maxInstances` defaults to 1
45
+ and must be a positive integer. `terminal` is valid only for a terminal
46
+ surface. `cwd` must be an existing absolute directory (`~/` expands);
47
+ omitting it creates a private folder under
48
+ `$LOBSTAH_HOME/trap-workspaces/<grounds>/<profile>/<instance>`. A folder
49
+ inside a repo still remains a plain folder for this profile. Unknown keys,
50
+ grounds, harnesses and surfaces are config errors naming the key.
51
+
52
+ Stow and ghost keep the instance and folder. Returning reuses a slot;
53
+ `man roster forget` frees an idle instance without deleting its folder,
54
+ app session, configuration or catch history. Queued and active work prevent
55
+ forgetting. Removing configuration leaves existing catches and identities
56
+ intact and prevents new claims. Roster, tend and the glass show each
57
+ profile's grounds, surface, capacity and state.
58
+
19
59
  ## `[repos.<key>]` — workspace definitions
20
60
 
21
61
  The descriptor's `repo` field resolves here; the key is what dispatchers name.
@@ -181,25 +221,83 @@ send a continuation.
181
221
  | `ttlSecs` | `1800` | Heartbeat age past which a registration is a ghost trap: the sweep removes it and requeues an unfinished catch, finalizes done/failed in `done/`, or finalizes a cancelled catch as failed. A fresh `lobstah report` or beat counts as liveness. If the daemon's own tick gap exceeds this TTL, it grants a full TTL after resume before sweeping any traps. |
182
222
  | `beat` | `true` | The post-tool hook (`lobstah soak beat`) refreshes a soaking session's liveness and writes its catch's activity, at most once per 30 seconds per trap. With `false` the hook does nothing, and a trap's liveness comes from its reports and its park only. |
183
223
  | `signOffGraceSecs` | `600` | After a trap signs off, its address is held this long: messages to it wait for a re-soak of the same worktree instead of bouncing, `send` to it queues with a warning, and work addressed to it raises no `bait-orphaned` notice. After the grace the daemon bounces the held messages. `0` bounces at sign-off. |
224
+ | `codexRemoteControl` | `false` | Start every Codex trap on Codex's shared app-server, so a paired phone can drive it, as `man throw --remote-control` does for one. It covers scheduled and batch throws, and saves hook and folder trust in `~/.codex/config.toml`. See [Codex](harness/codex.md). |
184
225
  | `terminal` | unset | The terminal app a thrown trap opens in: `terminal` (Terminal.app) or `iterm` (iTerm2). A trap's roster profile (`man roster set <trap> --terminal`) overrides it. Unset, `man throw` uses the app the trap last signed on from, else Terminal.app. `man throw` opens the trap's session there through AppleScript (macOS only); the app needs Automation permission for the terminal that runs `man throw`. |
185
226
  | `pausedTtlSecs` | `86400` (24 hours) | A trap whose catch last reported `paused` is kept out of the ghost sweep this long after the report. `report paused --until <iso|duration>` sets the expiry instead. After it, the sweep removes the trap as usual, and the notice says the pause expired. |
186
227
 
228
+ ## `[heavy]` — the machine's line for heavy commands (`lobstah heavy`)
229
+
230
+ `lobstah heavy -- <command>` waits for a slot, runs the command, and frees the
231
+ slot. One line covers every repo on the machine. Each process manages its own
232
+ place in `~/.lobstah/heavy/`, so the line doesn't depend on the daemon. With no
233
+ command, `lobstah heavy` shows the line.
234
+
235
+ | Key | Default | Meaning |
236
+ |---|---|---|
237
+ | `slots` | `"auto"` | Commands that run at once. `auto` is 1 below 14 cores, otherwise 2. Read on every check, so a change needs no restart. |
238
+ | `workers` | `"auto"` | Test workers per run, set as `VITEST_MAX_WORKERS`, `VITEST_MAX_FORKS` and `VITEST_MAX_THREADS` unless already set. `auto` is a third of the cores, at least 2. |
239
+ | `holdLimitMins` | `45` | Active minutes a command keeps its slot. Past this it loses the slot and keeps running. Sleep doesn't count. |
240
+ | `lineNoticeMins` | `30` | How long the oldest waiter waits before a quiet notice. |
241
+
242
+ Pushes queue with no change to how they're run. Soak, worktree creation and
243
+ pool warm-up set a linked worktree's `core.hooksPath` to a shim in
244
+ `~/.lobstah/heavy/hooks`, which runs the repo's real hook unchanged. Its
245
+ `pre-push` takes a slot first, but only in a lobstah worktree, in an agent
246
+ session, and when the repo has a real hook. A person's push never waits. This
247
+ isn't applied on Windows.
248
+
249
+ `[heavy.repos.<key>]` names pushes the repo's hook handles cheaply, so they take
250
+ no slot. The hook still runs in full, so a wrong setting costs only some load.
251
+
252
+ ```toml
253
+ [heavy.repos.homebase]
254
+ lightRefs = ["refs/heads/pr-evidence"] # remote refs
255
+ lightPaths = ["apps/design/"] # every changed file is under one of these
256
+ reminders = ["pnpm test:e2e"] # this repo's own heavy commands
257
+ ```
258
+
259
+ A trap or worker on a dispatch that runs a known heavy command outside the line
260
+ gets one line of context, once per dispatch for each command. It approves
261
+ nothing and blocks nothing, and that run isn't queued.
262
+
263
+ `lobstah heavy`, `man tend` and the glass show the line, and the load average
264
+ beside it. Waiting doesn't count as needing attention. A long line is one quiet
265
+ notice, `heavy-line-long`, once until the line empties. A command over its limit
266
+ is one `heavy-over-limit` notice per ticket, which wakes the helm because
267
+ something may be stuck. Joining, starting and finishing post nothing.
268
+
269
+ The line never kills or fails a command. If the line itself fails, the command
270
+ runs without a slot and prints one line. A waiter removed from the line because
271
+ its trap or dispatch stopped exits 75 having run nothing. `--bg` returns at once
272
+ and posts the exit code, log path and last lines to the dispatch's inbox.
273
+
187
274
  ## `[helm]` — the orchestrator seat (`lobstah man helm`)
188
275
 
189
276
  | Key | Default | Meaning |
190
277
  |---|---|---|
191
278
  | `ttlSecs` | `1800` | Heartbeat age past which a helm registration is stale: the next `man helm` claims it without `--take`. The park and `man brief` heartbeat it. |
192
279
  | `reportSecs` | `900` | Minimum seconds between park-delivered digests for a helm session. The digest is also change-gated — quiet grounds deliver nothing regardless of cadence. |
193
- | `timezone` | system timezone | IANA timezone (e.g. `America/New_York`) for daily goals and for when a done todo leaves `man tend` and the glass. A day starts at 04:00 local. |
280
+ | `timezone` | system timezone | IANA timezone (e.g. `America/New_York`) for daily goals, for reading todo times, and for when a done todo leaves `man tend` and the glass. A day starts at 04:00 local. |
194
281
  | `queuedNoticeSecs` | `180` | Queued age before a dispatch-progress notice wakes the helm with its queue reason and remedy. `0` disables. Reminders back off at 15, 45, 105… minutes after the threshold; claim clears the condition. |
195
282
  | `stalledNoticeSecs` | `1200` | Silence since both a claimed dispatch's last activity and note before dispatch-progress attention. The same reminder backoff applies; activity or a note clears it. Paused, needs-decision and blocked workers use their existing paths. `0` disables. |
196
283
  | `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. |
197
284
  | `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. |
198
- | `todoStaleDays` | `3` | Open helm todos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
199
- | `briefTodoLimit` | `5` | Maximum open todos in the session-start brief, oldest first; the remainder is counted. `0` shows only the count. |
285
+ | `todoStaleDays` | `3` | Open helm todos with no due time and older than this many days are stale and require a todo/goals pass. `0` disables staleness. |
286
+ | `passIntervalSecs` | `7200` | Maximum seconds between delivered todo/goals passes. `0` disables only this interval; a new goals day or newly stale todo still makes a pass due. |
287
+ | `briefTodoLimit` | `5` | Maximum unscheduled open todos in the session-start brief, oldest first; the remainder is counted. `0` shows only their count. Overdue todos always show and use up the limit. Future and snoozed todos always stay listed with their due times, outside the limit. |
200
288
  | `goalsNudgeSecs` | `7200` | Minimum seconds between capped goals lines on `man wait` timeout digests, per helm session; resets at the goals-day boundary. `0` disables. |
201
289
  | `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. |
202
290
 
291
+ A todo/goals pass is due on the first helm sign-on or wait of a goals day
292
+ (04:00 local), after the interval, or when a todo becomes stale. When due,
293
+ sign-on, the Stop hook, and quiet `man wait` timeouts print the full open todo
294
+ list (stale first) and today's goals with their done states, using the same
295
+ renderers as `lobstah todo ls` and `lobstah goals`. Showing those details records
296
+ the pass automatically; there is no extra command. The Stop hook blocks once to
297
+ deliver the details. Previews (`man wait --peek`), `todo ls`, and `goals` stay
298
+ read-only. A delivery acknowledges current stale todo versions; new stale
299
+ versions stand again. Glass shows the last pass age beside goals and todos.
300
+
203
301
  ## `[wait]` — quiet helm and trap waiters
204
302
 
205
303
  | Key | Default | Meaning |
@@ -447,7 +545,11 @@ restriction; the classifier keeps its own safety policy:
447
545
  - the helm doing what you asked in its chat is not a bypass;
448
546
  - an answer you give on a glass card is your own, like a chat message.
449
547
 
450
- It also allows `Read` and `Edit` on `<lobstah home>/worktrees/**`.
548
+ It also allows `Read` and `Edit` on `<lobstah home>/worktrees/**`, permission
549
+ proposals, `lobstah dispatch` / `lobstah send` relays, and trap coordination
550
+ commands such as `report`, `todo`, `status`, `inbox`, `soak`, and `stow`. Applying the profile
551
+ adds missing allow rules, preserving existing rule order and backing up settings
552
+ before writing. Doctor warns when the profile needs applying.
451
553
  `[permissions]` adds to it:
452
554
 
453
555
  ```toml
@@ -472,7 +574,7 @@ allow = [["wrangler", "dev"]]
472
574
  - Text outside the markers is yours and stays.
473
575
  - 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.
474
576
  - **`rules/lobstah.rules`.** This file is wholly lobstah's. It holds the base rules plus `[permissions.codex]`:
475
- - allow: `lobstah permissions propose`. lobstah adds no `forbidden` or `prompt` rule of its own; Codex's reviewer keeps its own policy.
577
+ - allow: `lobstah permissions propose`, `lobstah dispatch`, `lobstah send`, and trap coordination commands such as `report`, `todo`, `status`, `inbox`, `soak`, and `stow`. lobstah adds no `forbidden` or `prompt` rule of its own; Codex's reviewer keeps its own policy.
476
578
  - `codex execpolicy check` loads every rule before the file is put in place.
477
579
 
478
580
  `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`.
@@ -30,10 +30,13 @@ says when the plugin is behind.
30
30
 
31
31
  ## Thrown trap startup
32
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.
33
+ Codex blocks at **Hooks need review** before the first model turn when any
34
+ hook definition is new or changed. A longer throw timeout cannot clear that
35
+ picker. `man throw` supplies invocation-scoped `hooks.state` for the installed
36
+ plugin's exact `lobstah hook <event>` commands. It asks Codex for each hash
37
+ through `hooks/list`, because from Codex 0.166 a plugin hook's trust also covers
38
+ the plugin's contents (`trusted_content_hash`). If Codex can't answer, lobstah
39
+ computes the hook hash itself, which is enough only before 0.166.
37
40
  Thrown sessions also set `check_for_update_on_startup=false` for that
38
41
  invocation, so an interactive update picker cannot hold the launch.
39
42
  The launcher rejects a plugin definition containing another command; it
@@ -41,6 +44,43 @@ never uses `--dangerously-bypass-hook-trust`, edits saved trust, enables a
41
44
  disabled hook, or approves repo/user/other-plugin hooks. Those still require
42
45
  their normal review. Manually launched Codex sessions still use `/hooks`.
43
46
 
47
+ ### On Codex's shared server
48
+
49
+ `man throw --remote-control` starts a Codex trap with `--remote unix://`, attached
50
+ to Codex's shared app-server. Its pane and a paired phone then drive one thread:
51
+ either can send a turn, and an approval reaches both, with the first answer
52
+ clearing the other. `[soak].codexRemoteControl = true` does this for every Codex
53
+ trap, including scheduled and batch throws. Other traps are unchanged.
54
+
55
+ To pair the phone, run `codex remote-control pair` at your own terminal. Pairing
56
+ grants the whole host, not one trap, and the phone can steer whatever runs on it.
57
+ Thrown traps run `danger-full-access` by default, so few commands ask for approval.
58
+
59
+ The trap's work runs in the server, not the pane, and that changes a few things:
60
+
61
+ - **Trust is saved.** `-c` flags don't reach the server, so a throw saves the same
62
+ trust it would otherwise pass for the session: lobstah's own hook commands,
63
+ committed project hooks and a lobstah-created worktree, in `~/.codex/config.toml`.
64
+ An explicit untrusted folder stays untrusted, and `enabled` isn't touched. A
65
+ folder that needs a person's decision still stops at Codex's own prompt.
66
+ - **No process is the trap's own.** The server hosts every trap on it, so the trap
67
+ records no harness process. `stow` from outside interrupts its turn and leaves
68
+ the server running. The pane's TUI stays open until it's closed.
69
+ - **Closing the pane doesn't stop the work.** The thread stays loaded while the
70
+ phone has it open. Otherwise it unloads about 60 seconds after its last client goes.
71
+ - **A server restart interrupts traps.** A forced restart stops running commands and
72
+ listeners, and the TUI reconnects within seconds. The lobstah daemon notices and
73
+ sends each trap a turn telling it to carry on, so an interrupted command can run
74
+ again. After a hard crash, the old command may still be running when it does.
75
+ - **The server keeps its own environment.** Start it from a plain terminal, or let
76
+ a throw start it. Never run `codex remote-control start` on a server with traps on
77
+ it: it restarts the server.
78
+ - **A message from the phone is an instruction.** What Chris sends in a trap's
79
+ session from his phone counts the same as typing in its pane.
80
+ - **The phone shows two hosts called `Mac`** when the desktop app is paired too.
81
+ Both list the same threads, and only the server's host can open a trap's thread.
82
+ Each thread is named `lobstah <trap>`.
83
+
44
84
  In 0.160.1, linked worktrees inherit project trust and hook declarations
45
85
  from their primary checkout, including the primary hook source path. They
46
86
  do not need blanket trust for `~/.codex/worktrees` or `~/.lobstah/worktrees`.
package/docs/man.md CHANGED
@@ -512,7 +512,8 @@ dispatch with its full brief, status log, inbox, and evidence, each trap
512
512
  with its lifecycle notices, message history, and catches, the notices
513
513
  tail, the merge view, and watches — with filters, a table/cards toggle,
514
514
  and the helm identified by name. Its tabs are On deck, Dispatches, Traps,
515
- PRs, Reviews, Reports, Notices, and Stats. The Stats tab shows catches per day as a
515
+ PRs, Reviews, Reports, Grants, Notices, Stats, and Settings, a read-only view of the
516
+ effective config with its secrets masked. The Stats tab shows catches per day as a
516
517
  53-week heatmap, with today, this week, the total, and the top traps; it
517
518
  reads `stats.json` from `GET /data/stats` and sends nothing. The Reports tab lists every report, unacked first,
518
519
  then newest first, and the repo filter and the search box (title, author,
@@ -606,7 +607,32 @@ the helm files to keep.
606
607
  in it.
607
608
  `lobstah todo done <id>` and `lobstah todo drop <id>` close one;
608
609
  `lobstah todo ls` (or bare `todo`) lists the open ones, and `--all` adds
609
- closed ones. They are stored per grounds in `todos/<grounds>.json` with
610
+ closed ones. `todo add "<text>" --at <time>` or `--in <duration>` gives one
611
+ a time, and `todo snooze <id> --until <time|duration>` sets or moves it. A
612
+ todo with a time is quiet and never stale until then. At its time, `man wait`
613
+ and the Stop hook wake the helm once with a `todo-due` event, and it stays
614
+ overdue until `done`, `snooze` or `drop`. Times read in `[helm].timezone`, in
615
+ 24-hour form: `fri 09:00`, `tomorrow 09:00`, `09:00`, `thu` (09:00 that day),
616
+ `2026-11-06 09:00`, `2026-11-06T14:00Z`. A day name means a goal day, which
617
+ runs from 04:00 to 04:00. So `fri 01:00` is the late end of Friday.
618
+ `todo add "<text>" --every "daily 09:00"`, `"weekdays 09:00"` or
619
+ `"weekly fri 09:00"` repeats one, and `--every` stands alone. `todo done`
620
+ moves it to the next occurrence, `todo skip <id>` passes one without counting
621
+ it as done, and `todo drop` ends it. Missed occurrences fire once when lobstah
622
+ next checks, with no backfill. A done on a series counts in `goals recap-data`.
623
+ `todo add "<text>" --when <trigger>` wakes on any of its triggers, and
624
+ `--when-all` on all of them; mixing the two is refused. `--at` or `--in` beside
625
+ either is a deadline backstop. The triggers are `card:<key>` (answered or
626
+ withdrawn), `dispatch:<id> done|blocked|needs-decision|failed`,
627
+ `pr:<owner>/<repo>#<n> merged|closed|green` and `trap:<name> free`. A `merged`
628
+ wait also fires if the PR closes without merging, and the event names that
629
+ outcome. A trigger
630
+ lobstah can't observe is refused and not stored. A PR trigger with no watch
631
+ registers one owned by the helm and says so; that watch also wakes the helm on
632
+ failing checks and requested changes. Each daemon tick reads only the local
633
+ record a trigger names, so it fires at most one interval late. A trigger whose
634
+ record is gone fires with what was lost. A todo waiting only on a trigger keeps
635
+ the age rule; a snooze quiets it and its unmet triggers keep listening. They are stored per grounds in `todos/<grounds>.json` with
610
636
  created and updated times. `man tend`, `man report`, and the glass deck
611
637
  show the open ones, and `man brief` re-injects them beside the charter at
612
638
  every session start and after compaction. A todo marked done stays in
@@ -1287,6 +1313,7 @@ lobstah man roster set <trap> --harness codex --model <m> --terminal iterm --con
1287
1313
  # save how a throw starts it; `default` or `key=` clears
1288
1314
  lobstah man throw <trap> [--timeout <secs>] # bring one trap back; wait until it listens
1289
1315
  lobstah man throw <trap> --bypass # a person, at a terminal: this start skips permission checks
1316
+ lobstah man throw <trap> --remote-control # this start can be driven from a phone: Claude's Remote Control, or Codex's shared server
1290
1317
  lobstah man throw --all # every eligible trap in your grounds, at once
1291
1318
  lobstah man throw --repo <key> # every eligible trap of one repo
1292
1319
  lobstah man throw --new --repo <key> --count N # N fresh traps (see "Starting a new trap")
@@ -1295,6 +1322,15 @@ lobstah man throw --dry-run <trap>... | --all | --repo <key> | --new ...
1295
1322
  lobstah man roster forget <trap> [--force] # remove a stowed trap's record, worktree, and ref
1296
1323
  ```
1297
1324
 
1325
+ `man throw --remote-control` makes one start reachable from a phone, new
1326
+ (`--new`) or returning. A Codex trap attaches to Codex's shared app-server, so its
1327
+ pane and a paired phone drive one thread. Other traps are unchanged unless
1328
+ `[soak].codexRemoteControl = true`, which covers every Codex start, including
1329
+ scheduled and batch throws. It saves hook and folder trust in
1330
+ `~/.codex/config.toml`. Pair the phone once with `codex remote-control pair` at your
1331
+ own terminal, which grants the whole host. See
1332
+ [Codex's shared server](harness/codex.md#on-codexs-shared-server) for what changes.
1333
+
1298
1334
  `man throw --dry-run` (or `--plan`) launches nothing and writes nothing. Each
1299
1335
  row says what a throw would do and why:
1300
1336
 
@@ -1349,12 +1385,16 @@ launched twice. Otherwise:
1349
1385
  fresh or rostered:
1350
1386
 
1351
1387
  - Claude Code: `--permission-mode auto`.
1352
- - Codex: `--approve-for-me`, which asks for approval on request and routes
1353
- each request to Codex's automatic reviewer, inside the workspace-write
1354
- sandbox. This is the nearest Codex has to Claude Code's auto mode. The
1355
- sandbox also gets the network (`-c sandbox_workspace_write.network_access=true`)
1356
- and, with `--add-dir`, lobstah's home and the repo's git directory: a trap
1357
- pushes, opens PRs, commits from a linked worktree, and reports.
1388
+ - Codex:
1389
+ `--sandbox danger-full-access --ask-for-approval on-request -c approvals_reviewer="auto_review"`.
1390
+ There is no OS sandbox. Codex asks for approval on request and routes each
1391
+ request to its automatic reviewer. This is the nearest Codex has to Claude
1392
+ Code's auto mode. The execpolicy rules in `$CODEX_HOME/rules` still apply:
1393
+ `prompt` goes to the reviewer and `forbidden` is refused.
1394
+
1395
+ A headless Codex dispatch is not a thrown trap and keeps the workspace-write
1396
+ sandbox. `heavy/` under lobstah's home is added as a writable directory, so its
1397
+ heavy commands can join the line.
1358
1398
 
1359
1399
  The mode is set, first match wins, by:
1360
1400
 
@@ -1568,3 +1608,34 @@ disk warn 412.3 GB free on ~/.lobstah/worktrees; minFreeGB 10; retentionDays 1
1568
1608
  after a reboot.
1569
1609
  - An honest six-verb status contract, validated at the write path, so the
1570
1610
  liaison never has to parse prose to know where things stand.
1611
+
1612
+ ## Configured repo-less traps
1613
+
1614
+ Declare one `[traps.<name>]` profile per grounds with `harness`, `surface`
1615
+ (`claude-desktop` or `terminal`), and `grounds`. `cwd` is an optional existing
1616
+ plain folder; `maxInstances` defaults to 1. See the configuration reference.
1617
+ A configured session joins with `lobstah soak --trap <name> --session <own-id>
1618
+ --wait`. Its identity, inbox, park, stow and ghost history survive without a
1619
+ git worktree. Forget frees an idle instance and keeps its folder and history.
1620
+
1621
+ Route a bounded app or browser step with:
1622
+
1623
+ ```sh
1624
+ lobstah dispatch --for trap:desk --grounds fleet --assist <original-id> --brief /tmp/inspection.md
1625
+ ```
1626
+
1627
+ The catch stays queued for that profile. The original worker keeps repo and
1628
+ PR ownership; a terminal child report returns its findings and attachments
1629
+ to the original dispatch once. Results arriving after the parent ends stay
1630
+ filed and notify the helm. Configured catches accept `--report` and
1631
+ `--attach`, rather than PR evidence. Tool approval remains with the harness
1632
+ Auto reviewer.
1633
+
1634
+ `lobstah man throw trap:desk` files one app-start card for an absent Claude
1635
+ Desktop profile. Open its prefilled Code link on the Mac, confirm the folder
1636
+ if Claude asks, and send the sign-on instruction. The catch stays queued
1637
+ until that session signs on and parks. Returning sessions use their saved
1638
+ app link when available; they are never cold-started in a terminal. Opening
1639
+ a card is not sign-on. Roster, status, tend and glass show the profile,
1640
+ grounds, surface, capacity, queued catches and current state. Desk catches
1641
+ share one host UI lease across grounds; the person's keyboard remains free.
@@ -314,10 +314,11 @@ plus Codex's `UserPromptSubmit` and `PermissionRequest` when declared, it says:
314
314
  - **trusted**: Codex runs a plugin hook only after the user trusts it in
315
315
  `/hooks`, and records trust in `config.toml` as
316
316
  `[hooks.state."lobstah@lobstah:hooks/hooks.json:<event>:<group>:<handler>"]`
317
- with a `trusted_hash`, a hash of the hook's definition. The row says
318
- `trusted` when that hash matches the hook as the plugin declares it now,
319
- `changed since trusted` when the hook changed after it was trusted (a
320
- plugin update; Codex asks again), and `untrusted` without an entry. Claude
317
+ with a `trusted_hash`, a hash of the hook's definition, and from Codex 0.166
318
+ a `trusted_content_hash` of the plugin's contents. The row reports Codex's
319
+ own answer when it can get one: `trusted`, `changed since trusted` when the
320
+ hook or plugin changed after it was trusted (a plugin update; Codex asks
321
+ again), or `untrusted` without an entry. Claude
321
322
  Code has no per-hook trust: `trust n/a`;
322
323
  - **last run**: when lobstah last saw the hook run (`never run` when it has
323
324
  not). Each hook run stamps `~/.lobstah/hook-runs.json` (`<harness>:<event>`
@@ -524,7 +525,7 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
524
525
  | `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`. |
525
526
  | 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. |
526
527
  | 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. |
527
- | 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. |
528
+ | 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`. One with a time wakes the helm once when it comes, as a `todo-due` event. Traps keep none. |
528
529
  | 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. |
529
530
 
530
531
  ## Attention contract
@@ -600,6 +601,24 @@ registry that decides what parses).
600
601
  | `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
 
602
603
 
604
+ ### Intent grants
605
+
606
+ A trap that will need more commands of one kind proposes them on its permission card, instead of raising a card per command: `lobstah report <id> needs-decision "<why>" --ask "<command>" --intent "<one sentence>" --allow <pattern> [--allow <pattern> ...]`. The card shows the patterns and the sentence before a person clicks. Only the glass can grant it: `man answer` can only say No.
607
+
608
+ The patterns are the grant. lobstah's own hook matches them, the same on Claude Code and Codex, from the moment the grant is made, and each match runs without asking and is recorded against the grant's id. The sentence only labels the grant on the card and the Grants tab, and allows nothing. A command that doesn't match goes to the harness's own reviewer, unchanged and told nothing. lobstah writes no harness configuration for these grants and adds no deny or prompt rules.
609
+
610
+ The card then offers three ways to allow, and No:
611
+
612
+ | Button | Scope | Lasts |
613
+ |---|---|---|
614
+ | Allow once | This trap, this command | One use, within the hour |
615
+ | Allow this kind for 1h | This trap only | One hour |
616
+ | Always allow this kind | Every trap in this repo | Until revoked |
617
+
618
+ A pattern is a command prefix or glob, `tool:<glob>`, or `path:<glob>` relative to the repo. Inside a command pattern, `*` matches within one word; a final `*` runs to the end, or to the closing quote when it's inside a quote. A command joined with shell syntax never matches, and neither does a protected target (grants, harness settings, `.git` at any depth and in any case). A proposal is refused if it's one word, starts with a glob, or names a command that runs anything, such as `bash`, `node` or `env`. A pattern is otherwise literal: a wrapper script that runs its arguments allows what it runs.
619
+
620
+ `lobstah grant ls` lists grants in force with their scope, label, patterns, expiry, uses and last use, and the glass's Grants tab shows the same with a Revoke button. `lobstah grant revoke <id>` takes one away; anyone may, the helm included. Each match is recorded with its tool and time, never its command text.
621
+
603
622
  ### Session grants
604
623
 
605
624
  `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.8.4",
3
+ "version": "0.8.5",
4
4
  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
5
5
  "license": "MIT",
6
6
  "author": "aequitas labs LLC",