lobstah 0.8.7 → 0.8.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
@@ -1050,6 +1050,11 @@ function reportMarkdownPath(key) {
1050
1050
  return file2 && readReport(key) && fs5.existsSync(file2) ? file2 : void 0;
1051
1051
  }
1052
1052
 
1053
+ // packages/core/dist/run-cards.js
1054
+ var RUN_SCRIPT_MAX_BYTES = 16 * 1024;
1055
+ var RUN_TIMEOUT_DEFAULT_SECS = 5 * 60;
1056
+ var RUN_TIMEOUT_MAX_SECS = 60 * 60;
1057
+
1053
1058
  // packages/core/dist/decisions.js
1054
1059
  var DECISION_DETAIL_MAX = 64 * 1024;
1055
1060
  var ANSWER_TYPES = {
@@ -1072,6 +1077,7 @@ var ANSWER_TYPES = {
1072
1077
  ".zip": "application/zip"
1073
1078
  };
1074
1079
  var ANSWER_EXTENSIONS = Object.keys(ANSWER_TYPES);
1080
+ var RUN_DONE_GRACE_MS = 2 * 6e4;
1075
1081
 
1076
1082
  // packages/core/dist/roster.js
1077
1083
  import * as fs6 from "node:fs";
@@ -3153,6 +3159,7 @@ var REVIEW_MODES = ["notify", "on-demand", "auto-draft", "auto-review"];
3153
3159
  var DEFAULT_REVIEWS = {
3154
3160
  enabled: false,
3155
3161
  mode: "notify",
3162
+ requestedAfter: "enabled",
3156
3163
  publish: false,
3157
3164
  repos: "configured",
3158
3165
  work: "off",
@@ -3196,6 +3203,11 @@ function parseSettings(raw, where) {
3196
3203
  }
3197
3204
  if (raw.work !== void 0)
3198
3205
  out.work = oneOf(raw.work, REVIEW_WORK, `${where}.work`);
3206
+ if (raw.requestedAfter !== void 0) {
3207
+ if (raw.requestedAfter !== "enabled" && (typeof raw.requestedAfter !== "string" || !Number.isFinite(Date.parse(raw.requestedAfter))))
3208
+ throw new Error(`${where}.requestedAfter must be "enabled" or an ISO timestamp`);
3209
+ out.requestedAfter = raw.requestedAfter === "enabled" ? "enabled" : new Date(raw.requestedAfter).toISOString();
3210
+ }
3199
3211
  if (raw.post !== void 0)
3200
3212
  out.post = oneOf(raw.post, REVIEW_POST, `${where}.post`);
3201
3213
  for (const k of ["harness", "model", "effort"])
@@ -3382,7 +3394,7 @@ function parsePermissions(raw) {
3382
3394
  }
3383
3395
  return out;
3384
3396
  }
3385
- var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report", "stack-ready", "review"];
3397
+ var ATTENTION_KINDS = ["question", "decision", "landed", "pr:draft", "pr:review", "pr:checks", "pr:conflict", "pr:ready", "report", "stack-ready", "review", "dispatch-progress"];
3386
3398
  var DEFAULT_ATTENTION_KINDS = ["question", "decision", "pr:ready", "pr:review", "pr:conflict", "pr:checks"];
3387
3399
  function parseAttentionKinds(raw) {
3388
3400
  if (raw === void 0)
@@ -3401,6 +3413,10 @@ function parseSoak(raw) {
3401
3413
  const soak = { ...DEFAULT_SOAK, ...raw ?? {} };
3402
3414
  if (!Number.isInteger(soak.codexStartSecs) || soak.codexStartSecs < 1)
3403
3415
  throw new Error("soak.codexStartSecs must be a positive whole number");
3416
+ for (const key of ["codexClaimWakeSecs", "codexClaimReleaseSecs"]) {
3417
+ if (!Number.isInteger(soak[key]) || soak[key] < 1)
3418
+ throw new Error(`soak.${key} must be a positive whole number`);
3419
+ }
3404
3420
  if (typeof soak.acceptWharfStarts !== "boolean")
3405
3421
  throw new Error("soak.acceptWharfStarts must be true or false");
3406
3422
  if (typeof soak.codexRemoteControl !== "boolean")
@@ -3442,11 +3458,18 @@ function parseHeavy(raw) {
3442
3458
  heavy.repos = repos;
3443
3459
  return heavy;
3444
3460
  }
3461
+ function parseMergeMethod(value, key) {
3462
+ if (value === "merge" || value === "squash" || value === "rebase")
3463
+ return value;
3464
+ throw new Error(`repos.${key}.mergeMethod must be "merge", "squash" or "rebase"`);
3465
+ }
3445
3466
  var DEFAULT_SOAK = {
3446
3467
  codexStartSecs: 600,
3447
3468
  acceptWharfStarts: false,
3448
3469
  deferSecs: 90,
3449
3470
  claimIdleNoticeSecs: 180,
3471
+ codexClaimWakeSecs: 120,
3472
+ codexClaimReleaseSecs: 600,
3450
3473
  ttlSecs: 1800,
3451
3474
  beat: true,
3452
3475
  pausedTtlSecs: 86400,
@@ -3490,6 +3513,7 @@ var DEFAULT_LIMITS = {
3490
3513
  backgroundWaitSecs: 1800,
3491
3514
  exitGraceSecs: 30,
3492
3515
  choreRetentionDays: 7,
3516
+ runRetentionDays: 14,
3493
3517
  attachmentMaxBytes: 25 * 1024 * 1024,
3494
3518
  retentionDays: 0,
3495
3519
  minFreeGB: 0,
@@ -3581,6 +3605,7 @@ function loadConfig() {
3581
3605
  pushEarly: r.pushEarly === void 0 ? void 0 : Boolean(r.pushEarly),
3582
3606
  draftPr: r.draftPr === void 0 ? void 0 : Boolean(r.draftPr),
3583
3607
  checkpointOnStop: r.checkpointOnStop === void 0 ? void 0 : Boolean(r.checkpointOnStop),
3608
+ ...r.mergeMethod !== void 0 ? { mergeMethod: parseMergeMethod(r.mergeMethod, key) } : {},
3584
3609
  humanGateChecks: Array.isArray(r.humanGateChecks) ? r.humanGateChecks.map(String).filter(Boolean) : void 0,
3585
3610
  ...parseBriefHooks(r.hooks?.brief) ? { hooks: { brief: parseBriefHooks(r.hooks.brief) } } : {},
3586
3611
  poolKeep: Array.isArray(r.poolKeep) ? r.poolKeep.map(String).filter(Boolean) : void 0
@@ -3588,10 +3613,15 @@ function loadConfig() {
3588
3613
  }
3589
3614
  const groundsRaw = raw.grounds ?? {};
3590
3615
  const wharves = {};
3616
+ const wharfRemoteAnswers = {};
3591
3617
  for (const [name, value] of Object.entries(raw.wharves ?? {})) {
3592
3618
  if (!/^[A-Za-z0-9_-]{1,64}$/.test(name))
3593
3619
  throw new Error("invalid wharf name");
3594
- wharves[name] = parseBackendLocation({ ...value, kind: "wharf" });
3620
+ const { remoteAnswers, ...location } = value;
3621
+ wharves[name] = parseBackendLocation({ ...location, kind: "wharf" });
3622
+ if (remoteAnswers !== void 0 && typeof remoteAnswers !== "boolean")
3623
+ throw new Error(`wharves.${name}.remoteAnswers must be true or false`);
3624
+ wharfRemoteAnswers[name] = remoteAnswers !== false;
3595
3625
  }
3596
3626
  const grounds = {};
3597
3627
  for (const [key, g] of Object.entries(groundsRaw)) {
@@ -3612,6 +3642,7 @@ function loadConfig() {
3612
3642
  watch,
3613
3643
  grounds,
3614
3644
  wharves,
3645
+ wharfRemoteAnswers,
3615
3646
  pools: parsePools(raw.pools, repos),
3616
3647
  traps: parseConfiguredTraps(raw.traps, grounds),
3617
3648
  hooks: parseHooks(raw.hooks),
@@ -3771,6 +3802,7 @@ function cancelRequested(id, lane) {
3771
3802
  }
3772
3803
 
3773
3804
  // packages/core/dist/backend-model.js
3805
+ var MIRROR_ATTENTION_MAX_BYTES = 256 * 1024;
3774
3806
  var MIRROR_SNAPSHOT_MAX_BYTES = 2 * 1024 * 1024;
3775
3807
  var MIRROR_SNAPSHOT_MAX_JSON_BYTES = 16 * 1024 * 1024;
3776
3808
 
@@ -3793,6 +3825,9 @@ function parseBackendLocation(raw) {
3793
3825
  // packages/core/dist/todos.js
3794
3826
  var CLOSED_KEEP_MS = 30 * 24 * 3600 * 1e3;
3795
3827
 
3828
+ // packages/core/dist/terminal-render.js
3829
+ var PLAIN = Object.freeze({});
3830
+
3796
3831
  // packages/core/dist/grants.js
3797
3832
  var ONCE_TTL_MS = 60 * 60 * 1e3;
3798
3833
 
@@ -5115,12 +5150,12 @@ function onlyScratch(porcelain, scratch) {
5115
5150
  });
5116
5151
  }
5117
5152
  async function chooseWorktree(input) {
5118
- const { id, lane, repoKey, repo, followUp } = input;
5153
+ const { id, lane, repoKey: repoKey2, repo, followUp } = input;
5119
5154
  const found = chainWorktree(followUp);
5120
5155
  if (!found)
5121
5156
  return { reuse: false, reason: "origin worktree is gone" };
5122
5157
  const ownerRepo = storedDescriptor(found.owner, laneOf(found.owner) ?? lane)?.repo ?? storedDescriptor(found.from, laneOf(found.from) ?? lane)?.repo;
5123
- if (ownerRepo !== void 0 && ownerRepo !== repoKey) {
5158
+ if (ownerRepo !== void 0 && ownerRepo !== repoKey2) {
5124
5159
  return { reuse: false, reason: `origin worktree belongs to repo ${ownerRepo}` };
5125
5160
  }
5126
5161
  try {
@@ -12,7 +12,7 @@ keys of that section.
12
12
 
13
13
  | Key | Default | Meaning |
14
14
  |---|---|---|
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). |
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`, `review`, and `dispatch-progress` are valid opt-in kinds. `dispatch-progress` (queued too long, stalled, idle while working) always reaches the helm; named here, it also walks on the pet and shows on the glass. An explicit list is used unchanged. Unknown kinds are errors. See the [attention contract](vocabulary.md#attention-contract). |
16
16
  | `remindSecs` | `900` | An unanswered `needs-decision`/`blocked` re-fires to `man wait`/`man haul` on this interval until answered. `0` = report once only. |
17
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. |
18
18
 
@@ -65,6 +65,7 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
65
65
  | `path` | yes | The git clone worktrees are allocated from (`~/` expands). |
66
66
  | `trunk` | yes (default `main`) | Branch dispatches start from (`origin/<trunk>`). |
67
67
  | `origin` | no | Enables clone-on-first-use when `path` doesn't exist. |
68
+ | `mergeMethod` | no (`[pickup.github.merge].method`, else `squash`) | How the glass's Merge when green merges this repo's PRs: `merge`, `squash` or `rebase`. A request keeps the method it was asked with. |
68
69
  | `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. |
69
70
  | `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. |
70
71
  | `cacheDirs` | no | Disposable cache-directory globs relative to trap worktrees, e.g. `["apps/*/.next/cache", ".temp/*DerivedData*"]`. No absolute paths or `..`; symlinks, Git metadata and matches containing tracked files are preserved. Cleared on sign-off or terminal dispatch reports, and in idle traps under disk pressure. Omit to disable. |
@@ -73,7 +74,7 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
73
74
  | `pickup` | no (`false`) | Opt this repo into `[pickup.github]` multi-repo mode. Explicit per repo — nothing becomes pickable by being configured. |
74
75
  | `pushEarly`, `draftPr`, `checkpointOnStop` | no (inherit `[limits]`) | Override remote preservation for this repo's headless dispatches. |
75
76
  | `poolKeep` | no | Extra gitignore-style patterns a pool reset keeps (e.g. `["apps/ios/DerivedData/"]`), on top of the built-in keep list. See [`[pools.<name>]`](#poolsname--warm-worktrees-for-headless-dispatches). |
76
- | `traps` | unlimited | Non-negative whole number: maximum rostered traps for this repo, live plus stowed or ghosted (starting reservations count too). `dispatch --trap-any` reuses a free live trap, brings a safely returnable roster trap back, then creates only below the cap; at capacity it queues for the first suitable free trap, never headless. `man throw --new` refuses above the cap and requires `--reason` when reusable traps exist, including `--dry-run`. Lowering the cap never deletes or forgets traps: `man tend` shows used/cap and over-limit entries; stow a live trap, then `man roster forget <trap>` to remove its checkout and free its roster place subject to the existing safety checks. |
77
+ | `traps` | unlimited | Non-negative whole number: maximum traps in use for this repo: signed on and listening, free or busy, plus those starting. Stowed and ghosted traps don't count; `man tend`, the status roster line and the glass's Settings show them beside the count as `+K stowed/ghosted`, and name a ghosted trap whose session is still open so you can end it. `dispatch --trap-any` reuses a free live trap, then, below the cap, brings a safely returnable stowed or ghosted trap back or creates one; at the cap it queues for the first suitable free trap, never headless. A trap coming back takes a slot like a new one: `man throw <trap>` and `man throw --new` refuse at the cap, and `--new` requires `--reason` when reusable traps exist, including `--dry-run`. Lowering the cap never stows or forgets traps: `man tend` shows in use against the cap, and stowing a trap frees its slot. |
77
78
  | `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>`. |
78
79
 
79
80
  `[repos.<key>.harness]` — per-repo harness defaults: `default` (`claude` \|
@@ -203,6 +204,7 @@ send a continuation.
203
204
  | `backgroundWaitSecs` | `1800` | A turn that ends without a report is held open this long while background work the worker started is still running (a push behind a slow pre-push gate); the harness wakes the worker when it settles. Heartbeats keep the wedge detector off the wait. Keep it below `wallClockSecs`, which still ends the run. |
204
205
  | `exitGraceSecs` | `30` | After the worker reports `done` or `failed` at the end of a turn, the runner ends the session and waits this long for the harness to close its event stream. If the stream is still open, the runner kills the harness, then stops every process the runner started (its process group on Linux and macOS, its process tree on Windows), and finishes. The report stands: the status stays `done` or `failed`, and evidence records `harnessStopped` with how many seconds after the report the harness was stopped. When the stream closes in time, the runner stops any background processes the harness left running on its way out. |
205
206
  | `choreRetentionDays` | `7` | Completed chores age out of `chores/done/`. |
207
+ | `runRetentionDays` | `14` | How long a run card's history stays on disk: each run's output and state, and a run card that left the glass. The daemon prunes older ones hourly. `0` keeps them. |
206
208
  | `attachmentMaxBytes` | `26214400` (25 MiB) | Maximum size of each file supplied with repeatable `dispatch --attach`, `send --attach`, or a decision answer. Picked files and images pasted into a glass answer box use this limit. |
207
209
  | `retentionDays` | `0` (off) | The daemon culls finished dispatches (done and failed) older than this many days: their `done/` entries, worktrees, state files, and stale PR records and acks. Branches are kept. A dispatch whose PR is still open is kept. Queued and active dispatches are never culled. The pass runs at most once per hour and culls at most 10 dispatches per pass, so it cannot stall the claim loop. Suggested: `14`, the same window as `lobstah cull`. |
208
210
  | `releaseOnMerge` | `false` (off) | When a PR watch records `merged` for a PR, the daemon's next cull pass removes the worktree of the dispatch that owns the PR, and of every dispatch in its follow-up chain that ran on that PR (its own worktree or a shared one). It uses the retention cull's removal path, its hourly throttle, and its limit of 10 per pass, and runs even when `retentionDays` is `0`. It releases a worktree only when every dispatch in the chain is finished (done or failed) and none is queued or active, `git status --porcelain` is empty, and after a fetch `git branch -r --contains HEAD` is not empty. Otherwise it keeps the worktree, records why, and `lobstah doctor`'s `disk` row shows `kept: unpushed work`; the next pass checks again. Uncommitted changes and unpushed commits are never deleted. A PR closed without merge releases nothing. A trap's worktree is never released. Branches (local and remote), `done/` entries, state, and evidence are kept; `lobstah catch` prints `worktree: released on merge (<time>)`. One `worktree-released` notice per pass lists what was released. |
@@ -217,6 +219,8 @@ send a continuation.
217
219
  | `codexStartSecs` | `600` | Seconds a Codex throw waits for sign-on and first park. Positive whole number; `man throw --timeout` overrides it. Other harnesses default to 180 seconds. A Codex timeout keeps its ticket valid for late sign-on and fences a duplicate launch; `stow --wt <trap>` withdraws it before retrying. |
218
220
  | `deferSecs` | `90` | A soaking session whose park heartbeat is this fresh holds unaddressed matching bait — the daemon waits instead of spawning. Addressed bait (`--for session:<id>`) waits regardless, until the registration is gone. |
219
221
  | `claimIdleNoticeSecs` | `180` | Grace period after a trap claims a dispatch before the daemon raises a `trap-claim-idle` notice if the worker has not reported. Fresh park or tool heartbeats do not acknowledge delivery. The notice does not release the claim; the original brief is re-delivered at the trap's next park, including after it resumes under a new session id. |
222
+ | `codexClaimWakeSecs` | `120` | After a Codex trap claims a dispatch and hasn't reported, the daemon wakes its session once: a turn on Codex's shared server, or a prompt typed into its tmux pane when that pane shows Codex's idle prompt. It tells the trap to run `soak --wait` in the foreground to receive the brief. A Codex session that ended its turn while its listener ran in the background never sees the brief otherwise. A cancel requested before the first report finalizes the dispatch at once. Positive whole number. |
223
+ | `codexClaimReleaseSecs` | `600` | How long after that wake a still-silent Codex trap keeps the claim. Then the dispatch goes back to the queue and the helm gets one `trap-claim-released` notice. Positive whole number. |
220
224
  | `acceptWharfStarts` | `false` | Opt this boat into helm-authorized trap start requests from the hosted glass. The daemon starts only its configured harness in a configured repo, refuses unknown repos, and never starts an expired request. Manual hosted `soak` and `man throw --new --repo` also use the daemon broker; traps receive only dispatch-scoped tokens. |
221
225
  | `ttlSecs` | `1800` | Heartbeat age past which a registration is a ghost trap: the sweep removes it and requeues an unfinished catch, finalizes done/failed in `done/`, or finalizes a cancelled catch as failed. A fresh `lobstah report` or beat counts as liveness. If the daemon's own tick gap exceeds this TTL, it grants a full TTL after resume before sweeping any traps. |
222
226
  | `beat` | `true` | The post-tool hook (`lobstah soak beat`) refreshes a soaking session's liveness and writes its catch's activity, at most once per 30 seconds per trap. With `false` the hook does nothing, and a trap's liveness comes from its reports and its park only. |
@@ -278,7 +282,7 @@ and posts the exit code, log path and last lines to the dispatch's inbox.
278
282
  | `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. |
279
283
  | `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. |
280
284
  | `timezone` | system timezone | IANA timezone (e.g. `America/New_York`) for daily goals, for reading todo times, and for when a done todo leaves `man tend` and the glass. A day starts at 04:00 local. |
281
- | `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. |
285
+ | `queuedNoticeSecs` | `180` | Queued age before a dispatch-progress notice wakes the helm with its queue reason and remedy. The pet and the glass show it only when `attentionKinds` names `dispatch-progress`. `0` disables. Reminders back off at 15, 45, 105… minutes after the threshold; claim clears the condition. |
282
286
  | `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. |
283
287
  | `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. |
284
288
  | `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. |
@@ -323,7 +327,7 @@ harness's blocking Stop-hook timeout too.
323
327
  | Key | Default | Meaning |
324
328
  |---|---|---|
325
329
  | `port` | `4949` | Localhost port for the glass. `LOBSTAH_GLASS_PORT` takes precedence. |
326
- | `mirror` | unset | A wharf in `[wharves]` that shows this machine's glass on its hosted glass. The fleet stays on its local grounds. The daemon puts the glass snapshot there (never the page token): within seconds of a change while a hosted glass is open, and every five minutes otherwise. It carries out on this glass, over loopback, the reads and writes a person makes there, except ↗ Open. Enroll with `lobstah wharf login --wharf <name> --mirror` (mirror and read access only), then `lobstah daemon restart`; `lobstah wharf whoami --wharf <name>` and `lobstah doctor` show how fresh the mirror is. Unset, nothing is sent. |
330
+ | `mirror` | unset | A wharf in `[wharves]` that shows this machine's glass on its hosted glass. The fleet stays on its local grounds. The daemon puts the glass snapshot there (never the page token): within seconds of a change while a hosted glass is open, and every five minutes otherwise. It carries out on this glass, over loopback, the reads and writes a person makes there, except ↗ Open. Enroll with `lobstah wharf login --wharf <name> --mirror` (mirror and read access only), or add `--attention` so this Mac's pet also walks every other mirror boat's items, then `lobstah daemon restart`; `lobstah wharf whoami --wharf <name>` and `lobstah doctor` show how fresh the mirror is. Unset, nothing is sent. |
327
331
 
328
332
  ## `[pet]` — report and decision clicks
329
333
 
@@ -481,7 +485,7 @@ key reused as the routing key. Opt-in is per repo, never implied. With no repo o
481
485
 
482
486
  | Key | Default | Meaning |
483
487
  |---|---|---|
484
- | `publish` | `false` (`true` for auto-review) | The glass draft/publish toggle, including on-demand jobs. Switching it changes auto-draft ↔ auto-review. Each job remembers whether publishing was enabled when it started. |
488
+ | `publish` | `false` (`true` for auto-review) | The glass draft/publish toggle, including on-demand jobs. Switching it changes auto-draft ↔ auto-review. Posting requires both the current mode and the job’s original publishing permission; lowering the mode applies to jobs already running. |
485
489
  | `identity` | required | The bot login work is assigned to / authored by. |
486
490
  | `repo` | single-repo mode | `owner/name`. Omit for multi-repo mode. |
487
491
  | `key` | single-repo mode | Lobstah repo key for dispatches and rebase chores. |
@@ -527,9 +531,12 @@ as that identity, with its token source, independently of `[pickup.github]`. Ide
527
531
  | `harness`, `model`, `effort` | repo, then `[harness]` | The review job's worker. |
528
532
  | `wallClockSecs`, `maxTurns`, `maxBudgetUsd` | `900`, `40`, unset | Cost bounds for one review job. |
529
533
  | `trapWaitSecs` | `600` | With `work = "trap"`: how long a job waits for a free trap. |
530
- | `maxPerDay` | `20` | Review jobs started per day. Past it, items file with no job. |
534
+ | `maxPerDay` | `20` | Review jobs lobstah starts on its own per day (UTC). Past it, automatic rounds file with no job and say how to start one by hand. A review you ask for (Draft on the glass, or a redraft) always runs, and counts toward the day's total. |
535
+ | `requestedAfter` | `"enabled"` | Requests before reviews were enabled or the repo switched to automatic mode stay in Reviews without a job. Set a quoted ISO timestamp to choose a different cutoff; repo overrides are supported. |
531
536
  | `skipAuthors`, `skipLabels` | `[]` | Requests on PRs by these authors or with these labels file an item but start no job. |
532
537
 
538
+ Setup records the activation time when settings change. For hand-edited settings, the next poll records the transition. Older requests remain available for an explicit Review action. Cancelling a review dispatch fails its round and stops the trap at its next tool hook; cancelled rounds cannot publish.
539
+
533
540
  Requests land silently in the Reviews inbox with a tab count, never on deck or tend. Draft-ready and automatic-published notifications use `[hooks.notify]` and the pet, with a `#review-<encoded key>` link to the row. The hook gets `LOBSTAH_NOTE`, `LOBSTAH_VERB` (`draft-ready`, `needs-you`, `published`) and `LOBSTAH_URL` / `LOBSTAH_GLASS_URL`. Opening marks seen; a row action clears the notification and needs-you marker. Wharf notification delivery is deferred.
534
541
 
535
542
  ## `[permissions]` — the Claude Code auto-mode profile
@@ -44,6 +44,16 @@ never uses `--dangerously-bypass-hook-trust`, edits saved trust, enables a
44
44
  disabled hook, or approves repo/user/other-plugin hooks. Those still require
45
45
  their normal review. Manually launched Codex sessions still use `/hooks`.
46
46
 
47
+ That trust covers the plugin as it was at launch. When the lobstah Codex
48
+ plugin's contents change, a running session refuses lobstah's hooks: the
49
+ transcript shows "Hook failed: plugin contents changed; hook approval
50
+ required", and the trap can no longer park or report liveness. The daemon
51
+ notices the change. For traps on Codex's shared server it refreshes the
52
+ trust in `~/.codex/config.toml`, which the server re-reads. Other traps were
53
+ trusted by launch flags that can't change while they run, so the helm gets
54
+ one `codex-hooks-stale` notice naming them. `lobstah stow --wt <id>` and then
55
+ `lobstah man throw <name>` resumes each with trust for the new plugin.
56
+
47
57
  ### On Codex's shared server
48
58
 
49
59
  `man throw --remote-control` starts a Codex trap with `--remote unix://`, attached
@@ -229,6 +239,16 @@ With no hook, run `lobstah man wait --session <task-id> --timeout 900` in
229
239
  the foreground and loop on it (exit 3 is a timeout). A trap listens with
230
240
  `lobstah soak --wait --timeout 600`.
231
241
 
242
+ Keep that listener in the foreground, with a yield time longer than its
243
+ timeout. Codex moves a command that outlasts its yield time to the
244
+ background. A background command that finishes after the turn ends starts
245
+ no new turn: when such a listener claims work, the brief it prints is lost
246
+ and the work sits claimed. The daemon wakes a trap in that state after
247
+ `[soak].codexClaimWakeSecs`. It takes a turn on the shared server, or types
248
+ a prompt into the trap's tmux pane when that pane shows Codex's idle prompt.
249
+ If the trap still doesn't report after `[soak].codexClaimReleaseSecs`, the
250
+ dispatch goes back to the queue.
251
+
232
252
  ## CLI vs desktop app
233
253
 
234
254
  Verified from a Codex desktop task on PR #48 and in #55:
package/docs/man.md CHANGED
@@ -189,9 +189,13 @@ worker's verb and note stay the primary line. `lobstah status <id>` prints
189
189
  the same line as `activity:`, and `lobstah ls` has an `activity` column. See
190
190
  [Activity](vocabulary.md#activity).
191
191
 
192
- A worker that waits on something outside lobstah (a ume review, a PR
193
- review, a deploy) reports `paused "<note>" --waiting-on review --link <url>`
194
- before it waits. Tend, `status`, `ls`, and the glass then show
192
+ A worker that waits on something outside lobstah (a ume review, a
193
+ deploy) reports `paused "<note>" --waiting-on review --link <url>`
194
+ before it waits. A trap never parks on its own PR's CI or review: once the
195
+ PR is up it reports `done --pr <url>`, which frees it, and the PR's watch
196
+ starts the next round on review feedback, a failing check or a merge. A
197
+ trap's `paused --waiting-on pr|review` about its own PR is recorded as
198
+ `done --pr`. Tend, `status`, `ls`, and the glass then show
195
199
  `paused: waiting on review` with the link and the time waited. It is a
196
200
  state, not a question: nothing to answer, no attention, no pet. A paused
197
201
  headless worker is never counted as wedged and its wall clock stops.
@@ -262,9 +266,16 @@ of the stack are recorded too:
262
266
 
263
267
  - a gh stack: the `gh-stack` state in the dispatch's checkout (from
264
268
  `gh stack init` or `gh stack submit`) lists a stack that holds the PR;
265
- - a base chain: the dispatch pushed two or more branches, and
266
- `gh pr view <branch>` links their PRs to the reported one by base
267
- branch.
269
+ - pushed branches: every branch recorded for the dispatch is checked for a
270
+ PR, including separate PRs outside the stack;
271
+ - observed stacks: the normal PR watch discovers both directions of an
272
+ owned branch chain and adds each member to the dispatch's evidence and
273
+ watches at the same cadence, without a second polling loop.
274
+
275
+ Stack positions are saved with the evidence, so retargeting after a squash
276
+ does not erase their order. Tracker reports and live status comments list
277
+ every PR with its position, and update when new PRs are found even if the
278
+ dispatch's status verb has not changed.
268
279
 
269
280
  The report prints `prs` with every PR it recorded. `lobstah catch` and
270
281
  `lobstah status <id>` list each PR (`prs`), `man tend` lists each with its
@@ -478,6 +489,28 @@ stack. When two PRs share a head branch, the parent is the one first seen
478
489
  last. The attention list is in standing order: the time each condition
479
490
  started. `observedAt` is shown as the time of the last check.
480
491
 
492
+ **Merge when green.** On the glass PRs tab, each open PR of yours has Merge
493
+ when green. A second tap names the merge (`Merge #12 into main as one
494
+ squashed commit`) and stores the request on the PR record. The boat refuses
495
+ a PR it has no record of (404), one that isn't open (409), and one that is
496
+ neither authored by the login `gh` signs in as nor opened by a dispatch
497
+ (403). Each PR-watch tick, the daemon takes each request in turn:
498
+
499
+ - A green PR that GitHub calls clean, with no open PR below it in its stack,
500
+ merges with `gh pr merge --<method> --match-head-commit <head>`. A refused
501
+ merge is tried again on the next tick.
502
+ - A conflicting PR, or one with failing checks, is repaired first. A
503
+ dispatch's PR already has its PR repair. For a PR no dispatch opened, the
504
+ daemon queues one repair dispatch per head, which pushes to that PR's
505
+ branch; once it reports the PR, the repair chain takes later rounds.
506
+ - When a PR's repair stops at a head, the helm gets one `repair-stopped`
507
+ notice for that head.
508
+ - Drafts and running checks wait. A merged or closed PR drops its request.
509
+
510
+ Cancel withdraws the request. The method is the repo's
511
+ [`mergeMethod`](configuration.md#reposkey--workspace-definitions), else
512
+ `[pickup.github.merge].method`, else squash.
513
+
481
514
  An observed PR joins tend's attention list by kind. `pr:ready` needs a
482
515
  mergeable, non-draft PR with no failed, pending, or unknown current checks.
483
516
  `pr:conflict` and `pr:checks` appear for an owned PR only when repair is off,
@@ -775,6 +808,36 @@ the same rule.
775
808
  the retention window, with the `decision-answer` request and its files. A
776
809
  standing decision is never culled.
777
810
 
811
+ ### Run cards
812
+
813
+ When the human must run a command on this machine, save it in a script and
814
+ offer a run card. Use plain cards for steps the glass cannot run, such as
815
+ app clicks or phone sign-ins. For a package publish, save the commands in
816
+ `/tmp/publish.sh` and offer the script.
817
+
818
+ ```sh
819
+ lobstah man ask --title "Publish the package" --run /tmp/publish.sh \
820
+ --interactive --cwd /path/to/package --timeout 10m --output exit
821
+ ```
822
+
823
+ Use `--input NAME:secret` for secrets (values via stdin, never in the script),
824
+ `--interactive` for logins/prompts, `--cwd` for the working folder,
825
+ `--timeout` for the time limit, and `--output scrubbed|exit` for the result.
826
+ The person reviews and runs the script from the glass. Scripts read declared
827
+ inputs from stdin, one line each in `--input` order. `scrubbed` returns
828
+ scrubbed output to the helm. `exit` returns only the exit code. The output
829
+ reads as a terminal showed it: redrawn lines, spinners and answered prompts
830
+ collapse to their final text, and no escape code remains. The card in the
831
+ glass keeps the colors, and the run's `output.log` keeps the raw stream.
832
+
833
+ From the phone: a Mac that mirrors to a hosted glass runs its cards from
834
+ there too. Run `lobstah run passkey add --hosted` on the Mac, open the link it
835
+ prints on the phone within 5 minutes, and tap Pair. Then press Run on the card
836
+ on the hosted glass: the phone's passkey confirms it, and covers 15 minutes of
837
+ runs on that page. Secret inputs, and every line typed into an interactive
838
+ run, are sealed to the Mac, so the wharf can't read them. Only the page that
839
+ started an interactive run can type into it.
840
+
778
841
  ### The periodic report
779
842
 
780
843
  `lobstah man tend` is the full picture on demand; `lobstah man report` is the
@@ -910,13 +973,28 @@ not). The pet also hides the clicked item itself until its state changes, so
910
973
  an ack that times out does not leave it walking. The ack changes only what the pet and the glass lobs display:
911
974
  `man tend --json` still lists the item (marked `acked`), and `man wait`, the
912
975
  park, and reminders ignore acks entirely — a human having seen a question
913
- must never hide it from the orchestrator that has to answer it. The glass,
914
- which has no write endpoint, hides a clicked lob per browser in localStorage
915
- instead.
976
+ must never hide it from the orchestrator that has to answer it. Clicking a
977
+ glass lob acknowledges its item the same way, through the page's guarded
978
+ `attention-ack` request (`by: glass`), so it stops walking on the pet and on
979
+ every glass. It names the item's key and the `stateHash` the page showed, so
980
+ it acks nothing newer. That browser also hides the lob at once. A review
981
+ notification is acknowledged on its review. An item of a grounds on a wharf
982
+ is acknowledged on that wharf, so every boat agrees. On the hosted glass, a
983
+ click on a boat's row is relayed to that boat, and a click on the wharf's own
984
+ grounds acks it on the wharf.
916
985
 
917
986
  **The pet's read.** Every six seconds the pet runs `lobstah attention --json`.
918
987
  It prints `{ "attention": [...] }`: the same items, with the same fields, that
919
- `man tend --json` puts under `attention`, and nothing else. If that command
988
+ `man tend --json` puts under `attention`, and nothing else. On a Mac that
989
+ mirrors to a wharf with the `attention` grant
990
+ (`lobstah wharf login --wharf <name> --mirror --attention`), it also lists
991
+ every other mirror boat's items, as the hosted glass shows them. Each one's
992
+ key is `@<boat id>/<its own key>` and its note starts with `[<boat name>]`. A
993
+ click opens it on the hosted glass, and its ack goes through the wharf to the
994
+ boat that owns it. The daemon puts this boat's list on the wharf when an item
995
+ changes, on its 30 s mirror pass. It reads the others when the wharf says one
996
+ changed, and every 5 minutes. Another boat's item reaches this pet within
997
+ about 30 seconds. A PR or stack that two boats watch walks once. If that command
920
998
  fails (an older CLI exits 2 on the unknown flag), the pet runs
921
999
  `man tend --json` instead. The pet reads the child's output while the child
922
1000
  runs, so a report of any size works. Each read may take 10 seconds; then the
@@ -1320,14 +1398,35 @@ lobstah man roster set <trap> --harness codex --model <m> --terminal iterm --con
1320
1398
  lobstah man throw <trap> [--timeout <secs>] # bring one trap back; wait until it listens
1321
1399
  lobstah man throw <trap> --bypass # a person, at a terminal: this start skips permission checks
1322
1400
  lobstah man throw <trap> --remote-control # this start can be driven from a phone: Claude's Remote Control, or Codex's shared server
1401
+ lobstah man throw <trap> --stop-stale # a leftover Codex process still holds the trap's thread: stop it, then throw
1323
1402
  lobstah man throw --all # every eligible trap in your grounds, at once
1324
1403
  lobstah man throw --repo <key> # every eligible trap of one repo
1325
1404
  lobstah man throw --new --repo <key> --count N # N fresh traps (see "Starting a new trap")
1326
1405
  lobstah man throw --dry-run <trap>... | --all | --repo <key> | --new ...
1327
1406
  # what a throw would do; launches nothing (--plan too)
1328
1407
  lobstah man roster forget <trap> [--force] # remove a stowed trap's record, worktree, and ref
1408
+ lobstah man tidy-panes [--apply] # dead panes and duplicate or leftover Codex panes on lobstah's tmux server
1329
1409
  ```
1330
1410
 
1411
+ Codex lets one process write a thread. Another Codex on the same thread
1412
+ shows "This conversation is open in another app" and never takes a turn.
1413
+ When a throw finds a leftover Codex process holding the trap's thread, it
1414
+ names the process and refuses; `--stop-stale` stops it first. Only processes
1415
+ holding that thread's writer lock are stopped, and never one a signed-on trap
1416
+ runs in. When the daemon sweeps a ghosted Codex trap, it stops the trap's own
1417
+ Codex process too, once it confirms the process still holds the thread.
1418
+
1419
+ `man tidy-panes` lists what it would tidy on lobstah's tmux server; `--apply`
1420
+ does it. Each trap keeps one Codex pane: the one it recorded at sign-on.
1421
+ - A dead pane closes.
1422
+ - Another Codex pane named for a live trap is a duplicate: its Codex stops
1423
+ and the pane closes.
1424
+ - A Codex pane named for a trap that is no longer signed on is a leftover,
1425
+ and is tidied the same way.
1426
+ - A pane whose Codex holds the writer lock of a live trap's thread stays,
1427
+ whatever its title says.
1428
+ - Panes running anything but Codex are left alone.
1429
+
1331
1430
  `man throw --remote-control` makes one start reachable from a phone, new
1332
1431
  (`--new`) or returning. A Codex trap attaches to Codex's shared app-server, so its
1333
1432
  pane and a paired phone drive one thread. Other traps are unchanged unless
package/docs/pickup.md CHANGED
@@ -152,7 +152,9 @@ arrives while the previous one runs buffers until it finishes — and each
152
152
  round sets `followUp` to the latest session in the chain (the previous
153
153
  round, else the implementation dispatch), so feedback lands on the context
154
154
  that made the choices; a fully culled chain starts cold and reads the thread
155
- like anyone else. A rebase chore starts cold on purpose — the conflict is
155
+ like anyone else. A round or implementation paused waiting on `review` or
156
+ `pr` counts as finished here: it waits for exactly this feedback, so the
157
+ feedback starts the next round. Paused on anything else, it still holds. A rebase chore starts cold on purpose — the conflict is
156
158
  about commits the original session never saw.
157
159
 
158
160
  ### Claiming
@@ -290,8 +292,11 @@ approves, requests changes, comments, or pushes. When the job reports done,
290
292
  the round is `drafted`, or `stale` if the head moved meanwhile, or `failed`
291
293
  with the reason when the files are missing or malformed. A skip rule, a PR
292
294
  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
+ (UTC) leave the round `requested` with the reason. The daily cap stops only
296
+ the jobs lobstah starts on its own: a round you ask for (Draft on the
297
+ glass's Reviews tab, or a redraft) always starts, and counts toward the
298
+ day's total. `lobstah reviews redraft <key>` drafts a stale or failed round
299
+ again at the current head, on the next pick cycle, in any mode.
295
300
 
296
301
  **Staging and posting.** With `mode = "auto-draft"` or `publish = false` for an on-demand job, a
297
302
  fresh draft is staged on the PR as the identity's **pending review**:
@@ -368,9 +373,18 @@ The loop's doctrine, in full:
368
373
  new push invalidates it and the gate waits for a fresh one.
369
374
  When an approval no longer covers the head, pickup re-requests review from
370
375
  that approver once per push.
371
- - **Stacks merge through the forge's stack-aware path.** A PR in a native
372
- stack goes through GitHub's asynchronous stack merge API; a standalone PR
373
- through the ordinary merge call. `method` is per repo and applies to both.
376
+ - **Stacks merge into the default branch.** For ordinary branch stacks,
377
+ pickup merges the bottom PR first. It then retargets the next PR to the
378
+ default branch, merges that branch into the head with GitHub's
379
+ `update-branch` API, and waits for current-head checks and approval.
380
+ It never rebases or force-pushes this transition. A conflict or red check
381
+ stops the stack and posts a `stack-stopped` notice.
382
+ - **GitHub-linked stacks use the asynchronous API.** Membership comes from
383
+ GitHub's `stack` resource, not branch names. Once every open member passes
384
+ the gate, pickup calls `PUT pulls/<top>/merge-async` and saves the request
385
+ id. Later ticks poll the result; queued or pending does not mean merged.
386
+ Missing, branching or out-of-scope members hold the stack.
387
+ `method` remains per repo for both paths.
374
388
  - **`scope = "own"` is the safety default.** Pickup merges work it dispatched.
375
389
  Widening to human-authored PRs is a deliberate config change.
376
390
 
@@ -381,7 +395,8 @@ A PR behind its base splits deterministically:
381
395
  | Condition | Action |
382
396
  |---|---|
383
397
  | Behind, no conflict | Update the branch through the forge API, re-enter the gate next tick |
384
- | Behind, real conflict | Write a rebase chore — resolve, push to the PR's branch, report `done` — then re-enter the gate, which re-requests stale review once per head |
398
+ | Stack transition, conflict or red check | Stop and report; wait for a normal resolution push |
399
+ | Standalone PR, real conflict | Write a rebase chore — resolve, push to the PR's branch, report `done` — then re-enter the gate, which re-requests stale review once per head |
385
400
 
386
401
  Rebase chores go through the **chore lane** (`~/.lobstah/chores/`, defined in
387
402
  the [design's queue contract](design.md#queue-contract)), never the primary queue. Same descriptor schema,
@@ -583,7 +583,7 @@ reminder loop apply the same predicate.
583
583
 
584
584
  | Word | Meaning |
585
585
  | ---- | ------- |
586
- | ack | `~/.lobstah/acks/<item-key>.json` — `{ key, kind, stateHash, at, by }`, written only by `lobstah attention ack` (removed by `unack`, by the CLI's `man tend` / `attention` when its `stateHash` goes stale, and by `cull` when the item is gone). **Display-only**: it hides the item from the desktop pet and the glass lobs while the item's `stateHash` is unchanged; `man tend --json` keeps the item with `acked: { at, by }`, and `man wait`, the park, reminders, and `[hooks.notify]` never read acks. Item keys: `<lane>:<uuid>` (question, landed), `decision:<rid>`, `pr:<owner>/<repo>#<n>` (all of a PR's `pr:*` kinds — one ack covers them), `watch:<key>`. `stateHash` covers the status entry (question, landed) or the PR's head sha plus every evidence field a `pr:*` kind stands on (not `observedAt`); for a ready PR, only the head sha. A ready ack is kept across same-head CI flaps and draft toggles, without hiding checks, conflicts, or review attention during the flap. A new head re-stands ready once after settling. |
586
+ | ack | `~/.lobstah/acks/<item-key>.json` — `{ key, kind, stateHash, at, by }`, written only by `lobstah attention ack` and the glass's guarded `pr-ack` and `attention-ack` requests (a lob click; `by: glass`) (removed by `unack`, by the CLI's `man tend` / `attention` when its `stateHash` goes stale, and by `cull` when the item is gone). **Display-only**: it hides the item from the desktop pet and the glass lobs while the item's `stateHash` is unchanged; `man tend --json` keeps the item with `acked: { at, by }`, and `man wait`, the park, reminders, and `[hooks.notify]` never read acks. Item keys: `<lane>:<uuid>` (question, landed), `decision:<rid>`, `pr:<owner>/<repo>#<n>` (all of a PR's `pr:*` kinds — one ack covers them), `watch:<key>`. `stateHash` covers the status entry (question, landed) or the PR's head sha plus every evidence field a `pr:*` kind stands on (not `observedAt`); for a ready PR, only the head sha. A ready ack is kept across same-head CI flaps and draft toggles, without hiding checks, conflicts, or review attention during the flap. A new head re-stands ready once after settling. |
587
587
  | pet state | `~/.lobstah/pet/state.json` — `{ pid, at, ok, command, reason, consecutiveFailures, items, lastOkAt }`. The desktop pet's one write: it rewrites the file after each attention read (about every six seconds). `command` is the command that worked (`attention --json`, or `man tend --json` from an older CLI). `reason` says why the last read failed (timed out, non-zero exit, output that does not decode). Only `lobstah doctor` reads it, for its `pet` row: running means `pid` is alive and `at` is less than two minutes old. |
588
588
  | budget stop | A headless runner's `failed` verb with a `budget:` note means its progress-extended active-work window reached the hard ceiling. This is out of time, not a code failure: the runner checkpoints eligible changes, pushes when enabled, names the saved branch/commit/draft PR, and invites `lobstah send <id> "continue"`. Paused `--waiting-on` time is excluded. |
589
589
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lobstah",
3
- "version": "0.8.7",
3
+ "version": "0.8.9",
4
4
  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
5
5
  "license": "MIT",
6
6
  "author": "aequitas labs LLC",