lobstah 0.7.7 → 0.7.8

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/runner.js CHANGED
@@ -1173,6 +1173,80 @@ function validReviewTool(value) {
1173
1173
  }
1174
1174
  }
1175
1175
 
1176
+ // packages/core/dist/reviews.js
1177
+ var REVIEW_WORK = ["off", "trap", "headless"];
1178
+ var REVIEW_POST = ["draft", "auto"];
1179
+ var DEFAULT_REVIEWS = {
1180
+ enabled: false,
1181
+ repos: "configured",
1182
+ work: "trap",
1183
+ post: "draft",
1184
+ limits: { wallClockSecs: 900, maxTurns: 40 },
1185
+ trapWaitSecs: 600,
1186
+ maxPerDay: 20,
1187
+ skipAuthors: [],
1188
+ skipLabels: [],
1189
+ perRepo: {}
1190
+ };
1191
+ function oneOf(value, allowed, where) {
1192
+ if (typeof value === "string" && allowed.includes(value))
1193
+ return value;
1194
+ throw new Error(`${where} must be ${allowed.map((a) => `"${a}"`).join(", ")}`);
1195
+ }
1196
+ function nonNegative(value, where) {
1197
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
1198
+ throw new Error(`${where} must be a non-negative number`);
1199
+ return value;
1200
+ }
1201
+ function strings(value, where) {
1202
+ if (!Array.isArray(value))
1203
+ throw new Error(`${where} must be an array of strings`);
1204
+ return value.map(String);
1205
+ }
1206
+ function parseSettings(raw, where) {
1207
+ const out = {};
1208
+ if (raw.work !== void 0)
1209
+ out.work = oneOf(raw.work, REVIEW_WORK, `${where}.work`);
1210
+ if (raw.post !== void 0)
1211
+ out.post = oneOf(raw.post, REVIEW_POST, `${where}.post`);
1212
+ for (const k of ["harness", "model", "effort"])
1213
+ if (raw[k] !== void 0)
1214
+ out[k] = String(raw[k]);
1215
+ const limits = {};
1216
+ for (const k of ["wallClockSecs", "maxTurns", "maxBudgetUsd"])
1217
+ if (raw[k] !== void 0)
1218
+ limits[k] = nonNegative(raw[k], `${where}.${k}`);
1219
+ if (Object.keys(limits).length)
1220
+ out.limits = limits;
1221
+ if (raw.trapWaitSecs !== void 0)
1222
+ out.trapWaitSecs = nonNegative(raw.trapWaitSecs, `${where}.trapWaitSecs`);
1223
+ if (raw.skipAuthors !== void 0)
1224
+ out.skipAuthors = strings(raw.skipAuthors, `${where}.skipAuthors`);
1225
+ if (raw.skipLabels !== void 0)
1226
+ out.skipLabels = strings(raw.skipLabels, `${where}.skipLabels`);
1227
+ return out;
1228
+ }
1229
+ function parseReviews(raw, reposRaw = {}) {
1230
+ const r = raw ?? {};
1231
+ if (typeof r !== "object" || Array.isArray(r))
1232
+ throw new Error("[reviews] must be a table");
1233
+ const base = parseSettings(r, "[reviews]");
1234
+ const perRepo = {};
1235
+ for (const [key, repo] of Object.entries(reposRaw)) {
1236
+ if (repo.reviews !== void 0)
1237
+ perRepo[key] = parseSettings(repo.reviews, `[repos.${key}.reviews]`);
1238
+ }
1239
+ return {
1240
+ ...DEFAULT_REVIEWS,
1241
+ ...base,
1242
+ limits: { ...DEFAULT_REVIEWS.limits, ...base.limits },
1243
+ enabled: r.enabled === void 0 ? false : Boolean(r.enabled),
1244
+ repos: r.repos === void 0 ? "configured" : oneOf(r.repos, ["configured", "any"], "[reviews].repos"),
1245
+ maxPerDay: r.maxPerDay === void 0 ? DEFAULT_REVIEWS.maxPerDay : nonNegative(r.maxPerDay, "[reviews].maxPerDay"),
1246
+ perRepo
1247
+ };
1248
+ }
1249
+
1176
1250
  // packages/core/dist/config.js
1177
1251
  var POOL_NAME = /^[A-Za-z0-9_-]+$/;
1178
1252
  function parsePools(raw, repos) {
@@ -1198,7 +1272,7 @@ function parsePools(raw, repos) {
1198
1272
  }
1199
1273
  return out;
1200
1274
  }
1201
- var BRIEF_KINDS = ["conflict", "checks", "review", "ciFix", "rebase"];
1275
+ var BRIEF_KINDS = ["conflict", "checks", "review", "ciFix", "rebase", "prReview"];
1202
1276
  function parseBriefHooks(raw) {
1203
1277
  if (!raw || typeof raw !== "object" || Array.isArray(raw))
1204
1278
  return void 0;
@@ -1210,7 +1284,44 @@ function parseBriefHooks(raw) {
1210
1284
  }
1211
1285
  return Object.keys(out).length ? out : void 0;
1212
1286
  }
