lobstah 0.5.13 → 0.6.0

package/docs/configuration.md

@@ -14,7 +14,7 @@ keys of that section.
 |---|---|---|
 | `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. |
 | `notifyVerbs` | `["needs-decision", "blocked", "done", "failed"]` | Which verbs fire `notifyCommand`. |
-| `attentionKinds` | `["question", "pr:ready", "pr:review", "pr:conflict", "pr:checks"]` | Which kinds `man tend`, the glass, and the desktop pet show. `pr:draft` and `landed` are valid opt-in kinds. An explicit list is used unchanged. Unknown kinds are errors. See the [attention contract](vocabulary.md#attention-contract). |
+| `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). |
 | `remindSecs` | `900` | An unanswered `needs-decision`/`blocked` re-fires to `man wait`/`man haul` on this interval until answered. `0` = report once only. |
 
 ## `[repos.<key>]` — workspace definitions
@@ -31,6 +31,7 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
 | `env` | no | Environment merged into every dispatch for this repo. |
 | `pickup` | no (`false`) | Opt this repo into `[pickup.github]` multi-repo mode. Explicit per repo — nothing becomes pickable by being configured. |
 | `pushEarly`, `draftPr`, `checkpointOnStop` | no (inherit `[limits]`) | Override remote preservation for this repo's headless dispatches. |
+| `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>`. |
 
 `[repos.<key>.harness]` — per-repo harness defaults: `default` (`claude` \|
 `codex`), `model`, `effort`.
@@ -55,14 +56,14 @@ Same three keys as the per-repo block. Precedence for every harness setting:
 
 | Key | Default | Meaning |
 |---|---|---|
-| `maxConcurrent` | `2` | Headless work-lane runners the daemon may run at once. Trap-claimed catches use their own sessions and do not spend these slots. |
+| `maxConcurrent` | `2` | Headless work-lane runners the daemon may run at once. Trap-claimed catches use their own sessions and do not spend these slots. A dispatch whose worker reported `done` or `failed` does not spend a slot, even while its runner is still exiting. A dispatch whose worker reported `paused` is parked: its runner ends the session and exits, and it spends no slot. An operator message, or the time given with `--until`, wakes it into the same session when a slot is free; a waking dispatch takes the slot before queued work. `man tend`, `daemon status`, `doctor`, and the glass list parked dispatches. |
 | `choreConcurrent` | `1` | Headless chore-lane runner ceiling (rebases and other machine-originated runs). |
 | `wedgeThresholdSecs` | `600` | No tool activity for this long while alive = wedged → killed and forked with a nudge. Also the age past which `status`, `ls`, `man tend`, and the glass show a dispatch's activity line as stale. |
 | `maxRestartAttempts` | `2` | Bounded restart ladder for dead and wedged runners. |
 | `wallClockSecs` | `3600` | Initial active-work window. Progress extends it, up to `maxWallClockSecs`; time paused with `report paused --waiting-on` does not count. |
 | `maxWallClockSecs` | `4 × wallClockSecs` | Hard active-work ceiling across restarts. |
-| `pushEarly` | `true` | For a new chain, push each new committed HEAD to its non-trunk branch on `origin` within 10 seconds. A rejected push is noted and retried only after HEAD moves. A follow-up whose chain already has a PR does not push automatically; its worker pushes to the existing PR's head branch. |
-| `draftPr` | `true` | For a new chain, after first push, adopt an existing PR or open one draft PR when `gh` is available. A follow-up with a chain PR keeps that PR and its watch; it does not open another. |
+| `pushEarly` | `true` | For a new chain, push each new committed HEAD to its non-trunk branch on `origin` within 10 seconds. A rejected push is noted and retried only after HEAD moves. A follow-up whose chain already has a PR, and a dispatch whose descriptor names a PR (a repair or a rebase chore), does not push automatically; its worker pushes to the existing PR's head branch. |
+| `draftPr` | `true` | For a new chain, after first push, adopt an existing PR or open one draft PR when `gh` is available. A follow-up with a chain PR, and a dispatch whose descriptor names a PR, keeps that PR and its watch; it does not open another. |
 | `checkpointOnStop` | `true` | Before a nonterminal stop, checkpoint eligible tracked and untracked files. A new chain then pushes; a follow-up with a chain PR leaves the checkpoint local for its worker to push. Ignored files and secret/build denylist paths are excluded. Set all three switches to `false` for prior runner behavior. |
 
 A runner extends its active-work window when a fresh activity event or new HEAD
