lobstah 0.7.7 → 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/dist/runner.js CHANGED
@@ -1173,7 +1173,91 @@ 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
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
+ }
1177
1261
  var POOL_NAME = /^[A-Za-z0-9_-]+$/;
1178
1262
  function parsePools(raw, repos) {
1179
1263
  const out = {};
@@ -1198,7 +1282,7 @@ function parsePools(raw, repos) {
1198
1282
  }
1199
1283
  return out;
1200
1284
  }
1201
- var BRIEF_KINDS = ["conflict", "checks", "review", "ciFix", "rebase"];
1285
+ var BRIEF_KINDS = ["conflict", "checks", "review", "ciFix", "rebase", "prReview"];
1202
1286
  function parseBriefHooks(raw) {
1203
1287
  if (!raw || typeof raw !== "object" || Array.isArray(raw))
1204
1288
  return void 0;
@@ -1210,7 +1294,44 @@ function parseBriefHooks(raw) {
1210
1294
  }
1211
1295
  return Object.keys(out).length ? out : void 0;
1212
1296
  }
1213
- var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report", "stack-ready"];
1297
+ function refuseMoved(raw, reposRaw) {
1298
+ const moved = [
1299
+ [raw.notifyCommand !== void 0, "notifyCommand moved to [hooks.notify].command"],
1300
+ [raw.notifyVerbs !== void 0, "notifyVerbs moved to [hooks.notify].verbs"],
1301
+ [raw.pickup?.notifyCommand !== void 0, "[pickup].notifyCommand moved to [hooks.pickupNotify].command"],
1302
+ [raw.reviews?.rules !== void 0, "[reviews].rules moved to [hooks.brief].prReview"]
1303
+ ];
1304
+ for (const [key, r] of Object.entries(reposRaw)) {
1305
+ 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`]);
1306
+ }
1307
+ const found = moved.filter(([hit]) => hit).map(([, why]) => why);
1308
+ if (found.length)
1309
+ throw new Error(`${found.join("; ")} (in ${configPath()})`);
1310
+ }
1311
+ function parseHooks(raw) {
1312
+ if (raw === void 0)
1313
+ return { brief: {} };
1314
+ if (!raw || typeof raw !== "object" || Array.isArray(raw))
1315
+ throw new Error(`[hooks] must be a table in ${configPath()}`);
1316
+ const h = raw;
1317
+ const command = (table, where) => {
1318
+ const t = table;
1319
+ if (!t || typeof t !== "object" || typeof t.command !== "string" || !t.command.trim())
1320
+ throw new Error(`${where}.command must be a command line in ${configPath()}`);
1321
+ return t.command;
1322
+ };
1323
+ const out = { brief: parseBriefHooks(h.brief) ?? {} };
1324
+ if (h.notify !== void 0) {
1325
+ const verbs = h.notify.verbs;
1326
+ if (verbs !== void 0 && (!Array.isArray(verbs) || !verbs.every((v) => typeof v === "string")))
1327
+ throw new Error(`[hooks.notify].verbs must be an array of verbs in ${configPath()}`);
1328
+ out.notify = { command: command(h.notify, "[hooks.notify]"), ...verbs ? { verbs } : {} };
1329
+ }
1330
+ if (h.pickupNotify !== void 0)
1331
+ out.pickupNotify = { command: command(h.pickupNotify, "[hooks.pickupNotify]") };
1332
+ return out;
1333
+ }
1334
+ var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report", "stack-ready", "review"];
1214
1335
  var DEFAULT_ATTENTION_KINDS = ["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"];
1215
1336
  function parseAttentionKinds(raw) {
1216
1337
  if (raw === void 0)
@@ -1273,6 +1394,13 @@ var DEFAULT_LIMITS = {
1273
1394
  reuseWorktree: true,
1274
1395
  releaseOnMerge: false
1275
1396
  };
1397
+ function withConfigPath(parse2) {
1398
+ try {
1399
+ return parse2();
1400
+ } catch (err) {
1401
+ throw new Error(`${err instanceof Error ? err.message : String(err)} in ${configPath()}`);
1402
+ }
1403
+ }
1276
1404
  function configPath() {
1277
1405
  return path4.join(lobstahHome(), "config.toml");
1278
1406
  }
@@ -1316,29 +1444,30 @@ function loadConfig() {
1316
1444
  throw new Error(`readySettleSecs must be a non-negative number in ${configPath()}`);
1317
1445
  }
1318
1446
  const reposRaw = raw.repos ?? {};
1447
+ refuseMoved(raw, reposRaw);
1319
1448
  const repos = {};
1320
1449
  for (const [key, r] of Object.entries(reposRaw)) {
1321
1450
  if (r.traps !== void 0 && (typeof r.traps !== "number" || !Number.isSafeInteger(r.traps) || r.traps < 0)) {
1322
1451
  throw new Error(`[repos.${key}].traps must be a non-negative whole number`);
1323
1452
  }
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}`);
1453
+ if (r.reviewTool !== void 0 && !validReviewTool(r.reviewTool))
1454
+ throw new Error(`[repos.${key}].reviewTool must be github, graphite, linear, linear-app, or an HTTPS template with {owner}, {repo}, {number}`);
1326
1455
  repos[key] = {
1327
1456
  path: expandHome(String(r.path ?? "")),
1328
1457
  ...r.traps !== void 0 ? { traps: r.traps } : {},
1329
- ...r.review !== void 0 ? { review: r.review } : {},
1458
+ ...r.reviewTool !== void 0 ? { reviewTool: r.reviewTool } : {},
1330
1459
  origin: r.origin ? String(r.origin) : void 0,
1331
1460
  trunk: String(r.trunk ?? "main"),
1332
1461
  setup: Array.isArray(r.setup) ? r.setup.map(String) : void 0,
1333
1462
  env: r.env ?? void 0,
1334
- harness: r.harness ?? void 0,
1463
+ harness: parseHarness(r.harness, `[repos.${key}.harness]`),
1335
1464
  pickup: r.pickup === void 0 ? void 0 : Boolean(r.pickup),
1336
1465
  scratch: Array.isArray(r.scratch) ? r.scratch.map(String) : void 0,
1337
1466
  pushEarly: r.pushEarly === void 0 ? void 0 : Boolean(r.pushEarly),
1338
1467
  draftPr: r.draftPr === void 0 ? void 0 : Boolean(r.draftPr),
1339
1468
  checkpointOnStop: r.checkpointOnStop === void 0 ? void 0 : Boolean(r.checkpointOnStop),
1340
1469
  humanGateChecks: Array.isArray(r.humanGateChecks) ? r.humanGateChecks.map(String).filter(Boolean) : void 0,
1341
- briefHooks: parseBriefHooks(r.briefHooks),
1470
+ ...parseBriefHooks(r.hooks?.brief) ? { hooks: { brief: parseBriefHooks(r.hooks.brief) } } : {},
1342
1471
  poolKeep: Array.isArray(r.poolKeep) ? r.poolKeep.map(String).filter(Boolean) : void 0
1343
1472
  };
1344
1473
  }