1213
- var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report", "stack-ready"];
1287
+ function refuseMoved(raw, reposRaw) {
1288
+ const moved = [
1289
+ [raw.notifyCommand !== void 0, "notifyCommand moved to [hooks.notify].command"],
1290
+ [raw.notifyVerbs !== void 0, "notifyVerbs moved to [hooks.notify].verbs"],
1291
+ [raw.pickup?.notifyCommand !== void 0, "[pickup].notifyCommand moved to [hooks.pickupNotify].command"],
1292
+ [raw.reviews?.rules !== void 0, "[reviews].rules moved to [hooks.brief].prReview"]
1293
+ ];
1294
+ for (const [key, r] of Object.entries(reposRaw)) {
1295
+ moved.push([r.briefHooks !== void 0, `[repos.${key}.briefHooks] moved to [repos.${key}.hooks.brief]`], [r.review !== void 0, `[repos.${key}].review moved to [repos.${key}].reviewTool`], [r.reviews?.rules !== void 0, `[repos.${key}.reviews].rules moved to [repos.${key}.hooks.brief].prReview`]);
1296
+ }
1297
+ const found = moved.filter(([hit]) => hit).map(([, why]) => why);
1298
+ if (found.length)
1299
+ throw new Error(`${found.join("; ")} (in ${configPath()})`);
1300
+ }
1301
+ function parseHooks(raw) {
1302
+ if (raw === void 0)
1303
+ return { brief: {} };
1304
+ if (!raw || typeof raw !== "object" || Array.isArray(raw))
1305
+ throw new Error(`[hooks] must be a table in ${configPath()}`);
1306
+ const h = raw;
1307
+ const command = (table, where) => {
1308
+ const t = table;
1309
+ if (!t || typeof t !== "object" || typeof t.command !== "string" || !t.command.trim())
1310
+ throw new Error(`${where}.command must be a command line in ${configPath()}`);
1311
+ return t.command;
1312
+ };
1313
+ const out = { brief: parseBriefHooks(h.brief) ?? {} };
1314
+ if (h.notify !== void 0) {
1315
+ const verbs = h.notify.verbs;
1316
+ if (verbs !== void 0 && (!Array.isArray(verbs) || !verbs.every((v) => typeof v === "string")))
1317
+ throw new Error(`[hooks.notify].verbs must be an array of verbs in ${configPath()}`);
1318
+ out.notify = { command: command(h.notify, "[hooks.notify]"), ...verbs ? { verbs } : {} };
1319
+ }
1320
+ if (h.pickupNotify !== void 0)
1321
+ out.pickupNotify = { command: command(h.pickupNotify, "[hooks.pickupNotify]") };
1322
+ return out;
1323
+ }
1324
+ var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report", "stack-ready", "review"];
1214
1325
  var DEFAULT_ATTENTION_KINDS = ["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"];