@@ -72,8 +73,9 @@ time. At the hard ceiling, the status verb remains `failed` for compatibility,
 but its note starts `budget:` and tells the man what work was saved and to
 send a continuation.
 | `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. |
+| `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. |
 | `choreRetentionDays` | `7` | Completed chores age out of `chores/done/`. |
-| `attachmentMaxBytes` | `26214400` (25 MiB) | Maximum size of each file supplied with repeatable `dispatch --attach` or `send --attach`. |
+| `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. |
 | `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`. |
 | `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. |
 | `reuseWorktree` | `true` | A follow-up (`--follow-up <id>`) runs in the worktree of the newest dispatch in its chain whose worktree still exists, on the branch and HEAD where that dispatch stopped. Trunk is fetched; `setup` runs again only if a lockfile changed. It reuses only when the worktree is clean (untracked files under the repo's `scratch` paths excepted), belongs to the same repo, and no other dispatch runs in it; otherwise it allocates a fresh worktree as usual. A dirty worktree is never cleaned or reset. The first status note says which: `reusing worktree of <origin>` or `fresh worktree (<reason>)`. A lock file in the worktree's git dir (`lobstah.lock`) keeps a second runner out; a lock whose dispatch has finished is stale. A shared worktree is kept by the cull and the free-space guard while any dispatch in the chain is queued or active, and it ages from the newest dispatch that used it. `false` allocates a fresh worktree for every dispatch. Headless dispatches only: a trap works in its own worktree. |
@@ -84,7 +86,7 @@ send a continuation.
 | Key | Default | Meaning |
 |---|---|---|
 | `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. |
-| `ttlSecs` | `1800` | Heartbeat age past which a registration is a ghost trap: the sweep removes it and requeues its open catch (or finalizes a cancelled one as failed). A fresh `lobstah report` on the catch counts as liveness too, and so does a fresh beat. |
+| `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. |
 | `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. |
 | `pausedTtlSecs` | `86400` (24 hours) | A trap whose catch last reported `paused` is kept out of the ghost sweep this long after the report. `report paused --until <iso|duration>` sets the expiry instead. After it, the sweep removes the trap as usual, and the notice says the pause expired. |
 
@@ -106,11 +108,13 @@ send a continuation.
 
 | Key | Default | Meaning |
 |---|---|---|
-| `maxForksPerCycle` | `3` | The most continuation (CI-fix) dispatches one watch cycle of `lobstah pick` may fork. Each watch over the cap is held: its events stay buffered, `man tend` and `lobstah watch` list it as `held`, one `watch-held` notice names the held watches, and it forks nothing until `lobstah watch release <key>` (or `--all`). |
-| `autoRepair` | `true` | On a dispatch-owned PR, fork a repair follow-up for a conflict, failed current check, or requested review changes. `false` leaves check-event delivery and attention as before. |
+| `maxForksPerCycle` | `3` | The most continuation (CI-fix) dispatches one watch cycle of `lobstah pick` may fork. Each watch over the cap is held: its events stay buffered, `man tend` and `lobstah watch` list it as `held`, one `watch-held` notice names the held watches, and it forks nothing until `lobstah watch release <key>` (or `--all`). A held PR watch also queues no repair; see [the man page](man.md) for `watch hold` and cancelled repairs. |
+| `autoRepair` | `true` | On a dispatch-owned PR, queue a repair chore for a conflict, failed current check, or requested review changes. `false` leaves check-event delivery and attention as before. |
 | `conflicts` | `true` | Repair conflicts when `autoRepair` is on. Set `false` to show conflict attention without a repair. |
 | `checks` | `true` | Repair failed current checks when `autoRepair` is on. Set `false` to show check attention without a repair. |
-| `maxRepairsPerPr` | `2` | Maximum repair follow-ups for one PR head SHA. When the limit is reached and the issue remains, `pr:conflict`, `pr:checks`, or `pr:review` attention names the limit. |
+| `maxRepairsPerPr` | `2` | Maximum repair follow-ups for one PR head SHA. When the limit is reached and the issue remains, `pr:conflict`, `pr:checks`, or `pr:review` attention names the limit. A repair that waits is not an attempt. Below this limit, each failing check gets at most one repair round per PR and head SHA: a check that had its round and still fails on the same head waits for a new commit, with `repair.status: waiting` and `heldBy: repaired`, and raises `pr:checks` attention. A CI-fix continuation from `lobstah pick` (`autoRepair = false`) follows the same rule. Human gates (`[repos.<key>].humanGateChecks`, `report --human-gate`) get no round. |
+| `repairSettleSecs` | `600` | A repair is queued only after the PR's head, its base branch's head, and its failing checks have been unchanged for this many seconds. Until then the PR record shows `repair.status: waiting` with `heldBy: settle` and `until`. |
+| `repairTrapWaitSecs` | `600` | A daemon repair chore addressed to the PR-owning trap waits this many seconds for that trap. If still queued, it becomes headless. A person's addressed work never falls back. |
 
 ## `[grounds.*]` — helm territories
 
@@ -195,3 +199,5 @@ See [pickup.md](pickup.md) for the loop semantics these keys drive.
 |---|---|
 | `LOBSTAH_HOME` | The instance root (default `~/.lobstah`). Multiple instances = multiple homes; one daemon per home, enforced. |
 | `LOBSTAH_MAN` | `=1` designates a session as the lobstah man for the `man haul` Stop hook. |
+| `LOBSTAH_TRAP_TICKET` | A `trap reserve` ticket. `lobstah soak` redeems it and signs the session on as the reserved trap. `--ticket` takes precedence. |
+| `LOBSTAH_TERMINAL_TITLE` | `=0` stops soak from naming the terminal tab after the trap, and stow from clearing it. |

package/docs/harness/claude-code.md

@@ -61,6 +61,14 @@ reads it, so no `--session` flag is needed. The session-start brief still
 prints the id, and the sign-on commands with the id filled in, if you want
 to pass `--session` explicitly. Claude Code session ids are UUIDv4.
 
+For the glass's ↗ open button, give the trap its own session link with
+`lobstah soak --link <url>`. A Claude desktop session exposes its own
+`claude://claude.ai/...` link in the app; copy that link from the session.
+Its app id is not the CLI session id. In the VS Code extension, use
+`vscode://anthropic.claude-code/open?session=<session-id>` with the id above.
+The glass checks the stored link before showing it. `lobstah focus <trap>`
+uses the same focus steps from the terminal.
+
 ## Getting woken: arm the watcher
 
 In Claude Code the Stop hook runs in **arm** mode by default. At turn end
@@ -74,6 +82,12 @@ with work in flight:
   question.
 
 A trap arms `lobstah soak --wait --timeout 900` the same way.
+
+`lobstah soak` prints a title at sign-on, `soak --wait` prints one with
+the claimed work, and `report done` or `report failed` prints the trap
+name again. The trap skill uses `set_session_title` for literal `self`
+in the desktop Code tab when available. It does not retry a refusal or
+approval request. The CLI title hook does not rename a running CLI session.
 `lobstah man haul --park` or `[helm].park = "block"` in `config.toml`
 switches to the blocking park instead: the hook itself waits (up to its
 4-hour timeout) for something to need attention.

package/docs/harness/codex.md

@@ -39,6 +39,12 @@ says when the plugin is behind.
 | `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken, and sending a follow-up to finished work. |
 | `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. |
 
+`lobstah soak` prints a title at sign-on, `soak --wait` prints one with
+the claimed work, and `report done` or `report failed` prints the trap
+name again. The trap skill uses `set_thread_title` for the current thread
+in the Codex app when available. It does not retry a refusal or approval
+request. The CLI has no live title setter.
+
 There are no slash commands: the Codex plugin layout has no commands
 directory. The skills run the same `lobstah` commands as the README
 quickstart.
@@ -118,6 +124,12 @@ Codex task ids are UUIDv7 (for example `01a0ceb8-b9bd-7d42-…`); Claude Code
 session ids are UUIDv4. When both harnesses' variables are set, lobstah uses
 this format to tell which one signed on.
 
+For the glass's ↗ open button, form `codex://threads/<task-id>` from the
+task id in the session-start brief and pass it with
+`lobstah soak --link <url>`. The glass checks the stored link before
+showing it. `lobstah focus <trap>` uses the same focus steps from the
+terminal.
+
 ## Getting woken: the blocking park
 
 In Codex the Stop hook runs in **block** mode by default. At turn end with