lobstah 0.7.8 → 0.7.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/main.js +2039 -1497
- package/dist/runner.js +17 -4
- package/docs/configuration.md +20 -4
- package/docs/man.md +73 -9
- package/docs/vocabulary.md +4 -3
- package/package.json +1 -1
package/dist/runner.js
CHANGED
|
@@ -1248,6 +1248,16 @@ function parseReviews(raw, reposRaw = {}) {
|
|
|
1248
1248
|
}
|
|
1249
1249
|
|
|
1250
1250
|
// packages/core/dist/config.js
|
|
1251
|
+
var TRAP_PERMISSION_MODES = ["auto", "bypass", "bypassPermissions", "default", "acceptEdits", "plan", "dontAsk"];
|
|
1252
|
+
function parseHarness(raw, where) {
|
|
1253
|
+
if (raw === void 0)
|
|
1254
|
+
return void 0;
|
|
1255
|
+
const h = raw;
|
|
1256
|
+
if (h.permissionMode !== void 0 && !TRAP_PERMISSION_MODES.includes(String(h.permissionMode))) {
|
|
1257
|
+
throw new Error(`${where}.permissionMode must be one of ${TRAP_PERMISSION_MODES.join(", ")}`);
|
|
1258
|
+
}
|
|
1259
|
+
return h;
|
|
1260
|
+
}
|
|
1251
1261
|
var POOL_NAME = /^[A-Za-z0-9_-]+$/;
|
|
1252
1262
|
function parsePools(raw, repos) {
|
|
1253
1263
|
const out = {};
|
|
@@ -1450,7 +1460,7 @@ function loadConfig() {
|
|
|
1450
1460
|
trunk: String(r.trunk ?? "main"),
|
|
1451
1461
|
setup: Array.isArray(r.setup) ? r.setup.map(String) : void 0,
|
|
1452
1462
|
env: r.env ?? void 0,
|
|
1453
|
-
harness: r.harness
|
|
1463
|
+
harness: parseHarness(r.harness, `[repos.${key}.harness]`),
|
|
1454
1464
|
pickup: r.pickup === void 0 ? void 0 : Boolean(r.pickup),
|
|
1455
1465
|
scratch: Array.isArray(r.scratch) ? r.scratch.map(String) : void 0,
|
|
1456
1466
|
pushEarly: r.pushEarly === void 0 ? void 0 : Boolean(r.pushEarly),
|
|
@@ -1476,7 +1486,7 @@ function loadConfig() {
|
|
|
1476
1486
|
}
|
|
1477
1487
|
return {
|
|
1478
1488
|
repos,
|
|
1479
|
-
harness: raw.harness ?? {},
|
|
1489
|
+
harness: parseHarness(raw.harness, "[harness]") ?? {},
|
|
1480
1490
|
limits: { ...DEFAULT_LIMITS, ...raw.limits ?? {} },
|
|
1481
1491
|
soak: parseSoak(raw.soak),
|
|
1482
1492
|
helm,
|
|
@@ -4033,7 +4043,7 @@ function buildPrompt(brief, opts) {
|
|
|
4033
4043
|
reporting,
|
|
4034
4044
|
`Use \`needs-decision\` when you are blocked on a question only a human can answer, then stop. New operator messages may arrive between your turns as user messages; treat them as instructions from the dispatcher.`,
|
|
4035
4045
|
`Before you wait on something outside lobstah (a human review, a PR review, a deploy), report \`lobstah report ${opts.id} paused "<note>" --waiting-on ${WAITING_ON.join("|")} --link <url>\`. Report \`working\` when you resume. A turn that ends on \`paused\` ends your session and stops its background work. The same session resumes when an operator message arrives, the \`--until\` time passes, or the PR you wait on ends; a merged PR finishes the dispatch as done.`,
|
|
4036
|
-
opts.existingPr ? `Commit your work with clear messages. This chain already has PR ${opts.existingPr.url}. The runner does not push or open another PR. ${pushRule(opts.existingPr.headRefName, opts.id)} Report done with the same PR URL. Do not merge anything.` : `Commit your work with clear messages. The runner pushes committed HEAD early and opens or adopts one draft PR for the branch when available
|
|
4046
|
+
opts.existingPr ? `Commit your work with clear messages. This chain already has PR ${opts.existingPr.url}. The runner does not push or open another PR. ${pushRule(opts.existingPr.headRefName, opts.id)} Report done with the same PR URL. Do not merge anything.` : `Commit your work with clear messages. The runner pushes committed HEAD early and opens or adopts one draft PR for the branch when available, titled \`lobstah ${opts.id.slice(0, 8)}\`; do not create a duplicate PR. When finished, give that PR a real title (\`gh pr edit --title\`), mark it ready for review if appropriate, then report done with its URL. Do not merge anything.`,
|
|
4037
4047
|
`--- BRIEF ---`,
|
|
4038
4048
|
opts.existingPr ? `${brief}
|
|
4039
4049
|
|
|
@@ -4608,6 +4618,9 @@ function remotePolicyFor(descriptor, repo, cfg) {
|
|
|
4608
4618
|
checkpointOnStop: repo.checkpointOnStop ?? cfg.limits.checkpointOnStop
|
|
4609
4619
|
};
|
|
4610
4620
|
}
|
|
4621
|
+
function draftPrTitle(id) {
|
|
4622
|
+
return `lobstah ${short3(id)}`;
|
|
4623
|
+
}
|
|
4611
4624
|
function coldNote(cold, cwd, trunk) {
|
|
4612
4625
|
const parts = [worktreeProgress(cwd, trunk)];
|
|
4613
4626
|
if (cold.origin) parts.push(originProgress(cold.origin.id, cold.origin.lane));
|
|
@@ -4744,7 +4757,7 @@ async function main(activeDir, lane, seams = {}) {
|
|
|
4744
4757
|
lane,
|
|
4745
4758
|
cwd,
|
|
4746
4759
|
trunk: repo.trunk,
|
|
4747
|
-
title:
|
|
4760
|
+
title: draftPrTitle(id),
|
|
4748
4761
|
policy: remotePolicy,
|
|
4749
4762
|
existingPrUrl: existingPr?.url
|
|
4750
4763
|
});
|
package/docs/configuration.md
CHANGED
|
@@ -36,7 +36,23 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
|
|
|
36
36
|
| `humanGateChecks` | no | Check names that fail until a person approves the change (e.g. `["owner approval"]`). `*` matches any run of characters. On a PR of a dispatch in this repo, a failed human gate never starts a PR repair or a CI-fix continuation. A PR whose only failing checks are human gates shows `repair.status: waiting` with `heldBy: human-gate`. A worker adds gates for one PR with `lobstah report --human-gate <check>`. |
|
|
37
37
|
|
|
38
38
|
`[repos.<key>.harness]` — per-repo harness defaults: `default` (`claude` \|
|
|
39
|
-
`codex`), `model`, `effort`.
|
|
39
|
+
`codex`), `model`, `effort`, `permissionMode`.
|
|
40
|
+
|
|
41
|
+
`permissionMode` is the mode a thrown trap of the repo starts in, cold,
|
|
42
|
+
resumed, or fresh: `auto` (the default when unset), `bypass` (also
|
|
43
|
+
`bypassPermissions`), or another Claude Code mode (`default`, `acceptEdits`,
|
|
44
|
+
`plan`, `dontAsk`). Auto is Claude Code `--permission-mode auto` and Codex
|
|
45
|
+
`--approve-for-me`; bypass is Claude Code `--dangerously-skip-permissions` and
|
|
46
|
+
Codex `--dangerously-bypass-approvals-and-sandbox`. A trap's roster profile
|
|
47
|
+
and `man throw --bypass` come first. Any other value is a config error.
|
|
48
|
+
|
|
49
|
+
```toml
|
|
50
|
+
[harness]
|
|
51
|
+
permissionMode = "bypass" # every repo's traps start with no permission checks
|
|
52
|
+
|
|
53
|
+
[repos.web.harness]
|
|
54
|
+
permissionMode = "auto" # except web's
|
|
55
|
+
```
|
|
40
56
|
|
|
41
57
|
`effort` reaches both harnesses: Claude as its effort level (`low`, `medium`,
|
|
42
58
|
`high`, `xhigh`, `max`), Codex as `model_reasoning_effort`. Set it for Claude
|
|
@@ -105,7 +121,7 @@ Call out migrations that are not reversible.
|
|
|
105
121
|
|
|
106
122
|
## `[harness]` — global harness defaults
|
|
107
123
|
|
|
108
|
-
Same
|
|
124
|
+
Same four keys as the per-repo block. Precedence for every harness setting:
|
|
109
125
|
**descriptor > repo > global > adapter default.**
|
|
110
126
|
|
|
111
127
|
## `[limits]`
|
|
@@ -118,8 +134,8 @@ Same three keys as the per-repo block. Precedence for every harness setting:
|
|
|
118
134
|
| `maxRestartAttempts` | `2` | Bounded restart ladder for dead and wedged runners. |
|
|
119
135
|
| `wallClockSecs` | `3600` | Initial active-work window. Progress extends it, up to `maxWallClockSecs`; time paused with `report paused --waiting-on` does not count. |
|
|
120
136
|
| `maxWallClockSecs` | `4 × wallClockSecs` | Hard active-work ceiling across restarts. |
|
|
121
|
-
| `pushEarly` | `true` | For a new chain, push each new committed HEAD to its non-trunk branch on `origin` within 10 seconds. A rejected push is noted and retried only after HEAD moves. A follow-up whose chain already has a PR, and a dispatch whose descriptor names a PR (a repair
|
|
122
|
-
| `draftPr` | `true` | For a new chain, after first push, adopt an existing PR or open one draft PR when `gh` is available. A follow-up with a chain PR, and a dispatch whose descriptor names a PR, keeps that PR and its watch; it does not open another. |
|
|
137
|
+
| `pushEarly` | `true` | For a new chain, push each new committed HEAD to its non-trunk branch on `origin` within 10 seconds. A rejected push is noted and retried only after HEAD moves. A follow-up whose chain already has a PR, and a dispatch whose descriptor names a PR (a repair, a rebase chore, or `lobstah dispatch --pr <url|number>`), does not push automatically; its worker pushes to the existing PR's head branch. A brief that only mentions a PR in prose does not name it: dispatch with `--pr` (`dispatch` warns when the brief names a PR of the repo without it). |
|
|
138
|
+
| `draftPr` | `true` | For a new chain, after first push, adopt an existing PR or open one draft PR when `gh` is available, titled `lobstah <short id>` (never from the brief); the worker gives it its real title. A follow-up with a chain PR, and a dispatch whose descriptor names a PR (`--pr`), keeps that PR and its watch; it does not open another. |
|
|
123
139
|
| `checkpointOnStop` | `true` | Before a nonterminal stop, checkpoint eligible tracked and untracked files. A new chain then pushes; a follow-up with a chain PR leaves the checkpoint local for its worker to push. Ignored files and secret/build denylist paths are excluded. Set all three switches to `false` for prior runner behavior. |
|
|
124
140
|
|
|
125
141
|
A runner extends its active-work window when a fresh activity event or new HEAD
|
package/docs/man.md
CHANGED
|
@@ -18,11 +18,12 @@ The liaison never watches the workers — the daemon does that with no model in
|
|
|
18
18
|
the loop. The liaison reads `lobstah status` when you ask, which is the
|
|
19
19
|
token-efficiency point: supervision is a filesystem read, not a conversation.
|
|
20
20
|
Headless runners preserve new-chain committed work on `origin` as HEAD moves
|
|
21
|
-
and open one draft PR when `gh` is available
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
a
|
|
25
|
-
|
|
21
|
+
and open one draft PR when `gh` is available, titled `lobstah <short id>`
|
|
22
|
+
(never from the brief; the worker gives it its real title). On a nonterminal
|
|
23
|
+
stop they checkpoint eligible worktree files and push once more. A follow-up
|
|
24
|
+
whose chain already has a PR, and a dispatch that names a PR with `--pr`,
|
|
25
|
+
keeps that PR and its watch. It does not push or open a second PR
|
|
26
|
+
automatically; its worker pushes to the existing PR's head branch. The final status note names the saved branch, commit, and PR, so the
|
|
26
27
|
lobstah man can send a continuation without losing work.
|
|
27
28
|
|
|
28
29
|
**The helm is harness-agnostic: drive the fleet from whichever session you
|
|
@@ -50,7 +51,10 @@ You are my liaison for delegated coding work. For any task that should run in
|
|
|
50
51
|
the background, dispatch it with the `lobstah` CLI instead of doing it inline:
|
|
51
52
|
|
|
52
53
|
- `lobstah dispatch --repo <key> --brief-text "<full brief>"` — returns an id.
|
|
53
|
-
Write briefs that stand alone; the worker has no other context.
|
|
54
|
+
Write briefs that stand alone; the worker has no other context. When the
|
|
55
|
+
work belongs on an open PR, add `--pr <url|number>`: the worker pushes to
|
|
56
|
+
that PR's branch and no new PR is opened. A brief that only mentions the PR
|
|
57
|
+
is not enough (dispatch warns).
|
|
54
58
|
- `lobstah status [<id>]`, `lobstah ls` — check progress when I ask, not on a loop.
|
|
55
59
|
- `lobstah send <id> "<instruction>"` — steer a live dispatch, add to a queued
|
|
56
60
|
dispatch's inbox, or wake a finished chain as a follow-up. Sending to any
|
|
@@ -578,8 +582,22 @@ the helm files to keep.
|
|
|
578
582
|
image the page names by bare filename (``) resolves to
|
|
579
583
|
that directory. The note stays one line.
|
|
580
584
|
- **Filing a helm report.** `lobstah man file <file.md> [--attach <file> ...]
|
|
581
|
-
[--title <text>]`. It is stored under the helm's
|
|
582
|
-
`reports/<grounds>/<rid>/`, with the same layout, and the author
|
|
585
|
+
[--attach-dir <dir> ...] [--title <text>]`. It is stored under the helm's
|
|
586
|
+
grounds, `reports/<grounds>/<rid>/`, with the same layout, and the author
|
|
587
|
+
is `helm`. The helm files its own reports, plans, and step lists this way:
|
|
588
|
+
a file left only in the chat does not reach the glass deck.
|
|
589
|
+
- **Images in folders.** A page may link an image by a path under its own
|
|
590
|
+
directory (``). `--attach` takes that
|
|
591
|
+
path from the working directory, or else from the page's directory.
|
|
592
|
+
`--attach-dir <dir>` attaches every image (`.png .jpg .jpeg .gif .webp`)
|
|
593
|
+
directly in a folder. Attachments are stored flat, so the filed copy
|
|
594
|
+
rewrites each such link to the image's stored name (`01.jpg`, or
|
|
595
|
+
`01-2.jpg` when two folders hold an `01.jpg`). A path resolved from the
|
|
596
|
+
page's directory must stay inside its tree: `..` out of it, and an
|
|
597
|
+
`--attach-dir` outside it, are refused, and nothing is filed. A link that
|
|
598
|
+
leaves the tree, or names an image that was not attached, is kept as it
|
|
599
|
+
is; the glass does not load it, and the filing prints a `warning` that
|
|
600
|
+
lists such links. Both `report --report` and `man file` take these flags.
|
|
583
601
|
- **The helm's todos.** Reminders the helm keeps for itself ("merge #2268
|
|
584
602
|
once the API is in production") go in `lobstah todo add "<text>"`, not
|
|
585
603
|
only in the conversation. The text is free: any detail, link, or PR goes
|
|
@@ -693,7 +711,8 @@ the same rule.
|
|
|
693
711
|
files in `~/.lobstah/requests/<id>/`. The payload is the decision `key`,
|
|
694
712
|
`title`, `dispatch`, `lane`, `repo`, the `option`, the `text`, and the
|
|
695
713
|
stored `attachments`. `answer.json` in the decision's directory marks it
|
|
696
|
-
answered and
|
|
714
|
+
answered, names the request, and holds the answer too: the `option`, the
|
|
715
|
+
`text` (also when no option was chosen), and the stored `attachments`.
|
|
697
716
|
- **The POST.** Send is a same-origin POST to `/requests` with the page's
|
|
698
717
|
token (header `x-lobstah-token`), the guard the **↗ open** button uses.
|
|
699
718
|
The body is `{ "kind": "decision-answer", "payload": { "key", "option",
|
|
@@ -1251,6 +1270,7 @@ lobstah man roster # every trap the roster keep
|
|
|
1251
1270
|
lobstah man roster set <trap> --harness codex --model <m> --terminal iterm --config effort=high
|
|
1252
1271
|
# save how a throw starts it; `default` or `key=` clears
|
|
1253
1272
|
lobstah man throw <trap> [--timeout <secs>] # bring one trap back; wait until it listens
|
|
1273
|
+
lobstah man throw <trap> --bypass # a person, at a terminal: this start skips permission checks
|
|
1254
1274
|
lobstah man throw --all # every eligible trap in your grounds, at once
|
|
1255
1275
|
lobstah man throw --repo <key> # every eligible trap of one repo
|
|
1256
1276
|
lobstah man throw --new --repo <key> --count N # N fresh traps (see "Starting a new trap")
|
|
@@ -1301,11 +1321,55 @@ launched twice. Otherwise:
|
|
|
1301
1321
|
`--effort`, `--permission-mode` for Claude; `-m`, `model_reasoning_effort`
|
|
1302
1322
|
for Codex); a setting with no flag is named as not applied. The first
|
|
1303
1323
|
prompt redeems the ticket, so the session signs on as the same trap.
|
|
1324
|
+
Every start names its permission mode (see **Permission mode** below).
|
|
1304
1325
|
4. It returns when the trap has signed on and parked, and prints whether it
|
|
1305
1326
|
resumed or started cold, and why. Past `--timeout` (default 180 seconds)
|
|
1306
1327
|
it withdraws the reservation, so a late session cannot take the trap,
|
|
1307
1328
|
posts `trap-start-failed`, and leaves the roster unchanged.
|
|
1308
1329
|
|
|
1330
|
+
**Permission mode.** A thrown trap starts in auto mode, cold or resumed,
|
|
1331
|
+
fresh or rostered:
|
|
1332
|
+
|
|
1333
|
+
- Claude Code: `--permission-mode auto`.
|
|
1334
|
+
- Codex: `--approve-for-me`, which asks for approval on request and routes
|
|
1335
|
+
each request to Codex's automatic reviewer, inside the workspace-write
|
|
1336
|
+
sandbox. This is the nearest Codex has to Claude Code's auto mode. The
|
|
1337
|
+
sandbox also gets the network (`-c sandbox_workspace_write.network_access=true`)
|
|
1338
|
+
and, with `--add-dir`, lobstah's home and the repo's git directory: a trap
|
|
1339
|
+
pushes, opens PRs, commits from a linked worktree, and reports.
|
|
1340
|
+
|
|
1341
|
+
The mode is set, first match wins, by:
|
|
1342
|
+
|
|
1343
|
+
1. `lobstah man throw <trap> --bypass`: this throw only.
|
|
1344
|
+
2. The trap's roster profile: `man roster set <trap> --config
|
|
1345
|
+
permissionMode=<mode>`, or `lobstah trap bypass <trap> on|off`.
|
|
1346
|
+
3. `permissionMode` under `[repos.<key>.harness]`, then under `[harness]`,
|
|
1347
|
+
in `config.toml`, for every throw of that repo's traps, rostered or
|
|
1348
|
+
fresh (`--new`), and for every restart.
|
|
1349
|
+
4. `auto`.
|
|
1350
|
+
|
|
1351
|
+
A mode is `auto`, `bypass` (also spelled `bypassPermissions`), or another
|
|
1352
|
+
Claude Code mode (`default`, `acceptEdits`, `plan`, `dontAsk`). For Codex,
|
|
1353
|
+
`default` starts Codex in its own default; another mode has no Codex flag
|
|
1354
|
+
and is named as not applied. The mode a trap was last seen in is not carried
|
|
1355
|
+
to its next start.
|
|
1356
|
+
|
|
1357
|
+
Bypass is a person's choice, made at a terminal. `man throw --bypass`,
|
|
1358
|
+
`trap bypass on`, and `man roster set --config permissionMode=bypass` (or
|
|
1359
|
+
`bypass=true`) each refuse inside an agent session (the helm's too) or
|
|
1360
|
+
without a terminal, and each prints the bypass warning. The config file is a
|
|
1361
|
+
person's to edit. A `--dry-run` with `--bypass` launches nothing, so it is
|
|
1362
|
+
allowed.
|
|
1363
|
+
|
|
1364
|
+
Bypass is Claude Code `--dangerously-skip-permissions` and Codex
|
|
1365
|
+
`--dangerously-bypass-approvals-and-sandbox`. The throw prints the mode it
|
|
1366
|
+
started with, and `--dry-run` shows it in a `mode` column. `man roster` shows
|
|
1367
|
+
the mode each trap's next throw starts in. `man tend` and `lobstah traps`
|
|
1368
|
+
show it in the worker column, for example `codex · gpt-6.1-sol · auto`. For a
|
|
1369
|
+
live Claude trap, that is the mode its hooks last reported, since a person
|
|
1370
|
+
can change it mid-session. Codex reports `default` whatever its approvals,
|
|
1371
|
+
so a live Codex trap shows the mode its throw started it in.
|
|
1372
|
+
|
|
1309
1373
|
**Batches.** `man throw --all` throws every eligible trap in the grounds
|
|
1310
1374
|
(`--grounds`, else the caller's helm grounds, else every repo); `--repo`
|
|
1311
1375
|
narrows to one repo; `--new --count N` starts N fresh ones. Every launch runs
|
package/docs/vocabulary.md
CHANGED
|
@@ -468,11 +468,12 @@ worktree is refused (the session lock); a stale one is adopted.
|
|
|
468
468
|
| `soak` | Sign the worktree's trap on and take matching work. From a primary checkout, or with `--repo <key>` from outside any configured repo, it first creates a linked worktree like a dispatch does (fetch trunk, new branch from `origin/<trunk>`, `setup` commands), prints `worktree:`, `created: true`, `branch:`, and, when the session is elsewhere, `instruction: cd <path> ...`; the session works in that directory. If creation fails, nothing is signed on and the partial worktree and branch are removed. `--repo` in a linked worktree must match its repo. A session that already mans a trap re-uses it (resolved from the session id) and never gets a second worktree. `--session` is needed only on first sign-on. `--one` stows after the first catch. `--wait` registers a watcher and waits for work; a quiet timeout exits 3. Workers never run `man` verbs. |
|
|
469
469
|
| `soak title-set` (alias `trap title-set`) | Confirm this session applied the title sign-on printed (`step: Apply this title: <title>`). The registration records `titleSet` and `titleSetAt` and drops `titlePending`; sign-on is complete. Until then, SessionStart and Stop remind the session once per turn, at most three times. A trap runs `soak title-set`: Claude Code's worktree isolation refuses a command line containing `trap`. |
|
|
470
470
|
| `stow` | Sign the trap off (in the worktree, or elsewhere by session id: `--session <id>` or `$CLAUDE_CODE_SESSION_ID`); an unfinished catch requeues, done/failed finalizes in `done/`, and a cancelled catch finalizes as failed. Unread messages are held for `[soak].signOffGraceSecs` (default 600): they deliver if the same worktree re-soaks in time, else the daemon bounces them to the helm (at once when stow removed the worktree or the grace is `0`). A trap always stows itself freely; stowing someone else's (`--wt`) is steering — the claimed helm's alone. Stow closes the seat, never the session: an opted-in session can only be asked to stop, and a still-looping worker re-enlists visibly (`trap-signed-on`). By default stow keeps the worktree (`worktree: kept`, `reason: stow keeps the worktree; --remove removes it`), so `man throw` can bring the trap back in it; `--keep` is accepted and changes nothing. `--remove` removes the worktree when soak created it (`createdWorktree: true`) and prints `worktree: removed`, `path:`, and `returnTo:`; it still keeps it (`worktree: kept`, `reason:`) when soak did not create it, or when it holds uncommitted changes, untracked files that are not ignored, commits absent from its upstream, or no upstream. `--remove --force` explicitly allows discarding unsaved checkout files; `--force` alone refuses. The branch is deleted (`branchDeleted:`) only when all its commits are on its upstream (with no upstream: on some remote branch); otherwise `branchKept: <branch> (<reason>)`. `--wt` follows the same rules. The SessionEnd hook (`stow --quiet`) signs off only when the ending session is the trap's registered session (another session in the worktree ending is a no-op) and keeps the worktree; SessionEnd cannot tell a restart or compaction from an exit (Claude Code's `reason` is `clear`, `resume`, `logout`, `prompt_input_exit`, or `other`; Codex's is always `other`), so the grace covers a session that signs on again. |
|
|
471
|
-
| `report needs-decision --ask <command>` (or `--ask-path <file>`) | A trap whose harness check refused a call asks for it. Besides the status, it files a decision card with the exact command or path and three options: **Allow once** (the asking trap, one use, within the hour), **Allow always** (every trap, until revoked), **No**. Only a glass answer can allow; `man answer`, which the helm runs, can only say No. An allow writes a grant and tells the dispatch's inbox the grant id and to run the command again exactly as shown. |
|
|
472
|
-
| `grant <command>` (alias `trap grant`) | A person allows traps to run one command: exactly, or with `--prefix` the command followed by more arguments (never anything joined on with `;`, `&`, `|`, a redirect or a subshell). `--path <file>` allows the write tools on one file, or under a directory with a trailing slash. `--once` (one use, within the hour unless `--expires`), `--harness claude\|codex\|any`, `--trap <name>`. It asks to confirm, and refuses without a terminal or inside an agent session. Grants are kept in `grants/ledger.jsonl`, an append-only, hash-chained list of grants, uses and revocations; a damaged ledger grants nothing. Grants apply to traps only. Claude Code honours them through the plugin's mod (before the auto-mode classifier) and its PermissionRequest hook; Codex through its PermissionRequest hook (before the approval reviewer). A deny rule, a tool's own check and the organization's limits still stand. |
|
|
471
|
+
| `report needs-decision --ask <command>` (or `--ask-path <file>`) | A trap whose harness check refused a call asks for it. Besides the status, it files a decision card with the exact command or path and three options: **Allow once** (the asking trap, one use, within the hour), **Allow always** (every trap, until revoked; the card says its scope), **No**. Only a glass answer can allow; `man answer`, which the helm runs, can only say No. An allow writes a grant and tells the dispatch's inbox the grant id and to run the command again exactly as shown. |
|
|
472
|
+
| `grant <command>` (alias `trap grant`) | A person allows traps to run one command: exactly, or with `--prefix` the command followed by more arguments (never anything joined on with `;`, `&`, `|`, a redirect or a subshell). `--path <file>` allows the write tools on one file, or under a directory with a trailing slash. `--once` (one use, within the hour unless `--expires`), `--harness claude\|codex\|any`, `--trap <name>`. An always-grant follows the repo, not one worktree: a path inside a configured repo is kept relative to its root and covers that path in any checkout of the repo (the main checkout and every worktree git knows of); in a command, checkout roots read as `{repo:<key>}`. A path outside every repo, and a once-grant, stay exact. It asks to confirm, and refuses without a terminal or inside an agent session. Grants are kept in `grants/ledger.jsonl`, an append-only, hash-chained list of grants, uses and revocations; a damaged ledger grants nothing. Grants apply to traps only. Claude Code honours them through the plugin's mod (before the auto-mode classifier) and its PermissionRequest hook; Codex through its PermissionRequest hook (before the approval reviewer). A deny rule, a tool's own check and the organization's limits still stand. |
|
|
473
473
|
| `grants` (alias `trap grants`) | The grants in force: id, what, once or always, harness, trap, who granted it, when, uses, expiry. `--all` adds spent, expired and revoked ones; `--json` for machines. A trap checks a relayed approval here: a grant listed is the person's, a message saying they approved is not. |
|
|
474
474
|
| `revoke <id>` (alias `trap revoke`) | Revoke a grant. Anyone may take a permission away. |
|
|
475
|
-
| `trap bypass <trap> on\|off` | A person, at a terminal, starts the trap with no permission checks from its next start: Claude Code `--
|
|
475
|
+
| `trap bypass <trap> on\|off` | A person, at a terminal, starts the trap with no permission checks from its next start: Claude Code `--dangerously-skip-permissions`, Codex `--dangerously-bypass-approvals-and-sandbox`. It warns that the trap then acts as the person's account with no checks, for isolated machines only, and asks to confirm. A running session keeps its mode. Off needs no terminal. |
|
|
476
|
+
| `man throw <trap> --bypass` | A person, at a terminal, starts this one throw with no permission checks (same flags as `trap bypass`). It refuses inside an agent session or without a terminal. Without it, and without `trap bypass`, a throw starts the trap in auto mode: Claude Code `--permission-mode auto`, Codex `--approve-for-me` (sandbox network on, lobstah's home and the repo's git directory writable). A roster `permissionMode` overrides `[harness].permissionMode` in config.toml (the repo's, then the global), which overrides auto; `bypass` is a mode there too. `man roster set` saves bypass only for a person at a terminal. |
|
|
476
477
|
| sign-off grace | For `[soak].signOffGraceSecs` after a trap signs off (`~/.lobstah/signed-off/<trap>.json`), its address is held: `send wt:<trap>` queues and warns instead of refusing, held messages wait, and work addressed to it raises no `bait-orphaned` notice. A re-soak of the same worktree releases the hold; after the grace, the daemon bounces the held messages (`message-bounced`). |
|
|
477
478
|
| address | `--for wt:<trap>` targets one trap; `session:<id>` is an alias resolved to the trap at dispatch time. **Sticky:** addressed work is never the daemon's — it waits for its trap; an orphan (trap gone) surfaces as a `bait-orphaned` notice for the helm to re-address, release, or cancel. Delivery stamps a receipt (`deliveredTo`/`deliveredAt`) into evidence. Unaddressed work defers to a parked matching trap for `[soak].deferSecs`, then the daemon spawns headless. |
|
|
478
479
|
| message | `send wt:<trap> "<text>"` — a conversational continuation, not work: no branch, no catch, no report obligation. Delivered before bait at the trap's next park, stamped with its sender (`helm` / `session:<id>` / `terminal`); undeliverable messages bounce to the helm as notices. |
|