@@ -1357,7 +1486,7 @@ function loadConfig() {
1357
1486
  }
1358
1487
  return {
1359
1488
  repos,
1360
- harness: raw.harness ?? {},
1489
+ harness: parseHarness(raw.harness, "[harness]") ?? {},
1361
1490
  limits: { ...DEFAULT_LIMITS, ...raw.limits ?? {} },
1362
1491
  soak: parseSoak(raw.soak),
1363
1492
  helm,
@@ -1368,11 +1497,11 @@ function loadConfig() {
1368
1497
  grounds,
1369
1498
  wharves,
1370
1499
  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,
1500
+ hooks: parseHooks(raw.hooks),
1373
1501
  remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0,
1374
1502
  readySettleSecs,
1375
- attentionKinds: parseAttentionKinds(raw.attentionKinds)
1503
+ attentionKinds: parseAttentionKinds(raw.attentionKinds),
1504
+ reviews: withConfigPath(() => parseReviews(raw.reviews, reposRaw))
1376
1505
  };
1377
1506
  }
1378
1507
  function resolveDispatch(d, cfg) {
@@ -3914,7 +4043,7 @@ function buildPrompt(brief, opts) {
3914
4043
  reporting,
3915
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.`,
3916
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.`,
3917
- 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; do not create a duplicate PR. When finished, mark the draft ready for review if appropriate, then report done with its URL. Do not merge anything.`,
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.`,
3918
4047
  `--- BRIEF ---`,
3919
4048
  opts.existingPr ? `${brief}
3920
4049
 
@@ -4481,6 +4610,17 @@ function boundPr(descriptor, lane) {
4481
4610
  }
4482
4611
  return descriptor.followUp ? chainPr(descriptor.followUp, lane) : void 0;
4483
4612
  }
4613
+ function remotePolicyFor(descriptor, repo, cfg) {
4614
+ if (descriptor.readOnly) return { pushEarly: false, draftPr: false, checkpointOnStop: false };
4615
+ return {
4616
+ pushEarly: repo.pushEarly ?? cfg.limits.pushEarly,
4617
+ draftPr: repo.draftPr ?? cfg.limits.draftPr,
4618
+ checkpointOnStop: repo.checkpointOnStop ?? cfg.limits.checkpointOnStop
4619
+ };
4620
+ }
4621
+ function draftPrTitle(id) {
4622
+ return `lobstah ${short3(id)}`;
4623
+ }
4484
4624
  function coldNote(cold, cwd, trunk) {
4485
4625
  const parts = [worktreeProgress(cwd, trunk)];
4486
4626
  if (cold.origin) parts.push(originProgress(cold.origin.id, cold.origin.lane));
@@ -4610,18 +4750,14 @@ async function main(activeDir, lane, seams = {}) {
4610
4750
  mergeEvidence(id, lane, { worktree: cwd, worktreeOf, ...inPool ? { pool: poolSlotLabel(inPool.pool, inPool.slot) } : {} });
4611
4751
  const existingPr = boundPr(descriptor, lane);
4612
4752
  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
- };
4753
+ const remotePolicy = remotePolicyFor(descriptor, repo, cfg);
4618
4754
  const remoteEnabled = Object.values(remotePolicy).some(Boolean);
4619
4755
  const remote = keepRemote({
4620
4756
  id,
4621
4757
  lane,
4622
4758
  cwd,
4623
4759
  trunk: repo.trunk,
4624
- title: descriptor.brief.split("\n")[0]?.trim() || `Lobstah dispatch ${short3(id)}`,
4760
+ title: draftPrTitle(id),
4625
4761
  policy: remotePolicy,
4626
4762
  existingPrUrl: existingPr?.url
4627
4763
  });
@@ -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. |
@@ -38,7 +36,23 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
38
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>`. |
39
37
 
40
38
  `[repos.<key>.harness]` — per-repo harness defaults: `default` (`claude` \|
41
- `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
+ ```
42
56
 
43
57
  `effort` reaches both harnesses: Claude as its effort level (`low`, `medium`,
44
58
  `high`, `xhigh`, `max`), Codex as `model_reasoning_effort`. Set it for Claude
@@ -46,9 +60,43 @@ rather than relying on the default — left unset, a Claude session takes
46
60
  `effortLevel` from the host's settings files, including the user's own
47
61
  `~/.claude/settings.json`.
48
62
 
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.
63
+ `[repos.<key>.hooks.brief]` — this repo's brief hooks: markdown appended
64
+ after the global [`[hooks.brief]`](#hooks--notify-commands-and-brief-hooks)
65
+ text, with the same keys.
66
+
67
+ ```toml
68
+ [repos.web.hooks.brief]
69
+ all = "Before you report done, run the repo's PR refresh (`/pr-refresh`)."
70
+ checks = "Run `pnpm test:ci` before you push."
71
+ prReview = "Check that every migration is reversible."
72
+ ```
73
+
74
+ `lobstah repos add <path> [--pickup]` detects and appends a block (origin,
75
+ default branch from `origin/HEAD`, setup from the lockfile); `lobstah init
76
+ --scan <dir>...` does the same for every git repo found under the given
77
+ roots. Both append text — hand-written comments survive.
78
+
79
+ ## `[hooks]` — notify commands and brief hooks
80
+
81
+ What lobstah runs, and what it appends to the briefs it writes. No old key
82
+ is read: each refuses to load and names its new place (see the CHANGELOG).
83
+
84
+ `[hooks.notify]` — the daemon's notifier.
85
+
86
+ | Key | Default | Meaning |
87
+ |---|---|---|
88
+ | `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. |
89
+ | `verbs` | `["needs-decision", "blocked", "paused", "done", "failed"]` | Which verbs fire `command`. |
90
+
91
+ `[hooks.pickupNotify]` — pick's notifier: `command`, exec'd on
92
+ tracker-report transitions with `LOBSTAH_KEY`, `LOBSTAH_UUID`,
93
+ `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_PR_URL`.
94
+
95
+ `[hooks.brief]` — markdown appended to every brief lobstah writes, per kind,
96
+ for every repo. A repo's `[repos.<key>.hooks.brief]` text comes after it.
97
+ Each value is a string; lobstah appends it as written and does not read it.
98
+ In each brief: the global kind's text, the global `all`, then the repo's
99
+ kind and `all`.
52
100
 
53
101
  | Key | Appended to |
54
102
  |---|---|
@@ -57,22 +105,23 @@ appends it as written and does not read it.
57
105
  | `review` | A daemon repair of a PR with requested changes, and a pickup review-feedback round. |
58
106
  | `ciFix` | A CI-fix continuation a PR watch forks. |
59
107
  | `rebase` | A rebase chore from pickup's merge loop. |
108
+ | `prReview` | A review-request draft job ([pickup.md](pickup.md), "Review requests"): your own review rules go here. |
60
109
  | `all` | Every kind above, after that kind's own text. |
61
110
 
62
111
  ```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."
112
+ [hooks.notify]
113
+ command = 'ntfy pub my-topic "$LOBSTAH_VERB $LOBSTAH_ID: $LOBSTAH_NOTE"'
114
+
115
+ [hooks.brief]
116
+ prReview = """
117
+ Flag any change without a test.
118
+ Call out migrations that are not reversible.
119
+ """
66
120
  ```
67
121
 
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
122
  ## `[harness]` — global harness defaults
74
123
 
75
- Same three keys as the per-repo block. Precedence for every harness setting:
124
+ Same four keys as the per-repo block. Precedence for every harness setting:
76
125
  **descriptor > repo > global > adapter default.**
77
126
 
78
127
  ## `[limits]`
@@ -85,8 +134,8 @@ Same three keys as the per-repo block. Precedence for every harness setting:
85
134
  | `maxRestartAttempts` | `2` | Bounded restart ladder for dead and wedged runners. |
86
135
  | `wallClockSecs` | `3600` | Initial active-work window. Progress extends it, up to `maxWallClockSecs`; time paused with `report paused --waiting-on` does not count. |
87
136
  | `maxWallClockSecs` | `4 × wallClockSecs` | Hard active-work ceiling across restarts. |
88
- | `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 or a rebase chore), does not push automatically; its worker pushes to the existing PR's head branch. |
89
- | `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. |
90
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. |
91
140
 
92
141
  A runner extends its active-work window when a fresh activity event or new HEAD
@@ -123,12 +172,12 @@ send a continuation.
123
172
  |---|---|---|
124
173
  | `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
174
  | `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. |
175
+ | `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
176
  | `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
177
  | `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
178
  | `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
179
  | `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. |
180
+ | `todoStaleDays` | `3` | Open helm todos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
132
181
 
133
182
  ## `[wait]` — quiet helm and trap waiters
134
183
 
@@ -275,7 +324,6 @@ outside `~/.lobstah/worktrees`: `lobstah cull`, the retention cull,
275
324
  |---|---|---|
276
325
  | `pollSecs` | `45` | Poll cadence. Outbound only — no webhooks, ever. |
277
326
  | `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
327
  | `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
328
 
281
329
  ### Token sources (both trackers)
@@ -332,6 +380,28 @@ key reused as the routing key. Opt-in is per repo, never implied.
332
380
 
333
381
  See [pickup.md](pickup.md) for the loop semantics these keys drive.
334
382
 
383
+ ## `[reviews]` — review requests (`lobstah pick`), off by default
384
+
385
+ When someone asks `[pickup.github].identity` for a review, `lobstah pick`
386
+ files a review item ([pickup.md](pickup.md), "Review requests"). It searches
387
+ as that identity, with its token. Any key except `enabled`, `repos` and
388
+ `maxPerDay` can be overridden per repo under `[repos.<key>.reviews]`.
389
+
390
+ | Key | Default | Meaning |
391
+ |---|---|---|
392
+ | `enabled` | `false` | Opt-in. Off means no search call at all. |
393
+ | `repos` | `"configured"` | `"configured"`: only PRs in a `[repos.*]` origin. `"any"`: every repo the token can see. |
394
+ | `work` | `"trap"` | Who drafts the review: `"off"`, `"trap"` (a free trap of that repo, then headless after `trapWaitSecs`), or `"headless"`. |
395
+ | `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. |
396
+ | `harness`, `model`, `effort` | repo, then `[harness]` | The review job's worker. |
397
+ | `wallClockSecs`, `maxTurns`, `maxBudgetUsd` | `900`, `40`, unset | Cost bounds for one review job. |
398
+ | `trapWaitSecs` | `600` | With `work = "trap"`: how long a job waits for a free trap. |
399
+ | `maxPerDay` | `20` | Review jobs started per day. Past it, items file with no job. |
400
+ | `skipAuthors`, `skipLabels` | `[]` | Requests on PRs by these authors or with these labels file an item but start no job. |
401
+
402
+ The `review` attention kind is not in the default `attentionKinds`; add it to
403
+ let review items walk in `man tend`, the glass, and the pet.
404
+
335
405
  ## Environment
336
406
 
337
407
  | Variable | Meaning |