lobstah 0.8.11 → 0.8.13

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
@@ -3277,6 +3277,7 @@ var DEFAULT_REVIEWS = {
3277
3277
  repos: "configured",
3278
3278
  work: "off",
3279
3279
  post: "draft",
3280
+ harness: "codex",
3280
3281
  limits: { wallClockSecs: 900, maxTurns: 40 },
3281
3282
  trapWaitSecs: 600,
3282
3283
  maxPerDay: 20,
@@ -3362,7 +3363,7 @@ function parseReviews(raw, reposRaw = {}) {
3362
3363
  ...base,
3363
3364
  mode,
3364
3365
  publish,
3365
- work: mode.startsWith("auto-") ? base.work && base.work !== "off" ? base.work : "trap" : "off",
3366
+ work: base.work && base.work !== "off" ? base.work : mode.startsWith("auto-") ? "headless" : "off",
3366
3367
  post: publish ? "auto" : "draft",
3367
3368
  ...Object.fromEntries(["identity", "tokenCommand", "tokenEnv", "tokenFile"].filter((k) => r[k] !== void 0).map((k) => [k, String(r[k])])),
3368
3369
  limits: { ...DEFAULT_REVIEWS.limits, ...base.limits },
@@ -3392,6 +3393,16 @@ function parseHarness(raw, where) {
3392
3393
  for (const harness of ["claude", "codex"]) {
3393
3394
  parsePermissionDefaults(defaults[harness], `${where.slice(0, -1)}.${harness}]`);
3394
3395
  }
3396
+ const codex = defaults?.codex;
3397
+ if (codex?.cli_path !== void 0 && (typeof codex.cli_path !== "string" || !codex.cli_path.trim())) {
3398
+ throw new Error(`${where.slice(0, -1)}.codex].cli_path must be a non-empty string`);
3399
+ }
3400
+ if (codex?.headless_sandbox !== void 0 && codex.headless_sandbox !== "workspace-write" && codex.headless_sandbox !== "danger-full-access") {
3401
+ throw new Error(`${where.slice(0, -1)}.codex].headless_sandbox must be "workspace-write" or "danger-full-access"`);
3402
+ }
3403
+ if (codex?.headless_model !== void 0 && (typeof codex.headless_model !== "string" || !codex.headless_model.trim())) {
3404
+ throw new Error(`${where.slice(0, -1)}.codex].headless_model must be a non-empty string`);
3405
+ }
3395
3406
  return defaults;
3396
3407
  }
3397
3408
  var POOL_NAME = /^[A-Za-z0-9_-]+$/;
@@ -3784,9 +3795,14 @@ function resolveDispatch(d, cfg) {
3784
3795
  throw new Error(`unknown repo key "${d.repo}" \u2014 add it to ${configPath()}`);
3785
3796
  const rh = repo.harness ?? {};
3786
3797
  const gh = cfg.harness;
3798
+ const harness = d.harness ?? rh.default ?? gh.default ?? "claude";
3787
3799
  return {
3788
- harness: d.harness ?? rh.default ?? gh.default ?? "claude",
3789
- model: d.model ?? rh.model ?? gh.model,
3800
+ harness,
3801
+ ...harness === "codex" ? {
3802
+ codexSandbox: rh.codex?.headless_sandbox ?? gh.codex?.headless_sandbox ?? "workspace-write",
3803
+ codexCliPath: rh.codex?.cli_path ?? gh.codex?.cli_path
3804
+ } : {},
3805
+ model: d.model ?? (harness === "codex" ? rh.codex?.headless_model ?? gh.codex?.headless_model : void 0) ?? rh.model ?? gh.model,
3790
3806
  effort: d.effort ?? rh.effort ?? gh.effort,
3791
3807
  limits: {
3792
3808
  wallClockSecs: cfg.limits.wallClockSecs,
@@ -3995,8 +4011,8 @@ function resolveOnPath(bin, pathVar = process.env.PATH) {
3995
4011
  function onPath(bin, pathVar = process.env.PATH) {
3996
4012
  return resolveOnPath(bin, pathVar) !== void 0;
3997
4013
  }
3998
- function codexInvocation(argv) {
3999
- if (onPath("codex"))
4014
+ function codexInvocation(argv, pathVar = process.env.PATH) {
4015
+ if (onPath("codex", pathVar))
4000
4016
  return { file: "codex", argv };
4001
4017
  const require_ = createRequire(import.meta.url);
4002
4018
  try {
@@ -4209,7 +4225,7 @@ var AsyncQueue = class {
4209
4225
  return Promise.resolve({ value: item, done: false });
4210
4226
  if (this.closed)
4211
4227
  return Promise.resolve({ value: void 0, done: true });
4212
- return new Promise((resolve12) => this.waiters.push(resolve12));
4228
+ return new Promise((resolve13) => this.waiters.push(resolve13));
4213
4229
  }
4214
4230
  };
4215
4231
  }
@@ -4234,7 +4250,7 @@ var InputGate = class {
4234
4250
  return msg;
4235
4251
  if (this.ended)
4236
4252
  return void 0;
4237
- await new Promise((resolve12) => this.waiter = resolve12);
4253
+ await new Promise((resolve13) => this.waiter = resolve13);
4238
4254
  this.waiter = null;
4239
4255
  }
4240
4256
  }
@@ -4379,20 +4395,20 @@ function startClaudeCli(invocation, opts) {
4379
4395
  }
4380
4396
  }
4381
4397
  });
4382
- const done = new Promise((resolve12) => {
4398
+ const done = new Promise((resolve13) => {
4383
4399
  child.on("error", (err) => {
4384
4400
  events.push({ at: now(), type: "error", data: { message: err.message } });
4385
4401
  events.close();
4386
- resolve12({ sessionId, error: err.message });
4402
+ resolve13({ sessionId, error: err.message });
4387
4403
  });
4388
4404
  child.on("exit", (code2) => {
4389
4405
  events.close();
4390
4406
  if (code2 === 0)
4391
- resolve12({ sessionId });
4407
+ resolve13({ sessionId });
4392
4408
  else {
4393
4409
  const detail = stderrTail.trim().split("\n").at(-1);
4394
4410
  const error = `claude exited ${code2}${detail ? ` \u2014 ${detail}` : ""}`;
4395
- resolve12({ sessionId, error });
4411
+ resolve13({ sessionId, error });
4396
4412
  }
4397
4413
  });
4398
4414
  });
@@ -4474,7 +4490,39 @@ function createClaudeAdapter() {
4474
4490
  import * as fs36 from "node:fs";
4475
4491
  import * as os5 from "node:os";
4476
4492
  import * as path30 from "node:path";
4477
- import { spawn as spawn2 } from "node:child_process";
4493
+ import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
4494
+ function resolveCodexCli(opts) {
4495
+ if (opts.codexCliPath !== void 0) {
4496
+ const file2 = path30.resolve(opts.cwd, opts.codexCliPath);
4497
+ try {
4498
+ fs36.accessSync(file2, fs36.constants.X_OK);
4499
+ if (!fs36.statSync(file2).isFile())
4500
+ throw new Error("not a file");
4501
+ } catch {
4502
+ throw new Error(`Codex CLI is not executable: ${file2}. Check [harness.codex].cli_path.`);
4503
+ }
4504
+ return file2;
4505
+ }
4506
+ const found = spawnSync3(process.platform === "win32" ? "where.exe" : "which", ["codex"], {
4507
+ cwd: opts.cwd,
4508
+ env: { ...process.env, ...opts.env },
4509
+ encoding: "utf8",
4510
+ timeout: 1e4
4511
+ });
4512
+ if (found.status === 0) {
4513
+ const files = found.stdout.trim().split(/\r?\n/);
4514
+ const file2 = process.platform === "win32" ? files.find((file3) => /\.(exe|com|cmd|bat)$/i.test(file3)) : files[0];
4515
+ if (file2)
4516
+ return path30.resolve(opts.cwd, file2);
4517
+ }
4518
+ if (found.error) {
4519
+ const file2 = resolveOnPath("codex", opts.env.PATH ?? process.env.PATH);
4520
+ if (file2)
4521
+ return path30.resolve(opts.cwd, file2);
4522
+ }
4523
+ console.warn("No codex CLI found on PATH; using the bundled CLI. Set [harness.codex].cli_path to choose a CLI.");
4524
+ return void 0;
4525
+ }
4478
4526
  function isolatedCodexHome() {
4479
4527
  const dir = path30.join(lobstahHome(), "codex-home");
4480
4528
  fs36.mkdirSync(dir, { recursive: true });
@@ -4493,10 +4541,22 @@ function isolatedCodexHome() {
4493
4541
  }
4494
4542
  return dir;
4495
4543
  }
4496
- function heavyLineDir() {
4497
- const dir = heavyDir();
4498
- fs36.mkdirSync(dir, { recursive: true });
4499
- return dir;
4544
+ function codexWritableDirectories(opts) {
4545
+ const dirs = [opts.env.LOBSTAH_HOME ?? lobstahHome()];
4546
+ for (const dir of dirs)
4547
+ fs36.mkdirSync(dir, { recursive: true });
4548
+ return dirs;
4549
+ }
4550
+ function codexThreadOptions(opts) {
4551
+ return {
4552
+ workingDirectory: opts.cwd,
4553
+ skipGitRepoCheck: true,
4554
+ sandboxMode: opts.codexSandbox ?? "workspace-write",
4555
+ additionalDirectories: codexWritableDirectories(opts),
4556
+ approvalPolicy: "never",
4557
+ ...opts.model ? { model: opts.model } : {},
4558
+ ...opts.effort ? { modelReasoningEffort: opts.effort } : {}
4559
+ };
4500
4560
  }
4501
4561
  function pumpCodexEvent(ev, push, onSession) {
4502
4562
  const at = now();
@@ -4529,13 +4589,18 @@ function pumpCodexEvent(ev, push, onSession) {
4529
4589
  }
4530
4590
  function codexExecArgs(opts, prompt, resumeThread) {
4531
4591
  const args = ["exec"];
4532
- if (resumeThread)
4533
- args.push("resume", resumeThread);
4534
- args.push("--json", "--skip-git-repo-check", "--sandbox", "workspace-write", "--add-dir", heavyLineDir(), "--cd", opts.cwd);
4592
+ args.push("--json", "--skip-git-repo-check");
4593
+ if (opts.codexSandbox === "danger-full-access")
4594
+ args.push("--dangerously-bypass-approvals-and-sandbox");
4595
+ else
4596
+ args.push("--sandbox", "workspace-write", ...codexWritableDirectories(opts).flatMap((dir) => ["--add-dir", dir]));
4597
+ args.push("-c", 'approval_policy="never"', "--cd", opts.cwd);
4535
4598
  if (opts.model)
4536
4599
  args.push("-m", opts.model);
4537
4600
  if (opts.effort)
4538
4601
  args.push("-c", `model_reasoning_effort=${JSON.stringify(opts.effort)}`);
4602
+ if (resumeThread)
4603
+ args.push("resume", resumeThread);
4539
4604
  args.push(prompt);
4540
4605
  return args;
4541
4606
  }
@@ -4546,7 +4611,7 @@ function startCodexCli(invoke, opts) {
4546
4611
  let current;
4547
4612
  let killed = false;
4548
4613
  function runTurn(prompt, resumeThread) {
4549
- return new Promise((resolve12) => {
4614
+ return new Promise((resolve13) => {
4550
4615
  const inv = invoke(codexExecArgs(opts, prompt, resumeThread));
4551
4616
  const child = spawn2(inv.file, inv.argv, {
4552
4617
  cwd: opts.cwd,
@@ -4577,14 +4642,14 @@ function startCodexCli(invoke, opts) {
4577
4642
  }
4578
4643
  }
4579
4644
  });
4580
- child.on("error", (err) => resolve12(err.message));
4645
+ child.on("error", (err) => resolve13(err.message));
4581
4646
  child.on("exit", (code2) => {
4582
4647
  if (turnError)
4583
- return resolve12(turnError);
4648
+ return resolve13(turnError);
4584
4649
  if (code2 === 0 || killed)
4585
- return resolve12(void 0);
4650
+ return resolve13(void 0);
4586
4651
  const detail = stderrTail.trim().split("\n").at(-1);
4587
- resolve12(`codex exited ${code2}${detail ? ` \u2014 ${detail}` : ""}`);
4652
+ resolve13(`codex exited ${code2}${detail ? ` \u2014 ${detail}` : ""}`);
4588
4653
  });
4589
4654
  });
4590
4655
  }
@@ -4626,27 +4691,27 @@ function createCodexAdapter() {
4626
4691
  return {
4627
4692
  name: "codex",
4628
4693
  async start(opts) {
4694
+ const cliPath = resolveCodexCli(opts);
4695
+ if (cliPath && process.platform === "win32" && /\.(cmd|bat)$/i.test(cliPath)) {
4696
+ return startCodexCli((argv) => ({ file: cliPath, argv }), opts);
4697
+ }
4629
4698
  let mod;
4630
4699
  try {
4631
4700
  mod = await import("@openai/codex-sdk");
4632
4701
  } catch (err) {
4633
- if (codexInvocation([]))
4634
- return startCodexCli((argv) => codexInvocation(argv), opts);
4702
+ if (cliPath)
4703
+ return startCodexCli((argv) => ({ file: cliPath, argv }), opts);
4704
+ const bundled = codexInvocation([], "");
4705
+ if (bundled)
4706
+ return startCodexCli((argv) => ({ file: bundled.file, argv: [...bundled.argv, ...argv] }), opts);
4635
4707
  const detail = err instanceof Error ? err.message : String(err);
4636
4708
  throw new Error(`codex adapter: SDK unavailable (${detail}) and no codex CLI found (PATH or vendored)`);
4637
4709
  }
4638
4710
  const codex = new mod.Codex({
4711
+ ...cliPath ? { codexPathOverride: cliPath } : {},
4639
4712
  env: { ...process.env, ...opts.env, CODEX_HOME: isolatedCodexHome() }
4640
4713
  });
4641
- const threadOptions = {
4642
- workingDirectory: opts.cwd,
4643
- skipGitRepoCheck: true,
4644
- sandboxMode: "workspace-write",
4645
- additionalDirectories: [heavyLineDir()],
4646
- approvalPolicy: "never",
4647
- ...opts.model ? { model: opts.model } : {},
4648
- ...opts.effort ? { modelReasoningEffort: opts.effort } : {}
4649
- };
4714
+ const threadOptions = codexThreadOptions(opts);
4650
4715
  const thread = opts.resumeSession ? codex.resumeThread(opts.resumeSession, threadOptions) : codex.startThread(threadOptions);
4651
4716
  const input = new InputGate();
4652
4717
  const events = new AsyncQueue();
@@ -5377,7 +5442,7 @@ async function* until(source, stop) {
5377
5442
  yield next.value;
5378
5443
  }
5379
5444
  }
5380
- var sleep = (ms) => new Promise((resolve12) => setTimeout(resolve12, ms));
5445
+ var sleep = (ms) => new Promise((resolve13) => setTimeout(resolve13, ms));
5381
5446
  function deliver(run3, id, lane) {
5382
5447
  const msgs = unhandled(id, lane);
5383
5448
  for (const m of msgs) {
@@ -5423,7 +5488,7 @@ async function drive(run3, opts) {
5423
5488
  let finalAt = 0;
5424
5489
  let exit;
5425
5490
  let abandon;
5426
- const abandoned = new Promise((resolve12) => abandon = resolve12);
5491
+ const abandoned = new Promise((resolve13) => abandon = resolve13);
5427
5492
  const clearExit = () => {
5428
5493
  if (!exit) return;
5429
5494
  clearInterval(exit.poll);
@@ -5924,7 +5989,7 @@ var defaultDeps = {
5924
5989
  var DONE_WAIT_MS = 2e3;
5925
5990
  function within(p, ms, fallback) {
5926
5991
  let timer;
5927
- const late = new Promise((resolve12) => timer = setTimeout(() => resolve12(fallback), ms));
5992
+ const late = new Promise((resolve13) => timer = setTimeout(() => resolve13(fallback), ms));
5928
5993
  return Promise.race([p, late]).finally(() => clearTimeout(timer));
5929
5994
  }
5930
5995
  var short3 = (s) => s.slice(0, 8);
@@ -6028,7 +6093,7 @@ async function main(activeDir, lane, seams = {}) {
6028
6093
  choice3 ? choice3.reuse ? `reusing worktree of ${short3(choice3.from)}` : `fresh worktree (${choice3.reason})` : recovered ? "recovered own unrecorded worktree" : void 0,
6029
6094
  poolNote
6030
6095
  ].filter(Boolean).join("; ") || void 0;
6031
- const firstModel = modelForHarness(plan.harness, resolved.model);
6096
+ const firstModel = modelForHarness(plan.harness, resolveDispatch({ ...descriptor, harness: plan.harness }, cfg).model);
6032
6097
  const firstNote = [
6033
6098
  wake ? `woke from pause: ${wake}` : attempts > 1 ? `attempt ${attempts}` : void 0,
6034
6099
  plan.note,
@@ -6172,19 +6237,22 @@ async function main(activeDir, lane, seams = {}) {
6172
6237
  return;
6173
6238
  }
6174
6239
  const runOnce = async (harness, prompt, resumeSession) => {
6240
+ const launch = resolveDispatch({ ...descriptor, harness }, cfg);
6175
6241
  const explicit = resolved.flags.length === 0;
6176
6242
  mergeEvidence(id, lane, { worker: workerMetadata({
6177
6243
  harness,
6178
6244
  observedAt: (/* @__PURE__ */ new Date()).toISOString(),
6179
- model: explicit ? modelForHarness(harness, resolved.model).model : void 0,
6245
+ model: explicit ? modelForHarness(harness, launch.model).model : void 0,
6180
6246
  config: { effort: explicit ? resolved.effort : null, permissionMode: explicit && harness === "claude" ? "bypassPermissions" : null }
6181
6247
  }) });
6182
6248
  const run3 = await deps.loadAdapter(harness).start({
6183
6249
  id,
6184
6250
  cwd,
6185
6251
  prompt,
6186
- model: modelForHarness(harness, resolved.model).model,
6252
+ model: modelForHarness(harness, launch.model).model,
6187
6253
  effort: resolved.effort,
6254
+ codexSandbox: launch.codexSandbox,
6255
+ codexCliPath: launch.codexCliPath,
6188
6256
  limits: resolved.limits,
6189
6257
  env: {
6190
6258
  ...resolved.env,
@@ -181,6 +181,28 @@ Call out migrations that are not reversible.
181
181
  Same four keys as the per-repo block. Precedence for every harness setting:
182
182
  **descriptor > repo > global > adapter default.**
183
183
 
184
+ ### `[harness.codex]` — headless Codex
185
+
186
+ These settings affect SDK and `codex exec` jobs only. Interactive traps keep
187
+ using their existing model and permission settings. These settings also work in
188
+ `[repos.<key>.harness.codex]`; repo settings override global settings.
189
+
190
+ | Key | Default | Meaning |
191
+ |---|---|---|
192
+ | `headless_sandbox` | `"workspace-write"` | `"workspace-write"` allows the checkout and lobstah reporting directory. `"danger-full-access"` disables the sandbox and approval prompts, allowing network access and writes outside the checkout, including tool caches and `~/.ume`. |
193
+ | `headless_model` | unset | Model for headless Codex jobs. An explicit dispatch model wins, then the repo headless model, global headless model, and ordinary repo/global model defaults. Must be a non-empty string. |
194
+ | `cli_path` | `which codex` | Executable path for headless Codex jobs, including SDK runs. A repo value overrides the global value. Relative paths resolve from the job's working directory. If unset and no Codex is on PATH, lobstah warns and uses the bundled CLI, which may support fewer models. An invalid explicit path fails the job. |
195
+
196
+ ```toml
197
+ [harness.codex]
198
+ headless_sandbox = "danger-full-access"
199
+ headless_model = "gpt-6.1-sol"
200
+ ```
201
+
202
+ Headless Codex uses a lobstah-managed `CODEX_HOME` with inherited auth and
203
+ an isolated config. Interactive MCP servers and session/Stop hooks are not
204
+ loaded; the runner handles reports, waits, and job completion.
205
+
184
206
  ## `[limits]`
185
207
 
186
208
  | Key | Default | Meaning |
@@ -530,15 +552,17 @@ as that identity, with its token source, independently of `[pickup.github]`. Ide
530
552
  | `autoPostRequestChanges` | `"ask"` | `"ask"`: wait for a person to post a request-changes draft; `"auto-post"`: post it automatically when the configured reviewer identity matches the GitHub token. |
531
553
  | `identity` | `gh api user` | The reviewer login. |
532
554
  | `tokenCommand`, `tokenFile`, `tokenEnv` | `gh auth token` | Token sources, using the same precedence as pickup. |
533
- | `work` | legacy | `"off"` maps to on-demand, `"trap"`/`"headless"` map to auto-draft; explicit mode wins. The worker choice still applies to automatic jobs. |
555
+ | `work` | `"headless"` for drafts | `"off"` maps to on-demand, `"trap"`/`"headless"` map to auto-draft; explicit mode wins. Drafts run as fresh headless jobs by default. `"trap"` keeps the existing free-trap path for automatic and manual drafts. |
534
556
  | `post` | legacy | `"draft"` stages pending; `"auto"` maps to auto-review. Explicit mode/publish wins. Legacy publishing does not enable either per-verdict auto-post setting. Comments-only drafts always wait for a person. All posting refuses stale drafts. |
535
- | `harness`, `model`, `effort` | repo, then `[harness]` | The review job's worker. |
557
+ | `harness`, `model`, `effort` | `harness = "codex"`; model/effort inherit | The review job's worker. Headless Codex uses `[harness.codex].headless_sandbox` and `headless_model`; an explicit review model wins. |
536
558
  | `wallClockSecs`, `maxTurns`, `maxBudgetUsd` | `900`, `40`, unset | Cost bounds for one review job. |
537
559
  | `trapWaitSecs` | `600` | With `work = "trap"`: how long a job waits for a free trap. |
538
560
  | `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. |
539
561
  | `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. |
540
562
  | `skipAuthors`, `skipLabels` | `[]` | Requests on PRs by these authors or with these labels file an item but start no job. |
541
563
 
564
+ Each draft or re-draft starts a fresh session without follow-up chat. Headless drafts use the chore runner slots (`[limits].choreConcurrent`), so several can run at once when that limit is greater than one. The daily cap still bounds automatic starts.
565
+
542
566
  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.
543
567
 
544
568
  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.
@@ -257,6 +257,22 @@ a prompt into the trap's tmux pane when that pane shows Codex's idle prompt.
257
257
  If the trap still doesn't report after `[soak].codexClaimReleaseSecs`, the
258
258
  dispatch goes back to the queue.
259
259
 
260
+ A claimed brief includes the task and tells the trap to keep working in the
261
+ same turn after acknowledging it. `lobstah report <id> working` also tells
262
+ the trap to continue. An acknowledgement or takeover note is not a stopping
263
+ point; the trap ends its turn after `done`, `failed`, `needs-decision`,
264
+ `blocked`, or `paused`.
265
+
266
+ If a Codex trap still ends its turn on `working`, the daemon attempts one
267
+ recovery prompt per claim and session after `[helm].idleWorkingNoticeSecs`.
268
+ It uses the shared server or types into the idle tmux composer. The helm
269
+ hears only if the trap remains idle for another such interval. A dialog is
270
+ left untouched and reaches helm attention after that interval. Unread
271
+ `lobstah send` messages use the same delivery path when no park hook is
272
+ running; busy sessions receive them through their park hook or when they
273
+ next become idle. The daemon records delivered wakes across restarts and
274
+ leaves messages unread until the trap reads them.
275
+
260
276
  ## CLI vs desktop app
261
277
 
262
278
  Verified from a Codex desktop task on PR #48 and in #55:
package/docs/man.md CHANGED
@@ -491,27 +491,38 @@ stack. When two PRs share a head branch, the parent is the one first seen
491
491
  last. The attention list is in standing order: the time each condition
492
492
  started. `observedAt` is shown as the time of the last check.
493
493
 
494
- **Merge when green.** On the glass PRs tab, each open PR of yours has Merge
495
- when green. A second tap names the merge (`Merge #12 into main as one
496
- squashed commit`) and stores the request on the PR record. The boat refuses
497
- a PR it has no record of (404), one that isn't open (409), and one that is
498
- neither authored by the login `gh` signs in as nor opened by a dispatch
499
- (403). Each PR-watch tick, the daemon takes each request in turn:
500
-
501
- - A green PR that GitHub calls clean, with no open PR below it in its stack,
502
- merges with `gh pr merge --<method> --match-head-commit <head>`. A refused
503
- merge is tried again on the next tick.
504
- - A conflicting PR, or one with failing checks, is repaired first. A
505
- dispatch's PR already has its PR repair. For a PR no dispatch opened, the
506
- daemon queues one repair dispatch per head, which pushes to that PR's
507
- branch; once it reports the PR, the repair chain takes later rounds.
508
- - When a PR's repair stops at a head, the helm gets one `repair-stopped`
509
- notice for that head.
510
- - Drafts and running checks wait. A merged or closed PR drops its request.
511
-
512
- Cancel withdraws the request. The method is the repo's
513
- [`mergeMethod`](configuration.md#reposkey--workspace-definitions), else
514
- `[pickup.github.merge].method`, else squash.
494
+ **Merge when green.** Record a chat instruction or a decision answer on the PR:
495
+
496
+ ```sh
497
+ lobstah pr merge-when-green owner/repo#12 --by chat
498
+ lobstah pr merge-when-green owner/repo#12 --by decision:deploy --method merge --note "After staging and production" --hold "Run DB steps"
499
+ lobstah pr merge-when-green owner/repo#12 --release-hold
500
+ lobstah pr merge-when-green --clear owner/repo#12
501
+ ```
502
+
503
+ The CLI reads the repository's allowed methods with `gh repo view`. The
504
+ method defaults to the repo's configured `mergeMethod` (merge commits for
505
+ lobstah), then pickup's method, then squash. An explicit CLI authorization
506
+ can name any open PR. The glass's Merge when green button accepts your own
507
+ PRs and PRs opened by a dispatch.
508
+
509
+ `man tend`, PR cards, PR details, and matching Reviews rows show who gave
510
+ permission, when, the note, any hold, and the current status. Cancel merge
511
+ withdraws permission. A hold is a non-CI precondition; checks passing does
512
+ not release it.
513
+
514
+ Each PR-watch tick, the daemon merges a green, clean PR with no hold and no
515
+ open PR below it. GitHub's merge endpoint checks the recorded head SHA and
516
+ branch protection. The daemon never force-merges, bypasses protection, or
517
+ enables GitHub auto-merge. It records the merge SHA and tells the helm.
518
+ After the bottom PR merges, the daemon retargets the next PR to its base
519
+ and waits for fresh checks before continuing with that PR's authorization.
520
+
521
+ Failing checks and conflicts notify the helm and keep the merge waiting.
522
+ Existing PR repair can work those failures back to green. A refused merge
523
+ notifies the helm and can be tried again on the next tick. Drafts, unknown
524
+ checks, and running checks wait. A merged PR retains its authorization and
525
+ merge SHA; a PR closed without merging drops the request.
515
526
 
516
527
  **Merge stack when green.** A stack card of several PRs, all yours or a
517
528
  dispatch's, has Merge stack when green. Hovering names the merge (`Merges
@@ -1471,6 +1482,8 @@ does it. Each trap keeps one Codex pane: the one it recorded at sign-on.
1471
1482
  whatever its title says.
1472
1483
  - Panes running anything but Codex are left alone.
1473
1484
 
1485
+ The daemon archives a departed trap's last 200 terminal lines in `~/.lobstah/logs/traps/<trap-id>.log` before closing its dead pane, and sweeps unowned dead panes at startup and every five minutes (unknown owners use `pane-<pane-id>.log`).
1486
+
1474
1487
  `man throw --remote-control` makes one start reachable from a phone, new
1475
1488
  (`--new`) or returning. A Codex trap attaches to Codex's shared app-server, so its
1476
1489
  pane and a paired phone drive one thread. Other traps are unchanged unless
package/docs/pickup.md CHANGED
@@ -256,7 +256,7 @@ in roughly harness start-up time.
256
256
  ## Review requests
257
257
 
258
258
  Opt-in with `[reviews].enabled` ([configuration.md](configuration.md)). Each
259
- cycle spends one GitHub request: a GraphQL search for open PRs with
259
+ cycle runs one GraphQL search for open PRs with
260
260
  `user-review-requested:<identity>`, through `gh api graphql` on the shared
261
261
  GitHub budget. A blocked budget skips the cycle. `user-review-requested`
262
262
  matches requests that name the identity; a request made only to a team the
@@ -264,10 +264,16 @@ identity is on files nothing.
264
264
 
265
265
  Each PR is one review item, `review:<owner>/<repo>#<n>`, in
266
266
  `~/.lobstah/reviews/<owner>-<repo>-<n>/review.json`. An item holds rounds,
267
- one per `ReviewRequestedEvent`: the same standing request never opens a
268
- second round, and a re-request opens a new one (an open earlier round is
269
- withdrawn as superseded). A new push with no new request moves a requested
270
- round's head; a drafted round becomes `stale` and starts nothing on its own.
267
+ one per distinct PR diff while your review request stands on GitHub. A
268
+ re-request at the same head keeps the existing round and its draft. A new
269
+ push that changes the PR diff opens a fresh round even without another
270
+ request event, including after Skip or a posted review. Merging the base or
271
+ rebasing with the same diff keeps the existing round. A changed diff
272
+ supersedes an open earlier round as `withdrawn`.
273
+ The new round follows the repo's review mode and daily automatic limit.
274
+ Diff comparisons run once per observed head and use the shared GitHub
275
+ budget; an unavailable comparison
276
+ waits for a later poll.
271
277
  When the search stops returning a PR (the request was withdrawn, the
272
278
  person reviewed it on GitHub, or the PR closed), its open round is `withdrawn`. A
273
279
  truncated search (more than 50 results) withdraws nothing.
package/docs/turn-end.md CHANGED
@@ -40,6 +40,7 @@ A registration, written into `waits` (one file per tool, any name ending in
40
40
  | `read` | What the agent runs to see what's new. |
41
41
  | `cwd` | Where to run `wait`. Optional; the owner's `cwd` otherwise. |
42
42
  | `cursor` | Where `{cursor}` starts. Optional. |
43
+ | `context` | Optional recovery text (at most 20,000 characters): the tool's set, artifact, or instructions for restoring its state in the trap's own session. Lobstah stores and replays it without interpreting or executing it. |
43
44
 
44
45
  `wait` prints `{ "cursor": "<next>", "summary": "<one line>" }` and exits 0.
45
46
  With nothing new by its own deadline, it prints nothing and exits 0 or 2.
@@ -70,7 +71,22 @@ not move what `read` shows the agent: the agent reads it later.
70
71
  - When a wait prints, a live trap gets the pointer in its dispatch's inbox
71
72
  (its own inbox between dispatches), which wakes its park: "ume has
72
73
  something new: Chris picked an option. Run `ume feedback a1` to see it."
73
- A trap that's gone gets a continuation of its dispatch, one at a time.
74
+ The wake stays keyed to that dispatch, even if the trap has moved on to
75
+ another catch. A working trap receives no injected turn: its own park
76
+ delivers the inbox message.
77
+ - The waiting dispatch stays addressed to its owning trap. Lobstah saves
78
+ the waiting report (including its note and link) and each tool's opaque
79
+ `context` with the dispatch. It does not read any tool's private state or
80
+ pass tool-specific environment variables.
81
+ - If the owner is stowed or ghosted when a wake is pending, the daemon
82
+ re-throws that same trap through its normal interactive launch path.
83
+ It restores the original dispatch and delivers its brief, saved park
84
+ context, and unread inbox together. The trap restores the tool's state
85
+ and registers its own wait again. A replacement registration retires the
86
+ old watcher. Turn-wait wakes never create a headless follow-up dispatch.
87
+ - Only one re-throw per owner runs at a time. Existing start reservations
88
+ prevent duplicate launches across daemon restarts; failed starts back
89
+ off while the dispatch and its messages remain in place.
74
90
  - A pointer still unread after 15 minutes raises one `trap-not-receiving`
75
91
  notice to the helm: the trap has stopped receiving.
76
92
  - A wait that ends without printing, with exit 0 or 2, timed out quietly
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lobstah",
3
- "version": "0.8.11",
3
+ "version": "0.8.13",
4
4
  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
5
5
  "license": "MIT",
6
6
  "author": "aequitas labs LLC",