lobstah 0.8.4 → 0.8.6

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`.
package/docs/design.md CHANGED
@@ -683,22 +683,35 @@ overrides the global, which overrides the adapter default.
683
683
  ## Glass source
684
684
 
685
685
  The spyglass (`lobstah glass`) is served as one self-contained HTML document,
686
- but it is written as ordinary source files under `apps/cli/glass/`, rendered
687
- with [Preact](https://preactjs.com) and [htm](https://github.com/developit/htm)
688
- (tagged-template markup, no JSX build):
686
+ written as ordinary source files and rendered with [Preact](https://preactjs.com)
687
+ and [htm](https://github.com/developit/htm) (tagged-template markup, no JSX
688
+ build). The UI lives in `packages/glass-ui`, which the hosted glass bundles too;
689
+ `apps/cli/glass/` holds only the local page's shell and its two-line entry;
690
+ the hosted glass (`services/wharf/glass/src/main.ts`) mounts the same UI on the
691
+ wharf backend with its sign-in around it, so the two never drift apart.
692
+ `apps/cli/test/glass-parity.test.ts` holds that: the same snapshot, rendered by
693
+ the local page's entry on the wharf's capabilities and by the hosted glass, must
694
+ give identical HTML for every shared tab and modal; `services/wharf/glass/src` may
695
+ hold only the host's files, and its stylesheet only the sign-in screen's rules.
696
+ A new view goes in `packages/glass-ui/ui/components`, where both glasses get it.
689
697
 
690
698
  | File | Holds |
691
699
  |---|---|
692
- | `index.html` | the document shell: head, the stylesheet slot, the script slot |
693
- | `glass.css` | every style; the design tokens (palette including the `.pr-*` badge states, spacing scale, card, badge, and modal metrics) are custom properties at the top |
694
- | `src/store.ts` | the one store: the latest snapshot, the route, the prefs, the open modal, the stale flag, the lob state |
695
- | `src/actions.ts` | every change the page can make (open or close a modal, set a preference, hide a lob, receive a snapshot) |
696
- | `src/main.ts` | the entry: builds the store from localStorage and the URL, renders `App` into the body on every change, starts polling |
697
- | `src/poll.ts` | `/data` polling: every 2s, one request at a time, paused while the tab is hidden; a 304 applies only the beats (server time and heartbeats) |
698
- | `src/route.ts` | the hash tabs (`#deck`, `#dispatches`, `#traps`, `#prs`, `#notices`) |
699
- | `src/prefs.ts` | the per-browser preferences and lob hides, in localStorage |
700
- | `src/components/*.ts` | `App`, `Header`, `Deck`, `Dispatches`, `Traps`, `PRs`, `Notices`, `Modal` (dispatch, trap, helm, PR, settings), `Lobs` |
701
- | `src/html.ts` | htm bound to Preact's `h` |
700
+ | `apps/cli/glass/index.html` | the document shell: head, the stylesheet slot, the script slot |
701
+ | `apps/cli/glass/src/main.ts` | the local entry: `startGlassPage(localBackend)` |
702
+ | `ui/glass.css` | every style; the design tokens (palette including the `.pr-*` badge states, spacing scale, card, badge, and modal metrics) are custom properties at the top |
703
+ | `ui/backend.ts` | `GlassBackend`, the one seam between the UI and its host: every read and write the page makes, and its capabilities (the tabs it fills, the actions it takes; the UI hides the rest) |
704
+ | `ui/backends/local.ts` | the local backend: `/data*`, `/report/*`, `/api/*` and `POST /requests` on the daemon that serves the page |
705
+ | `ui/backends/wharf.ts` | the wharf backend: the hosted glass's cookie-only `/api/glass*`, projected onto the same snapshot by `ui/wharf-snapshot.ts` (types in `ui/wharf-model.ts`); it fills deck, dispatches, traps, reviews and reports, and nothing it does not record |
706
+ | `ui/host.ts` | what a host adds around the glass: the hosted glass's sign-out and helm chip, Boats, human requests, notices and boat approval (the local glass adds nothing) |
707
+ | `ui/start.ts` | `startGlassPage(backend)`: builds the store from localStorage and the URL, renders `App` into the body on every change, starts polling (or renders one report on `/report/<key>`) |
708
+ | `ui/store.ts` | the one store: the latest snapshot, the route, the prefs, the open modal, the stale flag, the lob state |
709
+ | `ui/actions.ts` | every change the page can make (open or close a modal, set a preference, hide a lob, receive a snapshot) |
710
+ | `ui/poll.ts` | snapshot polling: every 2s, one request at a time, paused while the tab is hidden; an unchanged answer applies only the beats (server time and heartbeats) |
711
+ | `ui/route.ts` | the hash tabs (`#deck`, `#dispatches`, `#traps`, `#prs`, `#notices`) |
712
+ | `ui/prefs.ts` | the per-browser preferences and lob hides, in localStorage |
713
+ | `ui/components/*.ts` | `App`, `Header`, `Deck`, `Dispatches`, `Traps`, `PRs`, `Notices`, `Modal` (dispatch, trap, helm, PR, settings), `Lobs`, and the Markdown, link and harness-icon pieces |
714
+ | `ui/html.ts` | htm bound to Preact's `h` |
702
715
 
