lobstah 0.7.11 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/main.js +9927 -8404
- package/dist/runner.js +34 -2
- package/docs/configuration.md +19 -10
- package/docs/harness/codex.md +41 -0
- package/docs/man.md +29 -11
- package/docs/pickup.md +8 -14
- package/docs/vocabulary.md +10 -4
- package/package.json +1 -1
package/dist/runner.js
CHANGED
|
@@ -1300,10 +1300,13 @@ function validReviewTool(value) {
|
|
|
1300
1300
|
// packages/core/dist/reviews.js
|
|
1301
1301
|
var REVIEW_WORK = ["off", "trap", "headless"];
|
|
1302
1302
|
var REVIEW_POST = ["draft", "auto"];
|
|
1303
|
+
var REVIEW_MODES = ["notify", "on-demand", "auto-draft", "auto-review"];
|
|
1303
1304
|
var DEFAULT_REVIEWS = {
|
|
1304
1305
|
enabled: false,
|
|
1306
|
+
mode: "notify",
|
|
1307
|
+
publish: false,
|
|
1305
1308
|
repos: "configured",
|
|
1306
|
-
work: "
|
|
1309
|
+
work: "off",
|
|
1307
1310
|
post: "draft",
|
|
1308
1311
|
limits: { wallClockSecs: 900, maxTurns: 40 },
|
|
1309
1312
|
trapWaitSecs: 600,
|
|
@@ -1329,6 +1332,19 @@ function strings(value, where) {
|
|
|
1329
1332
|
}
|
|
1330
1333
|
function parseSettings(raw, where) {
|
|
1331
1334
|
const out = {};
|
|
1335
|
+
if (raw.mode !== void 0)
|
|
1336
|
+
out.mode = oneOf(raw.mode, REVIEW_MODES, `${where}.mode`);
|
|
1337
|
+
else if (raw.post === "auto")
|
|
1338
|
+
out.mode = "auto-review";
|
|
1339
|
+
else if (raw.work === "off")
|
|
1340
|
+
out.mode = "on-demand";
|
|
1341
|
+
else if (raw.work !== void 0 || raw.post !== void 0)
|
|
1342
|
+
out.mode = "auto-draft";
|
|
1343
|
+
if (raw.publish !== void 0) {
|
|
1344
|
+
if (typeof raw.publish !== "boolean")
|
|
1345
|
+
throw new Error(`${where}.publish must be a boolean`);
|
|
1346
|
+
out.publish = raw.publish;
|
|
1347
|
+
}
|
|
1332
1348
|
if (raw.work !== void 0)
|
|
1333
1349
|
out.work = oneOf(raw.work, REVIEW_WORK, `${where}.work`);
|
|
1334
1350
|
if (raw.post !== void 0)
|
|
@@ -1355,6 +1371,9 @@ function parseReviews(raw, reposRaw = {}) {
|
|
|
1355
1371
|
if (typeof r !== "object" || Array.isArray(r))
|
|
1356
1372
|
throw new Error("[reviews] must be a table");
|
|
1357
1373
|
const base = parseSettings(r, "[reviews]");
|
|
1374
|
+
const requestedMode = base.mode ?? "notify";
|
|
1375
|
+
const publish = base.publish ?? requestedMode === "auto-review";
|
|
1376
|
+
const mode = requestedMode.startsWith("auto-") ? publish ? "auto-review" : "auto-draft" : requestedMode;
|
|
1358
1377
|
const perRepo = {};
|
|
1359
1378
|
for (const [key, repo] of Object.entries(reposRaw)) {
|
|
1360
1379
|
if (repo.reviews !== void 0)
|
|
@@ -1363,6 +1382,11 @@ function parseReviews(raw, reposRaw = {}) {
|
|
|
1363
1382
|
return {
|
|
1364
1383
|
...DEFAULT_REVIEWS,
|
|
1365
1384
|
...base,
|
|
1385
|
+
mode,
|
|
1386
|
+
publish,
|
|
1387
|
+
work: mode.startsWith("auto-") ? base.work && base.work !== "off" ? base.work : "trap" : "off",
|
|
1388
|
+
post: publish ? "auto" : "draft",
|
|
1389
|
+
...Object.fromEntries(["identity", "tokenCommand", "tokenEnv", "tokenFile"].filter((k) => r[k] !== void 0).map((k) => [k, String(r[k])])),
|
|
1366
1390
|
limits: { ...DEFAULT_REVIEWS.limits, ...base.limits },
|
|
1367
1391
|
enabled: r.enabled === void 0 ? false : Boolean(r.enabled),
|
|
1368
1392
|
repos: r.repos === void 0 ? "configured" : oneOf(r.repos, ["configured", "any"], "[reviews].repos"),
|
|
@@ -1515,6 +1539,8 @@ function parseAttentionKinds(raw) {
|
|
|
1515
1539
|
}
|
|
1516
1540
|
function parseSoak(raw) {
|
|
1517
1541
|
const soak = { ...DEFAULT_SOAK, ...raw ?? {} };
|
|
1542
|
+
if (!Number.isInteger(soak.codexStartSecs) || soak.codexStartSecs < 1)
|
|
1543
|
+
throw new Error("soak.codexStartSecs must be a positive whole number");
|
|
1518
1544
|
if (typeof soak.acceptWharfStarts !== "boolean")
|
|
1519
1545
|
throw new Error("soak.acceptWharfStarts must be true or false");
|
|
1520
1546
|
if (soak.terminal !== void 0 && soak.terminal !== "terminal" && soak.terminal !== "iterm") {
|
|
@@ -1523,6 +1549,7 @@ function parseSoak(raw) {
|
|
|
1523
1549
|
return soak;
|
|
1524
1550
|
}
|
|
1525
1551
|
var DEFAULT_SOAK = {
|
|
1552
|
+
codexStartSecs: 600,
|
|
1526
1553
|
acceptWharfStarts: false,
|
|
1527
1554
|
deferSecs: 90,
|
|
1528
1555
|
claimIdleNoticeSecs: 180,
|
|
@@ -1532,6 +1559,7 @@ var DEFAULT_SOAK = {
|
|
|
1532
1559
|
signOffGraceSecs: 600
|
|
1533
1560
|
};
|
|
1534
1561
|
var DEFAULT_HELM = {
|
|
1562
|
+
chat: "full",
|
|
1535
1563
|
queuedNoticeSecs: 180,
|
|
1536
1564
|
stalledNoticeSecs: 1200,
|
|
1537
1565
|
idleWorkingNoticeSecs: 60,
|
|
@@ -1582,6 +1610,8 @@ function loadConfig() {
|
|
|
1582
1610
|
throw new Error(`[pet].open must be "tab", "app", or "helm" in ${configPath()}`);
|
|
1583
1611
|
const watch = { ...DEFAULT_WATCH, ...raw.watch ?? {} };
|
|
1584
1612
|
const helm = { ...DEFAULT_HELM, ...raw.helm ?? {} };
|
|
1613
|
+
if (helm.chat !== "full" && helm.chat !== "brief")
|
|
1614
|
+
throw new Error('[helm].chat must be "full" or "brief"');
|
|
1585
1615
|
const wait = { ...DEFAULT_WAIT, ...raw.wait ?? {} };
|
|
1586
1616
|
for (const key of ["baseTimeoutSecs", "baseRepeats", "maxTimeoutSecs"]) {
|
|
1587
1617
|
if (typeof wait[key] !== "number" || !Number.isSafeInteger(wait[key]) || wait[key] <= 0)
|
|
@@ -1667,7 +1697,7 @@ function loadConfig() {
|
|
|
1667
1697
|
hooks: parseHooks(raw.hooks),
|
|
1668
1698
|
remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0,
|
|
1669
1699
|
readySettleSecs,
|
|
1670
|
-
attentionKinds: parseAttentionKinds(raw.attentionKinds),
|
|
1700
|
+
attentionKinds: parseAttentionKinds(raw.attentionKinds ?? (raw.reviews?.enabled ? [...DEFAULT_ATTENTION_KINDS, "review"] : void 0)),
|
|
1671
1701
|
reviews: withConfigPath(() => parseReviews(raw.reviews, reposRaw)),
|
|
1672
1702
|
permissions: withConfigPath(() => parsePermissions(raw.permissions))
|
|
1673
1703
|
};
|
|
@@ -2390,6 +2420,8 @@ function codexDesktopThread(threadId, home = codexHome()) {
|
|
|
2390
2420
|
} catch {
|
|
2391
2421
|
return void 0;
|
|
2392
2422
|
}
|
|
2423
|
+
if (/"source"\s*:\s*"vscode"/.test(head))
|
|
2424
|
+
return "VS Code extension";
|
|
2393
2425
|
const originator = /"originator"\s*:\s*"([^"]*)"/.exec(head)?.[1];
|
|
2394
2426
|
return originator && /desktop/i.test(originator) ? originator : void 0;
|
|
2395
2427
|
}
|
package/docs/configuration.md
CHANGED
|
@@ -157,6 +157,7 @@ send a continuation.
|
|
|
157
157
|
|
|
158
158
|
| Key | Default | Meaning |
|
|
159
159
|
|---|---|---|
|
|
160
|
+
| `codexStartSecs` | `600` | Seconds a Codex throw waits for sign-on and first park. Positive whole number; `man throw --timeout` overrides it. Other harnesses default to 180 seconds. A Codex timeout keeps its ticket valid for late sign-on and fences a duplicate launch; `stow --wt <trap>` withdraws it before retrying. |
|
|
160
161
|
| `deferSecs` | `90` | A soaking session whose park heartbeat is this fresh holds unaddressed matching bait — the daemon waits instead of spawning. Addressed bait (`--for session:<id>`) waits regardless, until the registration is gone. |
|
|
161
162
|
| `claimIdleNoticeSecs` | `180` | Grace period after a trap claims a dispatch before the daemon raises a `trap-claim-idle` notice if the worker has not reported. Fresh park or tool heartbeats do not acknowledge delivery. The notice does not release the claim; the original brief is re-delivered at the trap's next park, including after it resumes under a new session id. |
|
|
162
163
|
| `acceptWharfStarts` | `false` | Opt this boat into helm-authorized trap start requests from the hosted glass. The daemon starts only its configured harness in a configured repo, refuses unknown repos, and never starts an expired request. Manual hosted `soak` and `man throw --new --repo` also use the daemon broker; traps receive only dispatch-scoped tokens. |
|
|
@@ -178,6 +179,7 @@ send a continuation.
|
|
|
178
179
|
| `idleWorkingNoticeSecs` | `60` | Explicitly idle trap whose last report is working: wake the helm with its full note. A live session-owned background wait exempts it. Tool activity or a new report clears it; reminders use the same backoff. `0` disables. |
|
|
179
180
|
| `armGraceSecs` | `5` | Arm mode: when work is in flight and no live watcher is registered, the Stop hook polls this long for one before blocking — a `man wait` (or `soak --wait`) backgrounded just before the turn ended is usually still starting. A stale registration gets the same window. |
|
|
180
181
|
| `todoStaleDays` | `3` | Open helm todos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
|
|
182
|
+
| `chat` | `"full"` | Default chat detail: `"full"` or `"brief"`. Brief mode points at cards instead of repeating detail and keeps routine wakes quiet. `lobstah man chat brief\|full [--grounds <name>]` or glass Settings overrides it for that grounds' signed-on helm, effective next turn, without a restart or config edit. The override stays with the seat on re-sign/takeover and ends when relieved. |
|
|
181
183
|
|
|
182
184
|
## `[wait]` — quiet helm and trap waiters
|
|
183
185
|
|
|
@@ -189,7 +191,7 @@ send a continuation.
|
|
|
189
191
|
|
|
190
192
|
The defaults wait 900, 900, 900, 1800, 3600, 7200, then 14400 seconds.
|
|
191
193
|
History is stored per session across re-arms. An event or user prompt resets
|
|
192
|
-
that session;
|
|
194
|
+
that session; routine writes and unchanged reminders do not. A prompt the
|
|
193
195
|
harness injects when a background task finishes (a `<task-notification>`,
|
|
194
196
|
which is how a backgrounded `man wait` or `soak --wait` ending quietly comes
|
|
195
197
|
back) is not a user prompt and does not reset. Already-armed
|
|
@@ -326,6 +328,7 @@ outside `~/.lobstah/worktrees`: `lobstah cull`, the retention cull,
|
|
|
326
328
|
| Key | Default | Meaning |
|
|
327
329
|
|---|---|---|
|
|
328
330
|
| `pollSecs` | `45` | Poll cadence. Outbound only — no webhooks, ever. |
|
|
331
|
+
| `watches` | off for reviews-only; on otherwise | Poll registered watches and their follow-up jobs. Reviews-only setups do not start unrelated watch work; explicit `true` opts in. |
|
|
329
332
|
| `liveComment` | `true` | Keep one editable, marked status comment per dispatch. Routine edits are capped at once per minute; human-needed and terminal transitions still post a fresh notification comment. Falls back to transition comments if editing is unavailable. |
|
|
330
333
|
| `pools` | `[]` | Pool names (`["codeclaw"]`). An issue dispatch for repo R runs in the first listed `[pools.<name>]` whose `repo` is R. Review rounds are follow-ups and keep their chain's worktree rule. |
|
|
331
334
|
|
|
@@ -356,18 +359,20 @@ secret:
|
|
|
356
359
|
Two modes. **Single-repo**: name the forge repo explicitly. **Multi-repo**:
|
|
357
360
|
omit `repo`/`key` and the `[repos.*]` table becomes the source of truth —
|
|
358
361
|
every repo with `pickup = true` and a GitHub `origin` is polled, its lobstah
|
|
359
|
-
key reused as the routing key. Opt-in is per repo, never implied.
|
|
362
|
+
key reused as the routing key. Opt-in is per repo, never implied. With no repo opted in, the identity/token can still serve reviews; no tracker pickup runs.
|
|
360
363
|
|
|
361
364
|
| Key | Default | Meaning |
|
|
362
365
|
|---|---|---|
|
|
366
|
+
| `publish` | `false` (`true` for auto-review) | The glass draft/publish toggle, including on-demand jobs. Switching it changes auto-draft ↔ auto-review. Each job remembers whether publishing was enabled when it started. |
|
|
363
367
|
| `identity` | required | The bot login work is assigned to / authored by. |
|
|
364
368
|
| `repo` | single-repo mode | `owner/name`. Omit for multi-repo mode. |
|
|
365
369
|
| `key` | single-repo mode | Lobstah repo key for dispatches and rebase chores. |
|
|
366
370
|
| `startLabel` | `lobstah` | Label + assignee + open = pickup. |
|
|
367
371
|
| `claimedLabel` | `lobstah:claimed` | Applied on claim. |
|
|
372
|
+
| `issues`, `feedback` | explicit opt-ins | Enable issue or PR-feedback pickup independently. Setting either makes unspecified loops off. Legacy configs with neither retain both loops on, with a doctor/pre-install warning. `prFeedback` remains an alias for `feedback`. |
|
|
368
373
|
|
|
369
374
|
`[pickup.github.overrides.<key>]` — multi-repo per-repo overrides:
|
|
370
|
-
`startLabel`, `claimedLabel`, and a nested `merge` table layered over
|
|
375
|
+
`startLabel`, `claimedLabel`, `issues`, `feedback`, and a nested `merge` table layered over
|
|
371
376
|
`[pickup.github.merge]`.
|
|
372
377
|
|
|
373
378
|
### `[pickup.github.merge]` — off by default
|
|
@@ -385,25 +390,29 @@ See [pickup.md](pickup.md) for the loop semantics these keys drive.
|
|
|
385
390
|
|
|
386
391
|
## `[reviews]` — review requests (`lobstah pick`), off by default
|
|
387
392
|
|
|
388
|
-
|
|
393
|
+
Run `lobstah setup reviews` (optional `--identity <login>`) to derive the GitHub login, write a self-contained notify configuration, enable review notifications, and install pick. It refuses to install reviews-only polling while issue/feedback pickup is also enabled.
|
|
394
|
+
|
|
395
|
+
When someone asks `[reviews].identity` for a review, `lobstah pick`
|
|
389
396
|
files a review item ([pickup.md](pickup.md), "Review requests"). It searches
|
|
390
|
-
as that identity, with its token.
|
|
391
|
-
`maxPerDay` can be overridden per repo under `[repos.<key>.reviews]`.
|
|
397
|
+
as that identity, with its token source, independently of `[pickup.github]`. Identity defaults to `gh api user`; the token source defaults to `gh auth token`. Existing pickup credentials remain a fallback. Mode, publish, cost bounds, and skip rules can be overridden per repo under `[repos.<key>.reviews]`; those overrides win over `[reviews]`. The glass repo filter scopes the mode switch and Publish toggle to that repo; All repos edits the global default. `lobstah doctor` shows each repo’s effective mode before pick is installed.
|
|
392
398
|
|
|
393
399
|
| Key | Default | Meaning |
|
|
394
400
|
|---|---|---|
|
|
395
401
|
| `enabled` | `false` | Opt-in. Off means no search call at all. |
|
|
396
402
|
| `repos` | `"configured"` | `"configured"`: only PRs in a `[repos.*]` origin. `"any"`: every repo the token can see. |
|
|
397
|
-
| `
|
|
398
|
-
| `
|
|
403
|
+
| `mode` | `"notify"` | `"notify"`: silent requests in Reviews; `"on-demand"`: only the glass Review action starts a round; `"auto-draft"`: new requests get trap drafts staged pending; `"auto-review"`: new requests get drafts published as REQUEST_CHANGES with blockers, COMMENT otherwise; approve verdicts wait for a click. |
|
|
404
|
+
| `publish` | `false` (`true` for auto-review) | The glass draft/publish toggle, including on-demand jobs. Switching it changes auto-draft ↔ auto-review. Each job remembers whether publishing was enabled when it started. |
|
|
405
|
+
| `identity` | `gh api user` | The reviewer login. |
|
|
406
|
+
| `tokenCommand`, `tokenFile`, `tokenEnv` | `gh auth token` | Token sources, using the same precedence as pickup. |
|
|
407
|
+
| `work` | legacy | `"off"` maps to on-demand, `"trap"`/`"headless"` map to auto-draft; explicit mode wins. The worker choice still applies to automatic jobs. |
|
|
408
|
+
| `post` | legacy | `"draft"` stages pending; `"auto"` maps to auto-review. Explicit mode/publish wins. Automatic publishing uses REQUEST_CHANGES for blockers or COMMENT; APPROVE requires a click in the glass. All publishing refuses stale drafts. |
|
|
399
409
|
| `harness`, `model`, `effort` | repo, then `[harness]` | The review job's worker. |
|
|
400
410
|
| `wallClockSecs`, `maxTurns`, `maxBudgetUsd` | `900`, `40`, unset | Cost bounds for one review job. |
|
|
401
411
|
| `trapWaitSecs` | `600` | With `work = "trap"`: how long a job waits for a free trap. |
|
|
402
412
|
| `maxPerDay` | `20` | Review jobs started per day. Past it, items file with no job. |
|
|
403
413
|
| `skipAuthors`, `skipLabels` | `[]` | Requests on PRs by these authors or with these labels file an item but start no job. |
|
|
404
414
|
|
|
405
|
-
|
|
406
|
-
let review items walk in `man tend`, the glass, and the pet.
|
|
415
|
+
Requests land silently in the Reviews inbox with a tab count, never on deck or tend. Draft-ready and automatic-published notifications use `[hooks.notify]` and the pet, with a `#review-<encoded key>` link to the row. The hook gets `LOBSTAH_NOTE`, `LOBSTAH_VERB` (`draft-ready`, `needs-you`, `published`) and `LOBSTAH_URL` / `LOBSTAH_GLASS_URL`. Opening marks seen; a row action clears the notification and needs-you marker. Wharf notification delivery is deferred.
|
|
407
416
|
|
|
408
417
|
## `[permissions]` — the Claude Code auto-mode profile
|
|
409
418
|
|
package/docs/harness/codex.md
CHANGED
|
@@ -28,6 +28,47 @@ the CLI: plugin 0.5.10 goes with `lobstah` 0.5.10. After every
|
|
|
28
28
|
`lobstah doctor` shows a `plugin codex` row, and the session-start brief
|
|
29
29
|
says when the plugin is behind.
|
|
30
30
|
|
|
31
|
+
## Thrown trap startup
|
|
32
|
+
|
|
33
|
+
Codex 0.160.1 blocks at **Hooks need review** before the first model turn
|
|
34
|
+
when any hook definition is new or changed. A longer throw timeout cannot
|
|
35
|
+
clear that picker. `man throw` supplies invocation-scoped `hooks.state`
|
|
36
|
+
hashes for the installed plugin's six exact `lobstah hook <event>` commands.
|
|
37
|
+
Thrown sessions also set `check_for_update_on_startup=false` for that
|
|
38
|
+
invocation, so an interactive update picker cannot hold the launch.
|
|
39
|
+
The launcher rejects a plugin definition containing another command; it
|
|
40
|
+
never uses `--dangerously-bypass-hook-trust`, edits saved trust, enables a
|
|
41
|
+
disabled hook, or approves repo/user/other-plugin hooks. Those still require
|
|
42
|
+
their normal review. Manually launched Codex sessions still use `/hooks`.
|
|
43
|
+
|
|
44
|
+
In 0.160.1, linked worktrees inherit project trust and hook declarations
|
|
45
|
+
from their primary checkout, including the primary hook source path. They
|
|
46
|
+
do not need blanket trust for `~/.codex/worktrees` or `~/.lobstah/worktrees`.
|
|
47
|
+
An untrusted primary project still needs its normal folder trust decision.
|
|
48
|
+
Auto-mode launches add only lobstah's home, ume's home (`UME_HOME`, otherwise
|
|
49
|
+
`~/.ume`), and the repository's git common directory as extra writable roots.
|
|
50
|
+
This lets ume write its push ledger without granting the rest of the home
|
|
51
|
+
directory.
|
|
52
|
+
`doctor` checks the additional `UserPromptSubmit` and `PermissionRequest`
|
|
53
|
+
hooks when declared; either can block startup even when the four lifecycle
|
|
54
|
+
hooks are already trusted. Its trust status reads saved configuration; the
|
|
55
|
+
throw's invocation overrides do not change that saved status.
|
|
56
|
+
|
|
57
|
+
Verified against the [0.160.1 startup review](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/tui/src/startup_hooks_review.rs),
|
|
58
|
+
[worktree config loader](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/config/src/loader/mod.rs),
|
|
59
|
+
and [hook-state merge](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/hooks/src/config_rules.rs).
|
|
60
|
+
|
|
61
|
+
### Resume folder selection
|
|
62
|
+
|
|
63
|
+
Codex 0.160.1 shows **Working directory · resume** when the saved session cwd
|
|
64
|
+
and current launch cwd differ. Starting the process with a shell `cd` does
|
|
65
|
+
not answer that picker. Each generated Codex command now also passes
|
|
66
|
+
`--cd <launch-directory>`; returning traps always choose their own worktree,
|
|
67
|
+
even when their session history began in the primary checkout. This selects
|
|
68
|
+
the current directory for that invocation without saving a global preference.
|
|
69
|
+
New traps still start in the primary checkout, where their first `soak`
|
|
70
|
+
creates and enters the worktree.
|
|
71
|
+
|
|
31
72
|
## What the plugin adds
|
|
32
73
|
|
|
33
74
|
| Piece | What it does |
|
package/docs/man.md
CHANGED
|
@@ -943,6 +943,17 @@ gates the digest above.
|
|
|
943
943
|
The lobstah man skill prints the glass URL. `[glass].port` sets the port;
|
|
944
944
|
`LOBSTAH_GLASS_PORT` takes precedence.
|
|
945
945
|
|
|
946
|
+
**Compare chat detail at runtime.** `lobstah man chat brief` asks the helm to
|
|
947
|
+
point at a card in one line when it already carries the detail, keep wakes
|
|
948
|
+
with nothing new quiet, and answer direct questions directly. `lobstah man
|
|
949
|
+
chat full` restores normal output. Use `--grounds <name>` when needed. A
|
|
950
|
+
person at a terminal or that grounds' helm may toggle it; glass Settings
|
|
951
|
+
has the same switch per helm. `man tend` and the glass helm chip show the
|
|
952
|
+
current mode. The seat stores the override through re-sign and takeover;
|
|
953
|
+
relieving removes it. `[helm].chat` supplies the default (`"full"`). The
|
|
954
|
+
next prompt, `man wait`, or Stop-hook wake carries the change, including
|
|
955
|
+
a one-time full-mode notice to retire an earlier brief instruction.
|
|
956
|
+
|
|
946
957
|
**One helm per grounds, enforced.** A **grounds** is a named territory: the
|
|
947
958
|
subset of configured repos one orchestrator oversees (`[grounds.*]`; with
|
|
948
959
|
none configured, one implicit `home` grounds covers every repo). A repo
|
|
@@ -1185,7 +1196,8 @@ lobstah stow --wt amber-gull # withdraw a reservation no session has
|
|
|
1185
1196
|
|
|
1186
1197
|
`man throw --new` (the helm's) picks a two-word name and a `wt:` id for each
|
|
1187
1198
|
fresh trap before any session exists and writes a **starting** reservation
|
|
1188
|
-
(`soaking/<id>.starting`) with a deadline (`--timeout
|
|
1199
|
+
(`soaking/<id>.starting`) with a deadline (`--timeout`; Codex defaults to
|
|
1200
|
+
`[soak].codexStartSecs`, 600 seconds, and other harnesses to 180 seconds).
|
|
1189
1201
|
`dispatch --for <name>` works on it at once: the work waits, as it does for
|
|
1190
1202
|
any addressed trap. `man tend` and the glass show the trap as `starting`.
|
|
1191
1203
|
|
|
@@ -1196,7 +1208,7 @@ command in a new tab in the repo's primary checkout:
|
|
|
1196
1208
|
|
|
1197
1209
|
```bash
|
|
1198
1210
|
cd <repo> && CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 claude '/lobstah:trap soak --ticket <ticket>'
|
|
1199
|
-
cd <repo> && codex '$lobstah:trap soak --ticket <ticket>'
|
|
1211
|
+
cd <repo> && codex -c 'tui.terminal_title=[]' '$lobstah:trap soak --ticket <ticket>'
|
|
1200
1212
|
```
|
|
1201
1213
|
|
|
1202
1214
|
The session's soak redeems the ticket, from `--ticket` or from the
|
|
@@ -1207,9 +1219,11 @@ reservation. The ticket then redeems nothing. A spent ticket left in
|
|
|
1207
1219
|
the session that redeemed it. A session that already mans a trap cannot
|
|
1208
1220
|
redeem a ticket.
|
|
1209
1221
|
|
|
1210
|
-
A throw that sees no sign-on by its deadline
|
|
1211
|
-
|
|
1212
|
-
|
|
1222
|
+
A Codex throw that sees no sign-on by its deadline keeps its ticket valid
|
|
1223
|
+
and fences a second launch. Check its terminal or withdraw it before retrying.
|
|
1224
|
+
Other harnesses withdraw the reservation and post `trap-start-failed`. The
|
|
1225
|
+
daemon marks an unredeemed reservation past its deadline as **failed**
|
|
1226
|
+
while retaining its ticket for late sign-on: the glass
|
|
1213
1227
|
shows the trap as `start failed` with the reason, and work addressed to it
|
|
1214
1228
|
stays queued. `lobstah stow --wt <name>` withdraws a reservation; its
|
|
1215
1229
|
addressed work is then orphaned bait and the helm gets a `bait-orphaned`
|
|
@@ -1325,9 +1339,11 @@ launched twice. Otherwise:
|
|
|
1325
1339
|
prompt redeems the ticket, so the session signs on as the same trap.
|
|
1326
1340
|
Every start names its permission mode (see **Permission mode** below).
|
|
1327
1341
|
4. It returns when the trap has signed on and parked, and prints whether it
|
|
1328
|
-
resumed or started cold, and why.
|
|
1329
|
-
|
|
1330
|
-
|
|
1342
|
+
resumed or started cold, and why. Codex uses `[soak].codexStartSecs`
|
|
1343
|
+
(default 600 seconds); other harnesses use 180 seconds. `--timeout`
|
|
1344
|
+
overrides either. A Codex timeout keeps its ticket and reservation for
|
|
1345
|
+
late sign-on; other harnesses withdraw the reservation and post
|
|
1346
|
+
`trap-start-failed`. Late first park announces the trap as available.
|
|
1331
1347
|
|
|
1332
1348
|
**Permission mode.** A thrown trap starts in auto mode, cold or resumed,
|
|
1333
1349
|
fresh or rostered:
|
|
@@ -1376,7 +1392,8 @@ so a live Codex trap shows the mode its throw started it in.
|
|
|
1376
1392
|
(`--grounds`, else the caller's helm grounds, else every repo); `--repo`
|
|
1377
1393
|
narrows to one repo; `--new --count N` starts N fresh ones. Every launch runs
|
|
1378
1394
|
at once, with no limit, and the batch waits for all of them. It prints one
|
|
1379
|
-
row per trap: `resumed`, `cold`, or `new` (with why), `
|
|
1395
|
+
row per trap: `resumed`, `cold`, or `new` (with why), `starting` (a Codex
|
|
1396
|
+
timeout still awaiting sign-on or first park), `skipped` (live,
|
|
1380
1397
|
starting, or unresolved, with why), or `failed` (with why). One trap failing
|
|
1381
1398
|
does not stop the others, and the command exits 1 when any failed.
|
|
1382
1399
|
|
|
@@ -1385,8 +1402,9 @@ trap is listening. Its reservation (`trap-starting`), sign-on
|
|
|
1385
1402
|
(`trap-signed-on`), and sign-off (`trap-stowed`) are quiet: tend, the
|
|
1386
1403
|
digest's `traps` table, and the glass show them. A ghost sweep of an idle
|
|
1387
1404
|
trap is quiet the same way; a ghost sweep of a trap that held a catch wakes.
|
|
1388
|
-
|
|
1389
|
-
posts one `trap-batch` notice with the counts and the
|
|
1405
|
+
Timely arrivals in a batch post no individual `trap-available`: when every
|
|
1406
|
+
throw has settled it posts one `trap-batch` notice with the counts and the
|
|
1407
|
+
names that failed. A late first park posts its own `trap-available`. A
|
|
1390
1408
|
trap that failed to start (`trap-start-failed`) and work addressed to a trap
|
|
1391
1409
|
that is gone (`bait-orphaned`) still wake.
|
|
1392
1410
|
|
package/docs/pickup.md
CHANGED
|
@@ -270,15 +270,15 @@ When the search stops returning a PR (the request was withdrawn, the
|
|
|
270
270
|
person reviewed it on GitHub, or the PR closed), its open round is `withdrawn`. A
|
|
271
271
|
truncated search (more than 50 results) withdraws nothing.
|
|
272
272
|
|
|
273
|
-
**Drafting.**
|
|
274
|
-
a configured repo
|
|
273
|
+
**Drafting.** `[reviews].mode = "notify"` starts no jobs. `"on-demand"` enables the glass Review action for requested, stale, or failed rounds and starts nothing automatically. `"auto-draft"` and `"auto-review"` start a review job for each requested round in
|
|
274
|
+
a configured repo: a chore-lane dispatch with the
|
|
275
275
|
`prReview` brief, `readOnly` (the runner pushes nothing, opens no PR, and
|
|
276
276
|
checkpoints nothing), and the `[reviews]` cost bounds. With `work = "trap"`
|
|
277
277
|
the job waits `trapWaitSecs` for a free trap of the repo, then pick hands it
|
|
278
278
|
to the daemon. The job reads the PR with `gh`, makes any checkout it needs
|
|
279
279
|
as a detached worktree of `pull/<n>/head` at the fixed path
|
|
280
|
-
`rounds/<round id>/checkout`, and writes `review.md` (the summary)
|
|
281
|
-
`comments.json` (inline comments: `path`, `line`, `side`, `body`) into the
|
|
280
|
+
`rounds/<round id>/checkout`, and writes `review.md` (the summary),
|
|
281
|
+
`comments.json` (inline comments: `path`, `line`, `side`, `body`), and `verdict.json` (`verdict`: `approve`, `comment`, or `request_changes`; `blocking`: findings with `path`, positive `line`, and `body`) into the
|
|
282
282
|
round's directory, `rounds/<round id>/`. Whenever the round's job ends
|
|
283
283
|
(drafted, stale, failed, or withdrawn and its job cancelled, a re-request
|
|
284
284
|
included), pick removes that checkout: `git worktree remove --force`, then
|
|
@@ -293,7 +293,7 @@ outside the configured repos, or `maxPerDay` jobs already started today
|
|
|
293
293
|
(UTC) leave the round `requested` with the reason. `lobstah reviews redraft
|
|
294
294
|
<key>` drafts a stale or failed round again at the current head.
|
|
295
295
|
|
|
296
|
-
**Staging and posting.** With `
|
|
296
|
+
**Staging and posting.** With `mode = "auto-draft"` or `publish = false` for an on-demand job, a
|
|
297
297
|
fresh draft is staged on the PR as the identity's **pending review**:
|
|
298
298
|
`POST /repos/{o}/{r}/pulls/{n}/reviews` with no event, `commit_id` set to the
|
|
299
299
|
head the draft reviewed, the inline comments, and a body ending with
|
|
@@ -304,12 +304,8 @@ sends it, with whatever event they choose. When the request then disappears from
|
|
|
304
304
|
search, pick reads that review once: submitted marks the round `posted` (by
|
|
305
305
|
`review tool`), deleted dismisses it, still pending withdraws it.
|
|
306
306
|
|
|
307
|
-
With `"auto"
|
|
308
|
-
(
|
|
309
|
-
comment-only review too. Neither path takes an event argument, so lobstah
|
|
310
|
-
itself never approves or requests changes. A stale draft is never staged or
|
|
311
|
-
posted on its own, and posts by hand only with `--stale`, which adds a line
|
|
312
|
-
saying the PR has moved. Each round is staged at most once and posted at
|
|
307
|
+
With `mode = "auto-review"` (also legacy `post = "auto"`), pick publishes fresh drafts as REQUEST_CHANGES when there are blocking findings, otherwise COMMENT. An approve verdict is staged pending with a needs-you marker and always waits for the person’s Approve click; approval is never automatic. The glass Publish toggle selects draft or publish, including for on-demand jobs; the row action reads Review (draft) or Review (publish). The repo filter scopes both settings to `[repos.<key>.reviews]`, otherwise they change the global `[reviews]` default. Jobs started with publishing off stay draft-only even if the toggle changes later. Manual drafting respects `maxPerDay`, including retries of the same round. `lobstah reviews post <key>` explicitly sends a staged review as a
|
|
308
|
+
comment review. The glass shows Approve, Request changes, or Publish comment according to the verdict; Approve posts APPROVE with the summary as the identity, only on the person’s explicit click. The glass shows requester names/avatars cached from the same authenticated search; workflow requests show the PR author with an automatic badge. Cards and rows open the configured review tool; drafted rounds link to their pending review. Skip (formerly Dismiss) means “Handle it yourself; removes lobstah’s draft”: it deletes any staged pending review without declining the request on GitHub. Redraft starts a stale round again. Every row action acknowledges and clears its notification and needs-you marker; opening a row only marks it seen and dims it. A stale draft is never staged or posted, including by hand. Publishing checks the live PR head immediately before submission; a changed or closed PR requires a new draft. Each round is staged at most once and posted at
|
|
313
309
|
most once: `staged.json` and `posted.json` in the round's directory are
|
|
314
310
|
created with `wx` before the call and removed if it fails, and a review on
|
|
315
311
|
the PR that already carries the round's marker is adopted (pending) or
|
|
@@ -330,9 +326,7 @@ pending draft with its own token and marks the request done or refused. The
|
|
|
330
326
|
wharf never calls GitHub.
|
|
331
327
|
|
|
332
328
|
Round states: `requested`, `drafting`, `drafted`, `stale`, `failed`,
|
|
333
|
-
`posted`, `dismissed`, `withdrawn`. The `review`
|
|
334
|
-
the newest round is `drafted`, `stale`, `failed`, or `requested` with no job
|
|
335
|
-
to draft it. `lobstah reviews` lists open items; `--all` adds the rest.
|
|
329
|
+
`posted`, `dismissed`, `withdrawn`. The Reviews tab is the inbox; it shows a count, and no review cards appear on deck or tend. Requests are silent. Only a completed draft (“Draft ready: #7 · request changes · 2 blocking”), an approve verdict needing the person, or an automatically published review notifies through `[hooks.notify]` and the pet. Notifications deep-link to the Reviews row; wharf notification delivery comes later. Generic review-job done notifications are suppressed to avoid duplicates. `lobstah reviews` lists open items; `--all` adds the rest.
|
|
336
330
|
|
|
337
331
|
## Merge loop
|
|
338
332
|
|
package/docs/vocabulary.md
CHANGED
|
@@ -305,7 +305,8 @@ prints one `hooks claude` and one `hooks codex` row for each harness whose
|
|
|
305
305
|
lobstah plugin is installed (`skip` otherwise). The row starts with the
|
|
306
306
|
readiness of each role: the helm needs `Stop` and `SessionStart`; a trap
|
|
307
307
|
needs all four (`helm ready, trap not ready (needs PostToolUse)`). Then, for
|
|
308
|
-
each hook (`Stop`, `SessionStart`, `PostToolUse`, `SessionEnd`),
|
|
308
|
+
each lifecycle hook (`Stop`, `SessionStart`, `PostToolUse`, `SessionEnd`),
|
|
309
|
+
plus Codex's `UserPromptSubmit` and `PermissionRequest` when declared, it says:
|
|
309
310
|
|
|
310
311
|
- **installed**: the plugin's `hooks/hooks.json` declares it (`missing`
|
|
311
312
|
otherwise), and whether the harness has it turned off (`installed but
|
|
@@ -482,7 +483,7 @@ worktree is refused (the session lock); a stale one is adopted.
|
|
|
482
483
|
| beat | `lobstah soak beat` (`lobstah hook post-tool-use`), run by the plugin's post-tool hook after every tool call. It resolves the trap from the working directory, else from the session id (files only: no git, no network), refreshes the trap's beat (`soaking/<trap>.beat`, separate from the registration), and writes the claimed catch's [activity](#activity). Throttled to one per 30 seconds per trap. Inert in a session that is not soaking, or with `[soak].beat = false`. Always exits 0; errors go to `logs/beat.log`. |
|
|
483
484
|
| ghost trap | A registration whose heartbeat **and** beat lapsed past `[soak].ttlSecs` **after having parked at least once**. The sweep removes the registration, requeues only unfinished catches, finalizes done/failed in `done/`, and posts a `trap-ghosted` notice: quiet (digest and glass only) for an idle trap, a wake for one that held a catch. It removes a soak-created checkout only when clean and pushed to its upstream; dirty, unpushed, no-upstream, or unreadable checkouts stay, protected from later culls too. The notice includes path, branch, modified-file and unpushed-commit counts, or `unknown` when unavailable. A kept anchor preserves the address on re-soaking. A fresh report or beat keeps a working session out of the sweep; a fresh beat also holds the session lock. A catch whose last report is `paused` keeps its trap until the pause expires ([Waiting on](#waiting-on)). A daemon tick gap longer than the soak TTL starts one full TTL of resume grace before any ghost sweep. |
|
|
484
485
|
| defective enlistment | A stale registration that **never parked** — signed on but never listened (usually no Stop hook). Not swept: the helm gets a `trap-defective` notice with the remedy (`soak --wait`), and the registration stays so the address keeps protecting its work. |
|
|
485
|
-
| reserved trap | A trap `man throw` reserved before its session signs on: a name, a `wt:` id, and a one-time ticket, shown as `starting`. `man throw --new` reserves a fresh id and name; `man throw <name>` reserves an existing roster trap under its own id and name, in its own worktree (the reservation records the worktree). A trap has at most one reservation, so a second throw refuses. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. A throw
|
|
486
|
+
| reserved trap | A trap `man throw` reserved before its session signs on: a name, a `wt:` id, and a one-time ticket, shown as `starting`. `man throw --new` reserves a fresh id and name; `man throw <name>` reserves an existing roster trap under its own id and name, in its own worktree (the reservation records the worktree). A trap has at most one reservation, so a second throw refuses. Work addressed to it waits. A session redeems the ticket with `soak --ticket` (or `LOBSTAH_TRAP_TICKET`) and signs on as that trap. A Codex throw timeout retains its ticket and reservation for late sign-on; other harnesses withdraw it; one found unredeemed past its deadline fails with a `trap-start-failed` notice and its work stays queued. `stow --wt <name>` withdraws it. A reservation made by a batch throw records the batch, and so does the registration its sign-on makes. |
|
|
486
487
|
| trap roster | One durable record per trap that ever signed on (`~/.lobstah/roster/<trapId>.json`): canonical name, repo and its git common directory, worktree, soak branch, last branch and HEAD, harness, session, the registration's model and config, window and link (navigation hints only), state (`live`, `stowed`, `ghosted`), when and why it left, its last catch, and a saved profile (harness, model, config, terminal) set with `man roster set`. Sign-on writes it; stow and the ghost sweep update it before the registration goes. Stow, the end of the sign-off grace, a ghost sweep, and `cull` never remove it. The roster's name is the trap's name: a trap that signs on again keeps it. A roster record never makes a trap live or claimable. `man roster` lists it; `man throw` reads it; `man roster forget` removes it. |
|
|
487
488
|
| protected ref | `refs/lobstah/traps/<trapId>` in the trap's repository: the trap's last HEAD, written at sign-on and before stow, a ghost sweep, or `cull` removes the checkout. It is not a branch, so worktree removal and branch cleanup leave it and its commit in place. A missing checkout is recreated from it. A trap checkout whose revision cannot be written there is not removed by a ghost sweep or cull. |
|
|
488
489
|
| trap request | A trap the human asked for from the glass's **+ New trap** button: a `trap-request` request in `requests/<id>.json` with a repo and a harness. It wakes the helm as a `trap-request` event; the helm starts it with `man throw --new --request <id>`, which takes the request's repo and harness and closes it. |
|
|
@@ -515,9 +516,9 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
|
|
|
515
516
|
| `helm` | Sign a session on as the orchestrator for one grounds. Prints the charter and enables the Stop hook without a marker file. Re-running from the same session is an idempotent re-sign. |
|
|
516
517
|
| watcher registration | `~/.lobstah/watchers/<session-id>.json` stores a `man wait` or `soak --wait` process's PID and heartbeat. The waiter refreshes it while running and removes it on exit; a heartbeat older than five seconds is stale, and a second waiter for the same session refuses. |
|
|
517
518
|
| `man throw --dry-run` | What a throw would do for each selected trap (`--plan` is the same), read from the [trap roster](#soaking-contract): `resume` the saved session, `cold` (a new session under the same name, id, and checkout; the row says why: no saved history, an app session, a profile that changes harness), `skip` (live or starting), or `unresolved` (repo no longer configured or now another repository, record incomplete, checkout gone with no protected ref, or the path anchors another trap). Names select traps; `--all` selects every eligible trap in the grounds; `--repo` narrows. Each row shows harness, model, config, terminal (and where each came from), checkout (`kept` or `recreate`), revision, and held messages. Read-only: it launches and writes nothing. |
|
|
518
|
-
| `man throw --all \| --repo <key> \| --new [--count N]` | A batch throw (the helm's): every eligible trap in the grounds, one repo's, or N fresh traps from the harness defaults (`--harness`, `--request <id>` for a glass trap request). Every launch runs at once, with no limit. One row per trap: `resumed`, `cold`, `new`, `skipped`, or `failed`, each with why; one failure does not stop the others, and the command exits 1 when any failed. The batch posts one `trap-batch` notice when it settles
|
|
519
|
+
| `man throw --all \| --repo <key> \| --new [--count N]` | A batch throw (the helm's): every eligible trap in the grounds, one repo's, or N fresh traps from the harness defaults (`--harness`, `--request <id>` for a glass trap request). Every launch runs at once, with no limit. One row per trap: `resumed`, `cold`, `new`, `starting` (Codex timed out but may still arrive), `skipped`, or `failed`, each with why; one failure does not stop the others, and the command exits 1 when any failed. The batch posts one `trap-batch` notice when it settles, suppressing per-trap `trap-available` for timely arrivals. A late first park announces availability separately. `--dry-run` (or `--plan`) shows the plan and launches nothing. |
|
|
519
520
|
| `man roster forget <name>` | Remove a stowed trap for good (the helm's): its worktree (one soak did not create stays, minus its anchor), its protected ref, its roster record, its held messages (bounced), and its name. Refuses a live or starting trap, and refuses, naming the work, when its checkout has unsaved files or its commits are on no remote branch and not merged to trunk; `--force` forgets anyway, keeping a branch that still holds such commits. |
|
|
520
|
-
| `man throw <name>` | Bring one roster trap back and wait until it listens. The helm's. It follows the plan for that trap: a `skip` (live or starting) refuses, which fences a double launch; an `unresolved` refuses with its reason. Otherwise it reserves the trap under its own id and name, recreates a missing checkout from the protected ref on its recorded branch (an existing branch only when it still contains that revision; a kept checkout, dirty or not, is used as is), and opens the start command in the profile's terminal (Terminal.app or iTerm2, macOS): `resume` reopens the saved session from the directory its history is keyed by, `cold` starts a new one in the worktree; the first prompt redeems the ticket. It returns when the trap has signed on under its id and parked, printing which start happened and why.
|
|
521
|
+
| `man throw <name>` | Bring one roster trap back and wait until it listens. The helm's. It follows the plan for that trap: a `skip` (live or starting) refuses, which fences a double launch; an `unresolved` refuses with its reason. Otherwise it reserves the trap under its own id and name, recreates a missing checkout from the protected ref on its recorded branch (an existing branch only when it still contains that revision; a kept checkout, dirty or not, is used as is), and opens the start command in the profile's terminal (Terminal.app or iTerm2, macOS): `resume` reopens the saved session from the directory its history is keyed by, `cold` starts a new one in the worktree; the first prompt redeems the ticket. It returns when the trap has signed on under its id and parked, printing which start happened and why. Codex defaults to `[soak].codexStartSecs` (600 s), others to 180 s; `--timeout` overrides either. A Codex timeout retains its ticket and duplicate-launch fence for late sign-on. Other harnesses withdraw the reservation and post `trap-start-failed`. Batches: see `man throw --all`. |
|
|
521
522
|
| `man roster` | List the trap roster. `man roster set <trap> --harness\|--model\|--terminal <value>\|--config <key>=<value>` saves how a throw starts the trap; `default` (or `key=`) clears a field. |
|
|
522
523
|
| `man haul --park` | Make the Stop hook wait for attention while work is in flight. `[helm].park = "block"` selects the same mode. In arm mode, the hook allows a stop with a live watcher or blocks with the arm command. |
|
|
523
524
|
| `relieve` | Step down. `--take` on another session's `helm` is the only force path: it displaces a live holder deliberately and leaves them a stand-down notice, delivered once at their next park. A holder whose heartbeat lapsed past `[helm].ttlSecs` is stale and claimable without `--take`. |
|
|
@@ -597,3 +598,8 @@ registry that decides what parses).
|
|
|
597
598
|
| `1` | Error: the command was well-formed but could not do its job. |
|
|
598
599
|
| `2` | Usage mistake: unknown command, flag, or subverb. The error names the offender and prints the command's usage card. Flags in a free-text tail (a `send` message, a `report` note) are never validated — prose may contain anything. |
|
|
599
600
|
| `3` | `man wait --timeout` elapsed with nothing to report. Its own code so `while lobstah man wait` loops still terminate on timeout while `2` stays unambiguous. |
|
|
601
|
+
|
|
602
|
+
|
|
603
|
+
### Session grants
|
|
604
|
+
|
|
605
|
+
`lobstah grant request --session <id>` (or `--trap <name>`, `--grounds <name>`) `--tools 'mcp__browser__*' [--hosts a,b] [--for 15m] --reason "why"` asks in glass; it never grants. Chris chooses Allow for the requested duration, Allow for 1h, or Deny. A real terminal can use `lobstah grant --session <id> --tools <name|glob>` with the same options and confirmation. Windows start at approval, default to 15m, and cannot exceed 4h. Bash requires `--command '<prefix>'` and keeps the existing no-joiner/no-redirect rules. URL hosts are pinned exactly when present; URL-less clicks/screenshots ride the session window. Grant/config/settings edits and self-grant commands are excluded. The existing permission card also offers a 15-minute tool-family window for its asking session. `lobstah grants` and the glass show expiry, use count and the latest 20 tool/time/host records (no typed text or URL paths/queries); Revoke takes effect immediately. Hooks request an allow; harness restrictions still apply.
|