1215
1326
  function parseAttentionKinds(raw) {
1216
1327
  if (raw === void 0)
@@ -1273,6 +1384,13 @@ var DEFAULT_LIMITS = {
1273
1384
  reuseWorktree: true,
1274
1385
  releaseOnMerge: false
1275
1386
  };
1387
+ function withConfigPath(parse2) {
1388
+ try {
1389
+ return parse2();
1390
+ } catch (err) {
1391
+ throw new Error(`${err instanceof Error ? err.message : String(err)} in ${configPath()}`);
1392
+ }
1393
+ }
1276
1394
  function configPath() {
1277
1395
  return path4.join(lobstahHome(), "config.toml");
1278
1396
  }
@@ -1316,17 +1434,18 @@ function loadConfig() {
1316
1434
  throw new Error(`readySettleSecs must be a non-negative number in ${configPath()}`);
1317
1435
  }
1318
1436
  const reposRaw = raw.repos ?? {};
1437
+ refuseMoved(raw, reposRaw);
1319
1438
  const repos = {};
1320
1439
  for (const [key, r] of Object.entries(reposRaw)) {
1321
1440
  if (r.traps !== void 0 && (typeof r.traps !== "number" || !Number.isSafeInteger(r.traps) || r.traps < 0)) {
1322
1441
  throw new Error(`[repos.${key}].traps must be a non-negative whole number`);
1323
1442
  }
1324
- if (r.review !== void 0 && !validReviewTool(r.review))
1325
- throw new Error(`[repos.${key}].review must be github, graphite, linear, linear-app, or an HTTPS template with {owner}, {repo}, {number}`);
1443
+ if (r.reviewTool !== void 0 && !validReviewTool(r.reviewTool))
1444
+ throw new Error(`[repos.${key}].reviewTool must be github, graphite, linear, linear-app, or an HTTPS template with {owner}, {repo}, {number}`);
1326
1445
  repos[key] = {
1327
1446
  path: expandHome(String(r.path ?? "")),
1328
1447
  ...r.traps !== void 0 ? { traps: r.traps } : {},
1329
- ...r.review !== void 0 ? { review: r.review } : {},
1448
+ ...r.reviewTool !== void 0 ? { reviewTool: r.reviewTool } : {},
1330
1449
  origin: r.origin ? String(r.origin) : void 0,
1331
1450
  trunk: String(r.trunk ?? "main"),
1332
1451
  setup: Array.isArray(r.setup) ? r.setup.map(String) : void 0,
@@ -1338,7 +1457,7 @@ function loadConfig() {
1338
1457
  draftPr: r.draftPr === void 0 ? void 0 : Boolean(r.draftPr),
1339
1458
  checkpointOnStop: r.checkpointOnStop === void 0 ? void 0 : Boolean(r.checkpointOnStop),
1340
1459
  humanGateChecks: Array.isArray(r.humanGateChecks) ? r.humanGateChecks.map(String).filter(Boolean) : void 0,
1341
- briefHooks: parseBriefHooks(r.briefHooks),
1460
+ ...parseBriefHooks(r.hooks?.brief) ? { hooks: { brief: parseBriefHooks(r.hooks.brief) } } : {},
1342
1461
  poolKeep: Array.isArray(r.poolKeep) ? r.poolKeep.map(String).filter(Boolean) : void 0
1343
1462
  };
1344
1463
  }
@@ -1368,11 +1487,11 @@ function loadConfig() {
1368
1487
  grounds,
1369
1488
  wharves,
1370
1489
  pools: parsePools(raw.pools, repos),
1371
- notifyCommand: raw.notifyCommand ? String(raw.notifyCommand) : void 0,
1372
- notifyVerbs: Array.isArray(raw.notifyVerbs) ? raw.notifyVerbs.map(String) : void 0,
1490
+ hooks: parseHooks(raw.hooks),
1373
1491
  remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0,
1374
1492
  readySettleSecs,
1375
- attentionKinds: parseAttentionKinds(raw.attentionKinds)
1493
+ attentionKinds: parseAttentionKinds(raw.attentionKinds),
1494
+ reviews: withConfigPath(() => parseReviews(raw.reviews, reposRaw))
1376
1495
  };
1377
1496
  }
1378
1497
  function resolveDispatch(d, cfg) {
@@ -4481,6 +4600,14 @@ function boundPr(descriptor, lane) {
4481
4600
  }
4482
4601
  return descriptor.followUp ? chainPr(descriptor.followUp, lane) : void 0;
4483
4602
  }
4603
+ function remotePolicyFor(descriptor, repo, cfg) {
4604
+ if (descriptor.readOnly) return { pushEarly: false, draftPr: false, checkpointOnStop: false };
4605
+ return {
4606
+ pushEarly: repo.pushEarly ?? cfg.limits.pushEarly,
4607
+ draftPr: repo.draftPr ?? cfg.limits.draftPr,
4608
+ checkpointOnStop: repo.checkpointOnStop ?? cfg.limits.checkpointOnStop
4609
+ };
4610
+ }
4484
4611
  function coldNote(cold, cwd, trunk) {
4485
4612
  const parts = [worktreeProgress(cwd, trunk)];
4486
4613
  if (cold.origin) parts.push(originProgress(cold.origin.id, cold.origin.lane));
@@ -4610,11 +4737,7 @@ async function main(activeDir, lane, seams = {}) {
4610
4737
  mergeEvidence(id, lane, { worktree: cwd, worktreeOf, ...inPool ? { pool: poolSlotLabel(inPool.pool, inPool.slot) } : {} });
4611
4738
  const existingPr = boundPr(descriptor, lane);
4612
4739
  if (existingPr) mergeEvidence(id, lane, { prUrl: existingPr.url });
4613
- const remotePolicy = {
4614
- pushEarly: repo.pushEarly ?? cfg.limits.pushEarly,
4615
- draftPr: repo.draftPr ?? cfg.limits.draftPr,
4616
- checkpointOnStop: repo.checkpointOnStop ?? cfg.limits.checkpointOnStop
4617
- };
4740
+ const remotePolicy = remotePolicyFor(descriptor, repo, cfg);
4618
4741
  const remoteEnabled = Object.values(remotePolicy).some(Boolean);
4619
4742
  const remote = keepRemote({
4620
4743
  id,
@@ -4,7 +4,7 @@ One file: `$LOBSTAH_HOME/config.toml` (default `~/.lobstah/config.toml`),
4
4
  created with commented examples by `lobstah init`. Pickup reads its own
5
5
  `[pickup.*]` sections from the same file.
6
6
 
7
- **The one TOML gotcha:** top-level keys (`notifyCommand`, `remindSecs`, …)
7
+ **The one TOML gotcha:** top-level keys (`attentionKinds`, `remindSecs`, …)
8
8
  must appear **before** the first `[section]` header, or they silently become
9
9
  keys of that section.
10
10
 
@@ -12,9 +12,7 @@ keys of that section.
12
12
 
13
13
  | Key | Default | Meaning |
14
14
  |---|---|---|
15
- | `notifyCommand` | — | Exec'd by the daemon on wake-worthy status transitions with `LOBSTAH_ID`, `LOBSTAH_LANE`, `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_AT` in the environment. Fire-and-forget; point it at ntfy, a Slack helper, anything. |
16
- | `notifyVerbs` | `["needs-decision", "blocked", "done", "failed"]` | Which verbs fire `notifyCommand`. |
17
- | `attentionKinds` | `["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"]` | Which kinds `man tend`, the glass, and the desktop pet show. `decision` is a question the helm put to the human with `lobstah man ask`; the glass shows it as a card to answer, and it hides the raw `question` it frames. Without `decision`, framed decisions do not show and raw questions do. `pr:draft`, `landed`, and `report` are valid opt-in kinds. An explicit list is used unchanged. Unknown kinds are errors. See the [attention contract](vocabulary.md#attention-contract). |
15
+ | `attentionKinds` | `["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"]` | Which kinds `man tend`, the glass, and the desktop pet show. `decision` is a question the helm put to the human with `lobstah man ask`; the glass shows it as a card to answer, and it hides the raw `question` it frames. Without `decision`, framed decisions do not show and raw questions do. `pr:draft`, `landed`, `report`, and `review` are valid opt-in kinds. An explicit list is used unchanged. Unknown kinds are errors. See the [attention contract](vocabulary.md#attention-contract). |
18
16
  | `remindSecs` | `900` | An unanswered `needs-decision`/`blocked` re-fires to `man wait`/`man haul` on this interval until answered. `0` = report once only. |
19
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. |
20
18
 
@@ -27,7 +25,7 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
27
25
  | `path` | yes | The git clone worktrees are allocated from (`~/` expands). |
28
26
  | `trunk` | yes (default `main`) | Branch dispatches start from (`origin/<trunk>`). |
29
27
  | `origin` | no | Enables clone-on-first-use when `path` doesn't exist. |
30
- | `review` | no (`"github"`) | Destination for PR links in the glass and PR pet clicks, independent of `[pet].open`: `github`, `graphite`, `linear` (browser: `https://linear.review/{owner}/{repo}/pull/{number}`), `linear-app` (Linear desktop app: `linear://review/{owner}/{repo}/pull/{number}`), or an HTTPS template containing `{owner}`, `{repo}`, and `{number}`. Example: `"https://review.example/{owner}/{repo}/{number}"`. The configured `origin` (else the checkout's git origin) identifies the repo; canonical GitHub URLs remain the watch identity. Linear reviews require its GitHub integration; `linear-app` also requires the installed app. Custom templates remain HTTPS-only. |
28
+ | `reviewTool` | no (`"github"`) | Destination for PR links in the glass and PR pet clicks, independent of `[pet].open`: `github`, `graphite`, `linear` (browser: `https://linear.review/{owner}/{repo}/pull/{number}`), `linear-app` (Linear desktop app: `linear://review/{owner}/{repo}/pull/{number}`), or an HTTPS template containing `{owner}`, `{repo}`, and `{number}`. Example: `"https://review.example/{owner}/{repo}/{number}"`. The configured `origin` (else the checkout's git origin) identifies the repo; canonical GitHub URLs remain the watch identity. Linear reviews require its GitHub integration; `linear-app` also requires the installed app. Custom templates remain HTTPS-only. |
31
29
  | `setup` | no | Commands run in each fresh worktree, in order (e.g. `["pnpm install"]`). A follow-up that reuses its origin's worktree does not run them again unless a lockfile at the worktree root (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, `go.sum`, and others) or the commands changed since they last ran there. |
32
30
  | `scratch` | no | Repo-relative paths (e.g. `["tmp", ".cache"]`) whose untracked files do not count as uncommitted changes when a follow-up decides whether to reuse its origin's worktree. Tracked changes anywhere, and untracked files elsewhere, still do. |
33
31
  | `env` | no | Environment merged into every dispatch for this repo. |
@@ -46,9 +44,43 @@ rather than relying on the default — left unset, a Claude session takes
46
44
  `effortLevel` from the host's settings files, including the user's own
47
45
  `~/.claude/settings.json`.
48
46
 
49
- `[repos.<key>.briefHooks]` — markdown appended to the briefs lobstah
50
- writes for this repo, one key per kind. Each value is a string; lobstah
51
- appends it as written and does not read it.
47
+ `[repos.<key>.hooks.brief]` — this repo's brief hooks: markdown appended
48
+ after the global [`[hooks.brief]`](#hooks--notify-commands-and-brief-hooks)
49
+ text, with the same keys.
50
+
51
+ ```toml
52
+ [repos.web.hooks.brief]
53
+ all = "Before you report done, run the repo's PR refresh (`/pr-refresh`)."
54
+ checks = "Run `pnpm test:ci` before you push."
55
+ prReview = "Check that every migration is reversible."
56
+ ```
57
+
58
+ `lobstah repos add <path> [--pickup]` detects and appends a block (origin,
59
+ default branch from `origin/HEAD`, setup from the lockfile); `lobstah init
60
+ --scan <dir>...` does the same for every git repo found under the given
61
+ roots. Both append text — hand-written comments survive.
62
+
63
+ ## `[hooks]` — notify commands and brief hooks
64
+
65
+ What lobstah runs, and what it appends to the briefs it writes. No old key
66
+ is read: each refuses to load and names its new place (see the CHANGELOG).
67
+
68
+ `[hooks.notify]` — the daemon's notifier.
69
+
70
+ | Key | Default | Meaning |
71
+ |---|---|---|
72
+ | `command` | — | Exec'd by the daemon on wake-worthy status transitions with `LOBSTAH_ID`, `LOBSTAH_LANE`, `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_AT` in the environment. Fire-and-forget; point it at ntfy, a Slack helper, anything. |
73
+ | `verbs` | `["needs-decision", "blocked", "paused", "done", "failed"]` | Which verbs fire `command`. |
74
+
75
+ `[hooks.pickupNotify]` — pick's notifier: `command`, exec'd on
76
+ tracker-report transitions with `LOBSTAH_KEY`, `LOBSTAH_UUID`,
77
+ `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_PR_URL`.
78
+
79
+ `[hooks.brief]` — markdown appended to every brief lobstah writes, per kind,
80
+ for every repo. A repo's `[repos.<key>.hooks.brief]` text comes after it.
81
+ Each value is a string; lobstah appends it as written and does not read it.
82
+ In each brief: the global kind's text, the global `all`, then the repo's
83
+ kind and `all`.
52
84
 
53
85
  | Key | Appended to |
54
86
  |---|---|
@@ -57,19 +89,20 @@ appends it as written and does not read it.
57
89
  | `review` | A daemon repair of a PR with requested changes, and a pickup review-feedback round. |
58
90
  | `ciFix` | A CI-fix continuation a PR watch forks. |
59
91
  | `rebase` | A rebase chore from pickup's merge loop. |
92
+ | `prReview` | A review-request draft job ([pickup.md](pickup.md), "Review requests"): your own review rules go here. |
60
93
  | `all` | Every kind above, after that kind's own text. |
61
94
 
62
95
  ```toml
63
- [repos.web.briefHooks]
64
- all = "Before you report done, run the repo's PR refresh (`/pr-refresh`)."
65
- checks = "Run `pnpm test:ci` before you push."
96
+ [hooks.notify]
97
+ command = 'ntfy pub my-topic "$LOBSTAH_VERB $LOBSTAH_ID: $LOBSTAH_NOTE"'
98
+
99
+ [hooks.brief]
100
+ prReview = """
101
+ Flag any change without a test.
102
+ Call out migrations that are not reversible.
103
+ """
66
104
  ```
67
105
 
68
- `lobstah repos add <path> [--pickup]` detects and appends a block (origin,
69
- default branch from `origin/HEAD`, setup from the lockfile); `lobstah init
70
- --scan <dir>...` does the same for every git repo found under the given
71
- roots. Both append text — hand-written comments survive.
72
-
73
106
  ## `[harness]` — global harness defaults
74
107
 
75
108
  Same three keys as the per-repo block. Precedence for every harness setting:
@@ -123,12 +156,12 @@ send a continuation.
123
156
  |---|---|---|
124
157
  | `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. |
125
158
  | `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. |
126
- | `timezone` | system timezone | IANA timezone (e.g. `America/New_York`) for daily goals. A goals day starts at 04:00 local. |
159
+ | `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. |
127
160
  | `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. |
128
161
  | `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. |
129
162
  | `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. |
130
163
  | `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. |
131
- | `todoStaleDays` | `3` | Open helm to-dos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
164
+ | `todoStaleDays` | `3` | Open helm todos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
132
165
 
133
166
  ## `[wait]` — quiet helm and trap waiters
134
167
 
@@ -275,7 +308,6 @@ outside `~/.lobstah/worktrees`: `lobstah cull`, the retention cull,
275
308
  |---|---|---|
276
309
  | `pollSecs` | `45` | Poll cadence. Outbound only — no webhooks, ever. |
277
310
  | `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. |
278
- | `notifyCommand` | — | Pickup's own hook, fired on tracker-report transitions with `LOBSTAH_KEY`, `LOBSTAH_UUID`, `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_PR_URL`. |
279
311
  | `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. |
280
312
 
281
313
  ### Token sources (both trackers)
@@ -332,6 +364,28 @@ key reused as the routing key. Opt-in is per repo, never implied.
332
364
 
333
365
  See [pickup.md](pickup.md) for the loop semantics these keys drive.
334
366
 
367
+ ## `[reviews]` — review requests (`lobstah pick`), off by default
368
+
369
+ When someone asks `[pickup.github].identity` for a review, `lobstah pick`
370
+ files a review item ([pickup.md](pickup.md), "Review requests"). It searches
371
+ as that identity, with its token. Any key except `enabled`, `repos` and
372
+ `maxPerDay` can be overridden per repo under `[repos.<key>.reviews]`.
373
+
374
+ | Key | Default | Meaning |
375
+ |---|---|---|
376
+ | `enabled` | `false` | Opt-in. Off means no search call at all. |
377
+ | `repos` | `"configured"` | `"configured"`: only PRs in a `[repos.*]` origin. `"any"`: every repo the token can see. |
378
+ | `work` | `"trap"` | Who drafts the review: `"off"`, `"trap"` (a free trap of that repo, then headless after `trapWaitSecs`), or `"headless"`. |
379
+ | `post` | `"draft"` | `"draft"`: stage the draft as the identity's pending review on the PR, to edit and send from the review tool. `"auto"`: post the draft as a comment-only review once drafted. lobstah never approves or requests changes. |
380
+ | `harness`, `model`, `effort` | repo, then `[harness]` | The review job's worker. |
381
+ | `wallClockSecs`, `maxTurns`, `maxBudgetUsd` | `900`, `40`, unset | Cost bounds for one review job. |
382
+ | `trapWaitSecs` | `600` | With `work = "trap"`: how long a job waits for a free trap. |
383
+ | `maxPerDay` | `20` | Review jobs started per day. Past it, items file with no job. |
384
+ | `skipAuthors`, `skipLabels` | `[]` | Requests on PRs by these authors or with these labels file an item but start no job. |
385
+
386
+ The `review` attention kind is not in the default `attentionKinds`; add it to
387
+ let review items walk in `man tend`, the glass, and the pet.
388
+
335
389
  ## Environment
336
390
 
337
391
  | Variable | Meaning |
package/docs/man.md CHANGED
@@ -74,6 +74,9 @@ and its TOON output is built to be read by agents.
74
74
  replaces them, and `lobstah goals YYYY-MM-DD` reads a past day. Use
75
75
  `lobstah goals add "<text>"` to append a goal at any time and
76
76
  `lobstah goals rm <n>` to remove the numbered line shown by `lobstah goals`.
77
+ `lobstah goals done <n>` checks one off without removing it; `goals undo <n>`
78
+ unchecks it. Completion is stored as Markdown `- [x]` / `- [ ]` in the same
79
+ daily file and is retained in recap data. Old unmarked lines are not done.
77
80
  These edit today's file without repeating the first-chat card. Use
78
81
  `--grounds <name>` to choose grounds and `--session <id>` to identify the helm
79
82
  for writes. Files are editable Markdown at
@@ -89,7 +92,7 @@ with `goals set`; the first reminder leaves a comment in that same daily file.
89
92
  The helm uses them to order work and choose the next quiet step.
90
93
 
91
94
  `lobstah goals recap-data [YYYY-MM-DD]` prints retained dispatch results, PR
92
- open/merge times, answered cards and closed to-dos when their
95
+ open/merge times, answered cards and closed todos when their
93
96
  optional store exists. Its default is yesterday. First observation is not
94
97
  the forge's PR creation time (older records may have only that fallback);
95
98
  missing/expired records are not reconstructed.
@@ -484,7 +487,7 @@ A question is held while a helm is signed on for its grounds and has not
484
487
  ended a turn since the question was filed. A held question is in `man tend`,
485
488
  `man wait`, the park, and reminders, and `lobstah attention` and `man tend`
486
489
  mark it `held`. It is not in `attention --json` (the pet), the glass, or
487
- notifyCommand. The question walks when the helm ends a turn (`man haul`)
490
+ `[hooks.notify]`. The question walks when the helm ends a turn (`man haul`)
488
491
  without answering it; the release is recorded in `releases/<key>.json`. With
489
492
  no helm signed on, or a helm relieved or stale past `[helm].ttlSecs`, a
490
493
  question walks at once.
@@ -503,11 +506,20 @@ dispatch with its full brief, status log, inbox, and evidence, each trap
503
506
  with its lifecycle notices, message history, and catches, the notices
504
507
  tail, the merge view, and watches — with filters, a table/cards toggle,
505
508
  and the helm identified by name. Its tabs are On deck, Dispatches, Traps,
506
- PRs, Reports, Notices, and Stats. The Stats tab shows catches per day as a
509
+ PRs, Reviews, Reports, Notices, and Stats. The Stats tab shows catches per day as a
507
510
  53-week heatmap, with today, this week, the total, and the top traps; it
508
511
  reads `stats.json` from `GET /data/stats` and sends nothing. The Reports tab lists every report, unacked first,
509
512
  then newest first, and the repo filter and the search box (title, author,
510
- dispatch id, repo) apply to it. Reading the glass consumes no cursor. Each
513
+ dispatch id, repo) apply to it. The Reviews tab lists the PRs that ask
514
+ for your review ([pickup.md](pickup.md), "Review requests"), the ones
515
+ waiting on you first, as a table or as cards. A row opens the PR in the
516
+ repo's review tool (`[repos.<key>].reviewTool`), where the drafted review waits
517
+ as your pending review, to edit and send there. The tab only dismisses a
518
+ review (deleting its pending draft) or re-drafts a stale or failed one,
519
+ through the page-token-guarded `/requests` endpoint as `review-dismiss` or
520
+ `review-redraft`. On Deck lists the reviews waiting on you when there are
521
+ any. A `review` lob and the pet's review lobster ("review request") open the
522
+ PR in the review tool too. Nothing counts reviews with a badge. Reading the glass consumes no cursor. Each
511
523
  live trap has a **↗ open** button at the end of its foot line. It asks the local server to focus
512
524
  that trap's reported session link, iTerm2 session, Terminal tab, editor
513
525
  worktree, or recorded app, in that order. The result names the step that
@@ -568,7 +580,7 @@ the helm files to keep.
568
580
  - **Filing a helm report.** `lobstah man file <file.md> [--attach <file> ...]
569
581
  [--title <text>]`. It is stored under the helm's grounds,
570
582
  `reports/<grounds>/<rid>/`, with the same layout, and the author is `helm`.
571
- - **The helm's to-dos.** Reminders the helm keeps for itself ("merge #2268
583
+ - **The helm's todos.** Reminders the helm keeps for itself ("merge #2268
572
584
  once the API is in production") go in `lobstah todo add "<text>"`, not
573
585
  only in the conversation. The text is free: any detail, link, or PR goes
574
586
  in it.
@@ -577,11 +589,16 @@ the helm files to keep.
577
589
  closed ones. They are stored per grounds in `todos/<grounds>.json` with
578
590
  created and updated times. `man tend`, `man report`, and the glass deck
579
591
  show the open ones, and `man brief` re-injects them beside the charter at
580
- every session start and after compaction. Open to-dos older than
592
+ every session start and after compaction. A todo marked done stays in
593
+ `man tend` and the glass Todos checklist, with a green check and struck
594
+ through, until the next day boundary (04:00 local, `[helm].timezone` or
595
+ the system zone, as for daily goals); then it drops off. A dropped one
596
+ leaves at once. Closed todos stay 30 days for `todo ls --all` and the
597
+ recap either way. Open todos older than
581
598
  `[helm].todoStaleDays` (default 3) add one line to `man tend`, for
582
- example "3 to-dos older than 3 days: move to the issue tracker?". The helm
599
+ example "3 todos older than 3 days: move to the issue tracker?". The helm
583
600
  decides whether to raise a card and files them with the user's tracker.
584
- A trap keeps no to-dos; with a claimed helm, only the helm writes them.
601
+ A trap keeps no todos; with a claimed helm, only the helm writes them.
585
602
  - **Title and author.** The title is `--title`, else the page's first `#`
586
603
  heading, else the dispatch's brief title. The author is the trap name, or
587
604
  `headless`, or `helm`. A file larger than `[limits].attachmentMaxBytes` is
package/docs/openclaw.md CHANGED
@@ -54,7 +54,7 @@ The division of labor that falls out:
54
54
  - **Fleet agents** keep the judgment work: triage, escalation policy,
55
55
  answering humans — and reach lobstah through the plugin tools when a request
56
56
  becomes a dispatch.
57
- - **Notifications** ride `notifyCommand` — point it at your existing Slack
57
+ - **Notifications** ride `[hooks.notify]` — point its `command` at your existing Slack
58
58
  helper; lobstah stays vendor-free.
59
59
 
60
60
  Token minting for GitHub Apps fits the `tokenCommand` source directly
package/docs/pickup.md CHANGED
@@ -47,7 +47,7 @@ watches needs `Checks: read`, `Pull requests: read and write`,
47
47
  pickup — `Issues: read and write`. [github.md](github.md) says what each one
48
48
  is used for and what fails without it; `lobstah doctor` probes them.
49
49
 
50
- **Notifications are a hook, not a vendor.** `notifyCommand` under `[pickup]`
50
+ **Notifications are a hook, not a vendor.** `[hooks.pickupNotify].command`
51
51
  is exec'd on every verb transition with `LOBSTAH_KEY`, `LOBSTAH_UUID`,
52
52
  `LOBSTAH_VERB`, `LOBSTAH_NOTE`, and `LOBSTAH_PR_URL` in the environment —
53
53
  fire-and-forget, never blocking the loop. Point it at whatever the host
@@ -114,15 +114,37 @@ A dispatch reports `done` when its PR opens, so the reviewer's side of the
114
114
  conversation has to re-enter the queue as its own work. Feedback pickup
115
115
  covers all of it: a `CHANGES_REQUESTED` review on any sha (a review of a
116
116
  slightly stale head still asks for changes), a comment review with a body,
117
- an inline review-thread comment, or a conversation comment — always from
118
- someone other than the configured identity, never a lobstah marker comment.
117
+ an inline review-thread comment, or a conversation comment — from anyone,
118
+ the configured identity included, but never a comment lobstah wrote.
119
119
  `APPROVED` reviews are the merge loop's signal, not feedback.
120
120
 
121
+ The configured identity counts because lobstah's workers post as that
122
+ account: the owner's own "also handle X" on a trap's PR differs from a worker's
123
+ reply only by the marker. An **active-round guard** covers a worker that
124
+ forgets the marker. An unmarked identity comment made while a lobstah run on
125
+ the PR works (the implementation dispatch or a round) is held: it waits for
126
+ the run to end, then opens a round. A round opened only by such held
127
+ comments drops, rather than holds, the identity's unmarked comments made
128
+ during its own run. A forgetful worker costs at most one extra round, never
129
+ a loop. A comment the owner writes during that one round is dropped too.
130
+
131
+ Everything lobstah writes carries a marker: status and live comments lead
132
+ with `[lobstah:<uuid>]`; notes with no dispatch behind them (an orphan reset)
133
+ end with the hidden `<!-- lobstah -->`; and the feedback and review-repair
134
+ briefs tell the worker to end every reply it posts with
135
+ `<!-- lobstah:<id> -->`. A review, inline comment, or conversation comment
136
+ carrying either marker is never feedback.
137
+
121
138
  The PR maps back to a dispatch two ways: a `lobstah/<uuid>` branch names it
122
139
  directly, and any other branch — a soaked session's PR — resolves through
123
140
  the PR URL in its worker's evidence (`report --pr <url>`, or a trap's beat). A PR
124
141
  that maps to neither is not lobstah's to answer.
125
142
 
143
+ A round goes to the trap that worked the PR (its claim, else its delivery
144
+ receipt) while that trap is live, and waits `[watch].repairTrapWaitSecs` for
145
+ it, as a repair chore does. Past the wait, any trap of the repo or the
146
+ daemon may take it.
147
+
126
148
  Each feedback **round** is keyed by the newest feedback event, so a new
127
149
  comment after a round completes opens the next round, while the same standing
128
150
  feedback never double-dispatches. Rounds on one PR serialize — a round that
@@ -208,7 +230,7 @@ lobstah watch add ume:9f2c --check '...' --for <dispatch-uuid>
208
230
 
209
231
  Each cycle: run due checks (cadence = `[pickup].pollSecs`, or `--every` per
210
232
  watch), append events, deliver by owner. Man-owned events surface through
211
- `man wait`/`man haul` and fire `notifyCommand` with verb `watch`;
233
+ `man wait`/`man haul` and fire `[hooks.pickupNotify]` with verb `watch`;
212
234
  dispatch-owned events enqueue a continuation that forks the latest session
213
235
  in the owning chain — one in flight per watch, later rounds buffer. With no
214
236
  tracker sources configured, `lobstah pick` still runs in watch-only mode.
@@ -229,6 +251,89 @@ directories, so a continuation enqueued by a stream event is claimed in
229
251
  milliseconds too — end to end, an external event reaches a spawning session
230
252
  in roughly harness start-up time.
231
253
 
254
+ ## Review requests
255
+
256
+ Opt-in with `[reviews].enabled` ([configuration.md](configuration.md)). Each
257
+ cycle spends one GitHub request: a GraphQL search for open PRs with
258
+ `user-review-requested:<identity>`, through `gh api graphql` on the shared
259
+ GitHub budget. A blocked budget skips the cycle. `user-review-requested`
260
+ matches requests that name the identity; a request made only to a team the
261
+ identity is on files nothing.
262
+
263
+ Each PR is one review item, `review:<owner>/<repo>#<n>`, in
264
+ `~/.lobstah/reviews/<owner>-<repo>-<n>/review.json`. An item holds rounds,
265
+ one per `ReviewRequestedEvent`: the same standing request never opens a
266
+ second round, and a re-request opens a new one (an open earlier round is
267
+ withdrawn as superseded). A new push with no new request moves a requested
268
+ round's head; a drafted round becomes `stale` and starts nothing on its own.
269
+ When the search stops returning a PR (the request was withdrawn, the
270
+ person reviewed it on GitHub, or the PR closed), its open round is `withdrawn`. A
271
+ truncated search (more than 50 results) withdraws nothing.
272
+
273
+ **Drafting.** With `[reviews].work` other than `"off"`, a requested round in
274
+ a configured repo gets a review job: a chore-lane dispatch with the
275
+ `prReview` brief, `readOnly` (the runner pushes nothing, opens no PR, and
276
+ checkpoints nothing), and the `[reviews]` cost bounds. With `work = "trap"`
277
+ the job waits `trapWaitSecs` for a free trap of the repo, then pick hands it
278
+ to the daemon. The job reads the PR with `gh`, makes any checkout it needs
279
+ as a detached worktree of `pull/<n>/head` at the fixed path
280
+ `rounds/<round id>/checkout`, and writes `review.md` (the summary) and
281
+ `comments.json` (inline comments: `path`, `line`, `side`, `body`) into the
282
+ round's directory, `rounds/<round id>/`. Whenever the round's job ends
283
+ (drafted, stale, failed, or withdrawn and its job cancelled, a re-request
284
+ included), pick removes that checkout: `git worktree remove --force`, then
285
+ `git worktree prune`; nothing happens when the path is absent. It follows the repo's own review guidance at the PR head (REVIEW.md,
286
+ CONTRIBUTING.md, AGENTS.md, CLAUDE.md, the PR template), then the
287
+ review rules in `[hooks.brief].prReview`, then any
288
+ `[repos.<key>.hooks.brief].prReview` text. It never posts,
289
+ approves, requests changes, comments, or pushes. When the job reports done,
290
+ the round is `drafted`, or `stale` if the head moved meanwhile, or `failed`
291
+ with the reason when the files are missing or malformed. A skip rule, a PR
292
+ outside the configured repos, or `maxPerDay` jobs already started today
293
+ (UTC) leave the round `requested` with the reason. `lobstah reviews redraft
294
+ <key>` drafts a stale or failed round again at the current head.
295
+
296
+ **Staging and posting.** With `[reviews].post = "draft"` (the default), a
297
+ fresh draft is staged on the PR as the identity's **pending review**:
298
+ `POST /repos/{o}/{r}/pulls/{n}/reviews` with no event, `commit_id` set to the
299
+ head the draft reviewed, the inline comments, and a body ending with
300
+ `<!-- lobstah:review <round id> -->`. GitHub shows a pending review only to
301
+ its author, so nothing is visible on the PR until the person opens it in
302
+ their review tool (`[repos.<key>].reviewTool`), edits the draft there, and
303
+ sends it, with whatever event they choose. When the request then disappears from the
304
+ search, pick reads that review once: submitted marks the round `posted` (by
305
+ `review tool`), deleted dismisses it, still pending withdraws it.
306
+
307
+ With `"auto"`, a fresh draft is posted at once as a comment-only review
308
+ (`event: COMMENT`). `lobstah reviews post <key>` sends a staged review as a
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
313
+ most once: `staged.json` and `posted.json` in the round's directory are
314
+ created with `wx` before the call and removed if it fails, and a review on
315
+ the PR that already carries the round's marker is adopted (pending) or
316
+ recorded (sent) instead of written again. A failed stage or post keeps its
317
+ reason on the round and is not retried on its own. `lobstah reviews dismiss`
318
+ and `redraft` delete the round's pending review first; a review already sent
319
+ is never deleted.
320
+
321
+ **On wharf grounds.** A review item whose repo belongs to a grounds with a
322
+ wharf is that boat's to publish: before drafting, pick creates the round's
323
+ `review` document, with an id derived from the item and the round, so a
324
+ second boat that found the same round gets a 409, drafts nothing, and stages
325
+ nothing. The boat publishes every state change with the link that opens the
326
+ PR in the repo's review tool (no helm seat, and no wharf event, so no helm
327
+ wakes). The hosted glass has a Reviews tab whose cards open that link; its
328
+ one request is Dismiss, addressed to the publishing boat, which deletes the
329
+ pending draft with its own token and marks the request done or refused. The
330
+ wharf never calls GitHub.
331
+
332
+ Round states: `requested`, `drafting`, `drafted`, `stale`, `failed`,
333
+ `posted`, `dismissed`, `withdrawn`. The `review` attention item stands while
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.
336
+
232
337
  ## Merge loop
233
338
 
234
339
  Opt-in, per repo, off by default. Merging is policy, not mechanics, so it ships