703
716
  Components are pure functions of the store. A new snapshot re-renders the
704
717
  page and Preact's reconciliation changes only the DOM whose data changed:
@@ -707,9 +720,10 @@ modal keeps its nodes across ticks, and scroll positions stay where the
707
720
  reader left them — no per-section hashing or manual node preservation. Only
708
721
  the active tab's section renders.
709
722
 
710
- The pure helpers stay beside the server in `apps/cli/src` and are imported by
711
- both sides: `glass-diff.ts` (the per-section selectors, tab route, filters,
712
- PR modal data) and `glass-lobs.ts` (which lobs walk). The `/data` payload
723
+ The pure helpers live in `packages/glass-ui/src` and are imported by both
724
+ sides (the CLI as `@lobstah/glass-ui`, the page from source): `glass-diff.ts`
725
+ (the per-section selectors, tab route, filters, PR modal data), `glass-lobs.ts`
726
+ (which lobs walk), and the Markdown and link parsers. The `/data` payload
713
727
  type, `GlassSnapshot`, lives in `@lobstah/core`: `glass-poll.ts` builds it
714
728
  from `buildGlassSnapshot()` and every component reads it, so a renamed field
715
729
  fails typecheck on both sides. `/data` carries dispatch summaries and the
@@ -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
@@ -679,8 +705,14 @@ the same rule.
679
705
  for a question such as "cut 0.6.0?"), who asked (`helm`), and when. It is
680
706
  stored in `~/.lobstah/decisions/<rid>/`: `decision.json`, `detail.md`, and
681
707
  `attachments/`. The claimed helm alone may ask.
708
+ - **Checklists.** Task items (`- [ ] step` or `- [x] step`), including nested
709
+ items, are tickable in decision details and filed reports. Ticks are saved
710
+ with the document and shared between desktop and phone; ticking never
711
+ answers a card. `lobstah man ask --show <card-or-report-key>` prints the
712
+ checked count and every item's state. Answered and withdrawn cards retain
713
+ read-only checklists at their existing glass links.
682
714
  - **Standing.** A decision stands until it is answered or the helm withdraws
683
- it with `lobstah man ask --withdraw <key>`, which removes its directory. A
715
+ it with `lobstah man ask --withdraw <key>`, which retains a read-only archive. A
684
716
  newer `man ask` on the same dispatch keeps the older decisions: each shows
685
717
  as its own card. `lobstah man ask ... --replace <key>` replaces that one
686
718
  standing decision; a key that is not standing is refused.
@@ -1287,6 +1319,7 @@ lobstah man roster set <trap> --harness codex --model <m> --terminal iterm --con
1287
1319
  # save how a throw starts it; `default` or `key=` clears
1288
1320
  lobstah man throw <trap> [--timeout <secs>] # bring one trap back; wait until it listens
1289
1321
  lobstah man throw <trap> --bypass # a person, at a terminal: this start skips permission checks
1322
+ lobstah man throw <trap> --remote-control # this start can be driven from a phone: Claude's Remote Control, or Codex's shared server
1290
1323
  lobstah man throw --all # every eligible trap in your grounds, at once
1291
1324
  lobstah man throw --repo <key> # every eligible trap of one repo
1292
1325
  lobstah man throw --new --repo <key> --count N # N fresh traps (see "Starting a new trap")
