lobstah 0.7.6 → 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)
@@ -1249,9 +1360,11 @@ var DEFAULT_HELM = {
1249
1360
  idleWorkingNoticeSecs: 60,
1250
1361
  ttlSecs: 1800,
1251
1362
  reportSecs: 900,
1252
- armGraceSecs: 5
1363
+ armGraceSecs: 5,
1364
+ todoStaleDays: 3
1253
1365
  };
1254
1366
  var DEFAULT_GLASS = { port: 4949 };
1367
+ var DEFAULT_WAIT = { baseTimeoutSecs: 900, baseRepeats: 3, maxTimeoutSecs: 14400 };
1255
1368
  var DEFAULT_WATCH = { maxForksPerCycle: 3, autoRepair: true, conflicts: true, checks: true, maxRepairsPerPr: 2, maxRepairsWithoutProgress: 2, repairSettleSecs: 600, repairCooldownSecs: 0, repairTrapWaitSecs: 600 };
1256
1369
  var DEFAULT_LIMITS = {
1257
1370
  maxConcurrent: 2,
@@ -1271,6 +1384,13 @@ var DEFAULT_LIMITS = {
1271
1384
  reuseWorktree: true,
1272
1385
  releaseOnMerge: false
1273
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
+ }
1274
1394
  function configPath() {
1275
1395
  return path4.join(lobstahHome(), "config.toml");
1276
1396
  }
@@ -1285,7 +1405,23 @@ function loadConfig() {
1285
1405
  throw new Error(`[pet].open must be "tab", "app", or "helm" in ${configPath()}`);
1286
1406
  const watch = { ...DEFAULT_WATCH, ...raw.watch ?? {} };
1287
1407
  const helm = { ...DEFAULT_HELM, ...raw.helm ?? {} };
1288
- for (const key of ["queuedNoticeSecs", "stalledNoticeSecs", "idleWorkingNoticeSecs"]) {
1408
+ const wait = { ...DEFAULT_WAIT, ...raw.wait ?? {} };
1409
+ for (const key of ["baseTimeoutSecs", "baseRepeats", "maxTimeoutSecs"]) {
1410
+ if (typeof wait[key] !== "number" || !Number.isSafeInteger(wait[key]) || wait[key] <= 0)
1411
+ throw new Error(`[wait].${key} must be a positive whole number in ${configPath()}`);
1412
+ }
1413
+ if (wait.maxTimeoutSecs < wait.baseTimeoutSecs)
1414
+ throw new Error(`[wait].maxTimeoutSecs must be at least baseTimeoutSecs in ${configPath()}`);
1415
+ if (helm.timezone !== void 0) {
1416
+ if (typeof helm.timezone !== "string" || !helm.timezone.trim())
1417
+ throw new Error("[helm].timezone must be an IANA timezone");
1418
+ try {
1419
+ new Intl.DateTimeFormat("en", { timeZone: helm.timezone });
1420
+ } catch {
1421
+ throw new Error("[helm].timezone must be an IANA timezone");
1422
+ }
1423
+ }
1424
+ for (const key of ["queuedNoticeSecs", "stalledNoticeSecs", "idleWorkingNoticeSecs", "todoStaleDays"]) {
1289
1425
  if (typeof helm[key] !== "number" || !Number.isFinite(helm[key]) || helm[key] < 0) {
1290
1426
  throw new Error(`[helm].${key} must be a non-negative number in ${configPath()}`);
1291
1427
  }
@@ -1298,17 +1434,18 @@ function loadConfig() {
1298
1434
  throw new Error(`readySettleSecs must be a non-negative number in ${configPath()}`);
1299
1435
  }
1300
1436
  const reposRaw = raw.repos ?? {};
1437
+ refuseMoved(raw, reposRaw);
1301
1438
  const repos = {};
1302
1439
  for (const [key, r] of Object.entries(reposRaw)) {
1303
1440
  if (r.traps !== void 0 && (typeof r.traps !== "number" || !Number.isSafeInteger(r.traps) || r.traps < 0)) {
1304
1441
  throw new Error(`[repos.${key}].traps must be a non-negative whole number`);
1305
1442
  }
1306
- if (r.review !== void 0 && !validReviewTool(r.review))
1307
- 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}`);
1308
1445
  repos[key] = {
1309
1446
  path: expandHome(String(r.path ?? "")),
1310
1447
  ...r.traps !== void 0 ? { traps: r.traps } : {},
1311
- ...r.review !== void 0 ? { review: r.review } : {},
1448
+ ...r.reviewTool !== void 0 ? { reviewTool: r.reviewTool } : {},
1312
1449
  origin: r.origin ? String(r.origin) : void 0,
1313
1450
  trunk: String(r.trunk ?? "main"),
1314
1451
  setup: Array.isArray(r.setup) ? r.setup.map(String) : void 0,
@@ -1320,7 +1457,7 @@ function loadConfig() {
1320
1457
  draftPr: r.draftPr === void 0 ? void 0 : Boolean(r.draftPr),
1321
1458
  checkpointOnStop: r.checkpointOnStop === void 0 ? void 0 : Boolean(r.checkpointOnStop),
1322
1459
  humanGateChecks: Array.isArray(r.humanGateChecks) ? r.humanGateChecks.map(String).filter(Boolean) : void 0,
1323
- briefHooks: parseBriefHooks(r.briefHooks),
1460
+ ...parseBriefHooks(r.hooks?.brief) ? { hooks: { brief: parseBriefHooks(r.hooks.brief) } } : {},
1324
1461
  poolKeep: Array.isArray(r.poolKeep) ? r.poolKeep.map(String).filter(Boolean) : void 0
1325
1462
  };
1326
1463
  }
@@ -1343,17 +1480,18 @@ function loadConfig() {
1343
1480
  limits: { ...DEFAULT_LIMITS, ...raw.limits ?? {} },
1344
1481
  soak: parseSoak(raw.soak),
1345
1482
  helm,
1483
+ wait,
1346
1484
  glass: { ...DEFAULT_GLASS, ...raw.glass ?? {} },
1347
1485
  pet: { open: petOpen },
1348
1486
  watch,
1349
1487
  grounds,
1350
1488
  wharves,
1351
1489
  pools: parsePools(raw.pools, repos),
1352
- notifyCommand: raw.notifyCommand ? String(raw.notifyCommand) : void 0,
1353
- notifyVerbs: Array.isArray(raw.notifyVerbs) ? raw.notifyVerbs.map(String) : void 0,
1490
+ hooks: parseHooks(raw.hooks),
1354
1491
  remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0,
1355
1492
  readySettleSecs,
1356
- attentionKinds: parseAttentionKinds(raw.attentionKinds)
1493
+ attentionKinds: parseAttentionKinds(raw.attentionKinds),
1494
+ reviews: withConfigPath(() => parseReviews(raw.reviews, reposRaw))
1357
1495
  };
1358
1496
  }
1359
1497
  function resolveDispatch(d, cfg) {
@@ -1513,7 +1651,7 @@ function parsePrRef(s) {
1513
1651
  const number = Number(n);
1514
1652
  return { owner, repo, number, key: `pr:${owner}/${repo}#${number}`, url: `https://github.com/${owner}/${repo}/pull/${number}` };
1515
1653
  }
1516
- var PR_VIEW_FIELDS = "title,state,isDraft,isCrossRepository,headRefOid,baseRefName,baseRefOid,headRefName,mergeStateStatus,reviewDecision,statusCheckRollup,mergedAt,closedAt,updatedAt,reviews";
1654
+ var PR_VIEW_FIELDS = "title,state,isDraft,isCrossRepository,headRefOid,baseRefName,baseRefOid,headRefName,mergeStateStatus,reviewDecision,statusCheckRollup,createdAt,mergedAt,closedAt,updatedAt,reviews";
1517
1655
  var PR_VIEW_FIELDS_NO_CHECKS = PR_VIEW_FIELDS.split(",").filter((f) => f !== "statusCheckRollup").join(",");
1518
1656
  var FORBIDDEN = /resource not accessible by (integration|personal access token)/i;
1519
1657
  function ghPrView(ref) {
@@ -2619,6 +2757,9 @@ function parseBackendLocation(raw) {
2619
2757
  return { kind: "wharf", url: b.url.replace(/\/$/, ""), account: b.account, tokenEnv: b.tokenEnv };
2620
2758
  }
2621
2759
 
2760
+ // packages/core/dist/todos.js
2761
+ var CLOSED_KEEP_MS = 30 * 24 * 3600 * 1e3;
2762
+
2622
2763
  // packages/core/dist/decisions.js
2623
2764
  var DECISION_DETAIL_MAX = 64 * 1024;
2624
2765
  var ANSWER_TYPES = {
@@ -2642,6 +2783,9 @@ var ANSWER_TYPES = {
2642
2783
  };
2643
2784
  var ANSWER_EXTENSIONS = Object.keys(ANSWER_TYPES);
2644
2785
 
2786
+ // packages/core/dist/grants.js
2787
+ var ONCE_TTL_MS = 60 * 60 * 1e3;
2788
+
2645
2789
  // packages/core/dist/harness.js
2646
2790
  import * as fs23 from "node:fs";
2647
2791
  import * as path19 from "node:path";
@@ -4456,6 +4600,14 @@ function boundPr(descriptor, lane) {
4456
4600
  }
4457
4601
  return descriptor.followUp ? chainPr(descriptor.followUp, lane) : void 0;
4458
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
+ }
4459
4611
  function coldNote(cold, cwd, trunk) {
4460
4612
  const parts = [worktreeProgress(cwd, trunk)];
4461
4613
  if (cold.origin) parts.push(originProgress(cold.origin.id, cold.origin.lane));
@@ -4585,11 +4737,7 @@ async function main(activeDir, lane, seams = {}) {
4585
4737
  mergeEvidence(id, lane, { worktree: cwd, worktreeOf, ...inPool ? { pool: poolSlotLabel(inPool.pool, inPool.slot) } : {} });
4586
4738
  const existingPr = boundPr(descriptor, lane);
4587
4739
  if (existingPr) mergeEvidence(id, lane, { prUrl: existingPr.url });
4588
- const remotePolicy = {
4589
- pushEarly: repo.pushEarly ?? cfg.limits.pushEarly,
4590
- draftPr: repo.draftPr ?? cfg.limits.draftPr,
4591
- checkpointOnStop: repo.checkpointOnStop ?? cfg.limits.checkpointOnStop
4592
- };
4740
+ const remotePolicy = remotePolicyFor(descriptor, repo, cfg);
4593
4741
  const remoteEnabled = Object.values(remotePolicy).some(Boolean);
4594
4742
  const remote = keepRemote({
4595
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,10 +156,29 @@ 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. |
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. |
126
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. |
127
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. |
128
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. |
129
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. |
164
+ | `todoStaleDays` | `3` | Open helm todos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
165
+
166
+ ## `[wait]` — quiet helm and trap waiters
167
+
168
+ | Key | Default | Meaning |
169
+ |-----|---------|---------|
170
+ | `baseTimeoutSecs` | `900` | Initial idle timeout for `man wait`, `soak --wait` and Stop-hook parks, local or on a wharf. A positive `--timeout` overrides the base for that invocation, not the adaptive backoff. |
171
+ | `baseRepeats` | `3` | Consecutive empty timeouts at the base before doubling on each subsequent wait. |
172
+ | `maxTimeoutSecs` | `14400` | Idle timeout cap (4 hours), at least the base. All three settings are positive whole numbers. |
173
+
174
+ The defaults wait 900, 900, 900, 1800, 3600, 7200, then 14400 seconds.
175
+ History is stored per session across re-arms. An event or user prompt resets
176
+ that session; a dispatch or send resets all this boat's waiters. Already-armed
177
+ waiters adopt a fresh base deadline on their next poll. Polling and liveness
178
+ heartbeats keep their usual cadence, so events still wake immediately.
179
+ `--peek` and zero-time trap probes do not advance the backoff.
180
+ For a cap longer than four hours, use a foreground waiter or increase the
181
+ harness's blocking Stop-hook timeout too.
130
182
 
131
183
  ## `[glass]` — the spyglass
132
184
 
@@ -256,7 +308,6 @@ outside `~/.lobstah/worktrees`: `lobstah cull`, the retention cull,
256
308
  |---|---|---|
257
309
  | `pollSecs` | `45` | Poll cadence. Outbound only — no webhooks, ever. |
258
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. |
259
- | `notifyCommand` | — | Pickup's own hook, fired on tracker-report transitions with `LOBSTAH_KEY`, `LOBSTAH_UUID`, `LOBSTAH_VERB`, `LOBSTAH_NOTE`, `LOBSTAH_PR_URL`. |
260
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. |
261
312
 
262
313
  ### Token sources (both trackers)
@@ -313,6 +364,28 @@ key reused as the routing key. Opt-in is per repo, never implied.
313
364
 
314
365
  See [pickup.md](pickup.md) for the loop semantics these keys drive.
315
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
+
316
389
  ## Environment
317
390
 
318
391
  | Variable | Meaning |
@@ -35,6 +35,8 @@ row, and the session-start brief says when the plugin is behind.
35
35
  | Stop hook (`lobstah man haul`) | At turn end, blocks with standing attention, or with the command to arm a watcher while work is in flight. Inert unless the session holds the helm or is soaking. |
36
36
  | PostToolUse hook (`lobstah soak beat`) | After every tool call in a soaking session: refreshes the trap's liveness and writes its catch's activity (the tool name and its primary target, redacted). At most once per 30 seconds per trap. No network, no git; always exits 0, errors go to `~/.lobstah/logs/beat.log`. Inert when not soaking or with `[soak].beat = false`. |
37
37
  | SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends and keeps its worktree. |
38
+ | Grants mod (`hooks/grants.mjs`) | Answers Claude Code's `tool.check` for a trap's Bash and write calls: a call that would be put to a prompt or the auto-mode classifier, and that a person has granted (`lobstah grant`, or Allow on a glass card), runs. It leaves alone a call the rules allow or refuse. Mods need a Claude Code version that supports them; they do not run in WSL or the VS Code chat panel. |
39
+ | PermissionRequest hook (`lobstah hook permission-request`) | The same answer where a permission prompt would show. |
38
40
  | `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken. |
39
41
  | `trap` skill | The worker: soaking (in a linked worktree, or in one that soak creates), the `wt:` address, the six report verbs, and `paused --waiting-on` before waiting on something external (for ume, the non-blocking push when the await cannot run as a tracked background task). |
40
42
 
@@ -36,6 +36,7 @@ says when the plugin is behind.
36
36
  | Stop hook (`lobstah man haul`) | Parks the session at turn end while work is in flight and wakes it when something needs attention. Inert unless the session holds the helm or is soaking. |
37
37
  | PostToolUse hook (`lobstah soak beat`) | After a tool call in a soaking session: refreshes the trap's liveness and writes its catch's activity. Needs Codex 0.117.0+ (see [below](#post-tool-hook-what-codex-has)). Older Codex ignores the event, and a trap's liveness then comes from its reports and its park only. |
38
38
  | SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends and keeps its worktree. |
39
+ | PermissionRequest hook (`lobstah hook permission-request`) | When Codex is about to ask for approval in a trap, a call a person has granted (`lobstah grant`, or Allow on a glass card) is allowed, before the approval reviewer. Anything not granted goes on to Codex's normal approval. Like every hook, it runs only once trusted in `/hooks`; it is new, so it needs that review once. |
39
40
  | `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken, and sending a follow-up to finished work. |
40
41
  | `trap` skill | The worker: soaking (in a linked worktree, or in one that soak creates), the `wt:` address, the six report verbs, and `paused --waiting-on` before external waits. |
41
42
 
package/docs/man.md CHANGED
@@ -68,6 +68,39 @@ the background, dispatch it with the `lobstah` CLI instead of doing it inline:
68
68
  That's the whole integration — the CLI is self-documenting (`lobstah help`)
69
69
  and its TOON output is built to be read by agents.
70
70
 
71
+ ## Daily goals
72
+
73
+ `lobstah goals` shows today's goals; `lobstah goals set "<line>" [...]`
74
+ replaces them, and `lobstah goals YYYY-MM-DD` reads a past day. Use
75
+ `lobstah goals add "<text>"` to append a goal at any time and
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.
80
+ These edit today's file without repeating the first-chat card. Use
81
+ `--grounds <name>` to choose grounds and `--session <id>` to identify the helm
82
+ for writes. Files are editable Markdown at
83
+ `~/.lobstah/goals/<grounds>/YYYY-MM-DD.md` (implicit `home` uses the permanent
84
+ `fleet` storage name). Each day starts at 04:00 in the system timezone;
85
+ `[helm].timezone` can choose an IANA timezone instead.
86
+
87
+ The first user prompt of a new day adds a non-blocking reminder to the helm:
88
+ handle that message, then put yesterday's recap and a draft of today's goals
89
+ on one card. Existing goals, a `Goals for YYYY-MM-DD` card, or an already
90
+ delivered reminder suppress another ask. The helm saves the answered goals
91
+ with `goals set`; the first reminder leaves a comment in that same daily file.
92
+ The helm uses them to order work and choose the next quiet step.
93
+
94
+ `lobstah goals recap-data [YYYY-MM-DD]` prints retained dispatch results, PR
95
+ open/merge times, answered cards and closed todos when their
96
+ optional store exists. Its default is yesterday. First observation is not
97
+ the forge's PR creation time (older records may have only that fallback);
98
+ missing/expired records are not reconstructed.
99
+ The helm matches those facts to the goals (done, moved, stuck, plus also done),
100
+ then saves the Markdown with `lobstah goals recap YYYY-MM-DD --file <md>`.
101
+ Today's lines are pinned above `man tend` and the glass; recaps stay in the
102
+ daily files. Goals are local files, not wharf-synced state.
103
+
71
104
  ## Taking over a worker
72
105
 
73
106
  Every dispatch **is** a real harness session, running under the same CLI you
@@ -454,7 +487,7 @@ A question is held while a helm is signed on for its grounds and has not
454
487
  ended a turn since the question was filed. A held question is in `man tend`,
455
488
  `man wait`, the park, and reminders, and `lobstah attention` and `man tend`
456
489
  mark it `held`. It is not in `attention --json` (the pet), the glass, or
457
- 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`)
458
491
  without answering it; the release is recorded in `releases/<key>.json`. With
459
492
  no helm signed on, or a helm relieved or stale past `[helm].ttlSecs`, a
460
493
  question walks at once.
@@ -473,11 +506,20 @@ dispatch with its full brief, status log, inbox, and evidence, each trap
473
506
  with its lifecycle notices, message history, and catches, the notices
474
507
  tail, the merge view, and watches — with filters, a table/cards toggle,
475
508
  and the helm identified by name. Its tabs are On deck, Dispatches, Traps,
476
- 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
477
510
  53-week heatmap, with today, this week, the total, and the top traps; it
478
511
  reads `stats.json` from `GET /data/stats` and sends nothing. The Reports tab lists every report, unacked first,
479
512
  then newest first, and the repo filter and the search box (title, author,
480
- 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
481
523
  live trap has a **↗ open** button at the end of its foot line. It asks the local server to focus
482
524
  that trap's reported session link, iTerm2 session, Terminal tab, editor
483
525
  worktree, or recorded app, in that order. The result names the step that
@@ -538,6 +580,25 @@ the helm files to keep.
538
580
  - **Filing a helm report.** `lobstah man file <file.md> [--attach <file> ...]
539
581
  [--title <text>]`. It is stored under the helm's grounds,
540
582
  `reports/<grounds>/<rid>/`, with the same layout, and the author is `helm`.
583
+ - **The helm's todos.** Reminders the helm keeps for itself ("merge #2268
584
+ once the API is in production") go in `lobstah todo add "<text>"`, not
585
+ only in the conversation. The text is free: any detail, link, or PR goes
586
+ in it.
587
+ `lobstah todo done <id>` and `lobstah todo drop <id>` close one;
588
+ `lobstah todo ls` (or bare `todo`) lists the open ones, and `--all` adds
589
+ closed ones. They are stored per grounds in `todos/<grounds>.json` with
590
+ created and updated times. `man tend`, `man report`, and the glass deck
591
+ show the open ones, and `man brief` re-injects them beside the charter at
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
598
+ `[helm].todoStaleDays` (default 3) add one line to `man tend`, for
599
+ example "3 todos older than 3 days: move to the issue tracker?". The helm
600
+ decides whether to raise a card and files them with the user's tracker.
601
+ A trap keeps no todos; with a claimed helm, only the helm writes them.
541
602
  - **Title and author.** The title is `--title`, else the page's first `#`
542
603
  heading, else the dispatch's brief title. The author is the trap name, or
543
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