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.
- package/dist/main.js +15122 -9986
- package/dist/runner.js +3467 -2856
- package/docs/configuration.md +107 -5
- package/docs/harness/codex.md +44 -4
- package/docs/man.md +79 -8
- package/docs/vocabulary.md +24 -5
- package/package.json +1 -1
package/docs/configuration.md
CHANGED
|
@@ -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
|
|
199
|
-
| `
|
|
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/harness/codex.md
CHANGED
|
@@ -30,10 +30,13 @@ says when the plugin is behind.
|
|
|
30
30
|
|
|
31
31
|
## Thrown trap startup
|
|
32
32
|
|
|
33
|
-
Codex
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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,
|
|
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.
|
|
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:
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
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.
|
package/docs/vocabulary.md
CHANGED
|
@@ -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
|
|
318
|
-
`
|
|
319
|
-
|
|
320
|
-
plugin
|
|
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.
|