@@ -1295,6 +1328,15 @@ lobstah man throw --dry-run <trap>... | --all | --repo <key> | --new ...
1295
1328
  lobstah man roster forget <trap> [--force] # remove a stowed trap's record, worktree, and ref
1296
1329
  ```
1297
1330
 
1331
+ `man throw --remote-control` makes one start reachable from a phone, new
1332
+ (`--new`) or returning. A Codex trap attaches to Codex's shared app-server, so its
1333
+ pane and a paired phone drive one thread. Other traps are unchanged unless
1334
+ `[soak].codexRemoteControl = true`, which covers every Codex start, including
1335
+ scheduled and batch throws. It saves hook and folder trust in
1336
+ `~/.codex/config.toml`. Pair the phone once with `codex remote-control pair` at your
1337
+ own terminal, which grants the whole host. See
1338
+ [Codex's shared server](harness/codex.md#on-codexs-shared-server) for what changes.
1339
+
1298
1340
  `man throw --dry-run` (or `--plan`) launches nothing and writes nothing. Each
1299
1341
  row says what a throw would do and why:
1300
1342
 
@@ -1349,12 +1391,16 @@ launched twice. Otherwise:
1349
1391
  fresh or rostered:
1350
1392
 
1351
1393
  - 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.
1394
+ - Codex:
1395
+ `--sandbox danger-full-access --ask-for-approval on-request -c approvals_reviewer="auto_review"`.
1396
+ There is no OS sandbox. Codex asks for approval on request and routes each
1397
+ request to its automatic reviewer. This is the nearest Codex has to Claude
1398
+ Code's auto mode. The execpolicy rules in `$CODEX_HOME/rules` still apply:
1399
+ `prompt` goes to the reviewer and `forbidden` is refused.
1400
+
1401
+ A headless Codex dispatch is not a thrown trap and keeps the workspace-write
1402
+ sandbox. `heavy/` under lobstah's home is added as a writable directory, so its
1403
+ heavy commands can join the line.
1358
1404
 
1359
1405
  The mode is set, first match wins, by:
1360
1406
 
@@ -1568,3 +1614,34 @@ disk warn 412.3 GB free on ~/.lobstah/worktrees; minFreeGB 10; retentionDays 1
1568
1614
  after a reboot.
1569
1615
  - An honest six-verb status contract, validated at the write path, so the
1570
1616
  liaison never has to parse prose to know where things stand.
1617
+
1618
+ ## Configured repo-less traps
1619
+
1620
+ Declare one `[traps.<name>]` profile per grounds with `harness`, `surface`
1621
+ (`claude-desktop` or `terminal`), and `grounds`. `cwd` is an optional existing
1622
+ plain folder; `maxInstances` defaults to 1. See the configuration reference.
1623
+ A configured session joins with `lobstah soak --trap <name> --session <own-id>
1624
+ --wait`. Its identity, inbox, park, stow and ghost history survive without a
1625
+ git worktree. Forget frees an idle instance and keeps its folder and history.
1626
+
1627
+ Route a bounded app or browser step with:
1628
+
1629
+ ```sh
1630
+ lobstah dispatch --for trap:desk --grounds fleet --assist <original-id> --brief /tmp/inspection.md
1631
+ ```
1632
+
1633
+ The catch stays queued for that profile. The original worker keeps repo and
1634
+ PR ownership; a terminal child report returns its findings and attachments
1635
+ to the original dispatch once. Results arriving after the parent ends stay
1636
+ filed and notify the helm. Configured catches accept `--report` and
1637
+ `--attach`, rather than PR evidence. Tool approval remains with the harness
1638
+ Auto reviewer.
1639
+
1640
+ `lobstah man throw trap:desk` files one app-start card for an absent Claude
1641
+ Desktop profile. Open its prefilled Code link on the Mac, confirm the folder
1642
+ if Claude asks, and send the sign-on instruction. The catch stays queued
1643
+ until that session signs on and parks. Returning sessions use their saved
1644
+ app link when available; they are never cold-started in a terminal. Opening
1645
+ a card is not sign-on. Roster, status, tend and glass show the profile,
1646
+ grounds, surface, capacity, queued catches and current state. Desk catches
1647
+ 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.6",
4
4
  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
5
5
  "license": "MIT",
6
6
  "author": "aequitas labs LLC",