lobstah 0.7.4 → 0.7.6
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/README.md +25 -7
- package/dist/main.js +11517 -7879
- package/dist/runner.js +894 -693
- package/dist/wharf-trap-runner.js +12 -0
- package/docs/configuration.md +13 -1
- package/docs/man.md +1 -1
- package/docs/vocabulary.md +2 -2
- package/package.json +4 -1
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// apps/cli/src/wharf-trap-runner.ts
|
|
2
|
+
import { spawn } from "node:child_process";
|
|
3
|
+
var [harness, ...args] = process.argv.slice(2);
|
|
4
|
+
if (harness !== "claude" && harness !== "codex") throw new Error("hosted trap runner accepts only Claude or Codex");
|
|
5
|
+
var child = spawn(harness, args, { stdio: "inherit", env: { ...process.env, LOBSTAH_WHARF_SESSION_PID: String(process.pid) } });
|
|
6
|
+
child.on("error", () => {
|
|
7
|
+
process.stderr.write("Could not launch the configured trap harness.\n");
|
|
8
|
+
process.exitCode = 1;
|
|
9
|
+
});
|
|
10
|
+
child.on("exit", (code) => {
|
|
11
|
+
process.exitCode = code ?? 1;
|
|
12
|
+
});
|
package/docs/configuration.md
CHANGED
|
@@ -27,12 +27,14 @@ The descriptor's `repo` field resolves here; the key is what dispatchers name.
|
|
|
27
27
|
| `path` | yes | The git clone worktrees are allocated from (`~/` expands). |
|
|
28
28
|
| `trunk` | yes (default `main`) | Branch dispatches start from (`origin/<trunk>`). |
|
|
29
29
|
| `origin` | no | Enables clone-on-first-use when `path` doesn't exist. |
|
|
30
|
+
| `review` | no (`"github"`) | Destination for PR links in the glass and PR pet clicks, independent of `[pet].open`: `github`, `graphite`, `linear` (browser: `https://linear.review/{owner}/{repo}/pull/{number}`), `linear-app` (Linear desktop app: `linear://review/{owner}/{repo}/pull/{number}`), or an HTTPS template containing `{owner}`, `{repo}`, and `{number}`. Example: `"https://review.example/{owner}/{repo}/{number}"`. The configured `origin` (else the checkout's git origin) identifies the repo; canonical GitHub URLs remain the watch identity. Linear reviews require its GitHub integration; `linear-app` also requires the installed app. Custom templates remain HTTPS-only. |
|
|
30
31
|
| `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. |
|
|
31
32
|
| `scratch` | no | Repo-relative paths (e.g. `["tmp", ".cache"]`) whose untracked files do not count as uncommitted changes when a follow-up decides whether to reuse its origin's worktree. Tracked changes anywhere, and untracked files elsewhere, still do. |
|
|
32
33
|
| `env` | no | Environment merged into every dispatch for this repo. |
|
|
33
34
|
| `pickup` | no (`false`) | Opt this repo into `[pickup.github]` multi-repo mode. Explicit per repo — nothing becomes pickable by being configured. |
|
|
34
35
|
| `pushEarly`, `draftPr`, `checkpointOnStop` | no (inherit `[limits]`) | Override remote preservation for this repo's headless dispatches. |
|
|
35
36
|
| `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). |
|
|
37
|
+
| `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. |
|
|
36
38
|
| `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>`. |
|
|
37
39
|
|
|
38
40
|
`[repos.<key>.harness]` — per-repo harness defaults: `default` (`claude` \|
|
|
@@ -108,6 +110,7 @@ send a continuation.
|
|
|
108
110
|
|---|---|---|
|
|
109
111
|
| `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. |
|
|
110
112
|
| `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. |
|
|
113
|
+
| `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. |
|
|
111
114
|
| `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. |
|
|
112
115
|
| `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. |
|
|
113
116
|
| `signOffGraceSecs` | `600` | After a trap signs off, its address is held this long: messages to it wait for a re-soak of the same worktree instead of bouncing, `send` to it queues with a warning, and work addressed to it raises no `bait-orphaned` notice. After the grace the daemon bounces the held messages. `0` bounces at sign-off. |
|
|
@@ -120,6 +123,9 @@ send a continuation.
|
|
|
120
123
|
|---|---|---|
|
|
121
124
|
| `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. |
|
|
122
125
|
| `reportSecs` | `900` | Minimum seconds between park-delivered digests for a helm session. The digest is also change-gated — quiet grounds deliver nothing regardless of cadence. |
|
|
126
|
+
| `queuedNoticeSecs` | `180` | Queued age before a dispatch-progress notice wakes the helm with its queue reason and remedy. `0` disables. Reminders back off at 15, 45, 105… minutes after the threshold; claim clears the condition. |
|
|
127
|
+
| `stalledNoticeSecs` | `1200` | Silence since both a claimed dispatch's last activity and note before dispatch-progress attention. The same reminder backoff applies; activity or a note clears it. Paused, needs-decision and blocked workers use their existing paths. `0` disables. |
|
|
128
|
+
| `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. |
|
|
123
129
|
| `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. |
|
|
124
130
|
|
|
125
131
|
## `[glass]` — the spyglass
|
|
@@ -128,6 +134,12 @@ send a continuation.
|
|
|
128
134
|
|---|---|---|
|
|
129
135
|
| `port` | `4949` | Localhost port for the glass. `LOBSTAH_GLASS_PORT` takes precedence. |
|
|
130
136
|
|
|
137
|
+
## `[pet]` — report and decision clicks
|
|
138
|
+
|
|
139
|
+
| Key | Default | Meaning |
|
|
140
|
+
|---|---|---|
|
|
141
|
+
| `open` | `"tab"` | `tab` opens the item in a new browser tab; `helm` focuses the helm through its existing focus ladder (falls back to the item's page). `app` tries an installed Chrome glass at the exact local address, then `glass show`; absent, hidden or unresponsive apps fall back to a tab. Native launch/delivery remains unverified; Safari currently takes the fallback. Applies only to reports and decisions, never PR links. Existing presence expiry windows are unchanged. |
|
|
142
|
+
|
|
131
143
|
## `[watch]` — watch delivery
|
|
132
144
|
|
|
133
145
|
| Key | Default | Meaning |
|
|
@@ -146,7 +158,7 @@ send a continuation.
|
|
|
146
158
|
|
|
147
159
|
One helm per grounds; a repo belongs to at most one grounds (`man helm`
|
|
148
160
|
refuses on overlap or an unknown repo key). With no `[grounds.*]` configured
|
|
149
|
-
there is one implicit `
|
|
161
|
+
there is one implicit `home` grounds covering every repo — the partition
|
|
150
162
|
only exists when asked for.
|
|
151
163
|
|
|
152
164
|
```toml
|
package/docs/man.md
CHANGED
|
@@ -863,7 +863,7 @@ The lobstah man skill prints the glass URL. `[glass].port` sets the port;
|
|
|
863
863
|
|
|
864
864
|
**One helm per grounds, enforced.** A **grounds** is a named territory: the
|
|
865
865
|
subset of configured repos one orchestrator oversees (`[grounds.*]`; with
|
|
866
|
-
none configured, one implicit `
|
|
866
|
+
none configured, one implicit `home` grounds covers every repo). A repo
|
|
867
867
|
belongs to at most one grounds, so two orchestrators can never dispatch into
|
|
868
868
|
the same territory. The registration is one file per grounds — the data model
|
|
869
869
|
cannot hold two:
|
package/docs/vocabulary.md
CHANGED
|
@@ -515,7 +515,7 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
|
|
|
515
515
|
| `man roster` | List the trap roster. `man roster set <trap> --harness\|--model\|--terminal <value>\|--config <key>=<value>` saves how a throw starts the trap; `default` (or `key=`) clears a field. |
|
|
516
516
|
| `man haul --park` | Make the Stop hook wait for attention while work is in flight. `[helm].park = "block"` selects the same mode. In arm mode, the hook allows a stop with a live watcher or blocks with the arm command. |
|
|
517
517
|
| `relieve` | Step down. `--take` on another session's `helm` is the only force path: it displaces a live holder deliberately and leaves them a stand-down notice, delivered once at their next park. A holder whose heartbeat lapsed past `[helm].ttlSecs` is stale and claimable without `--take`. |
|
|
518
|
-
| grounds | A named territory: the subset of configured repos one helm oversees, from `[grounds.*]`. A repo belongs to at most one grounds (config error otherwise). No grounds configured means one implicit `
|
|
518
|
+
| grounds | A named territory: the subset of configured repos one helm oversees, from `[grounds.*]`. A repo belongs to at most one grounds (config error otherwise). No grounds configured means one implicit `home` grounds covering every repo; explicit `home` or `fleet` names are unchanged. Internal detail: the implicit local grounds permanently uses storage ID `fleet` (files, embedded fields and report/ack keys), so old and new CLI/daemon versions share one authority without moving data. `--grounds fleet` aliases `home` with a notice; raw storage addresses remain valid and copyable. Wharf grounds have no legacy alias. |
|
|
519
519
|
| charter | The helm's persona and scope fences, in Standard Technical English. Printed at sign-on and re-injected by `man brief` at every session start, so it survives restarts and compaction. |
|
|
520
520
|
| digest | The delta since the reported-through cursor: catches landed, attention arisen, still-waiting, fleet verdict. Carried by `man report`, a `man wait` timeout, and — in blocking park mode, at `[helm].reportSecs` cadence — the park itself. Change-gated: an empty delta is never delivered. |
|
|
521
521
|
|
|
@@ -538,7 +538,7 @@ never until someone acknowledges it.
|
|
|
538
538
|
| ---- | ------------ | ----------- |
|
|
539
539
|
| `question` | The dispatch's last status is `needs-decision` or `blocked`. Held (`held: true`; not in the pet, the glass, or notifyCommand) while a live helm for its grounds has not ended a turn since it was filed. Hidden while a decision on the same dispatch, asked at or after it, is on disk (when `decision` is enabled). | Any newer status entry, or a message newer than it. |
|
|
540
540
|
| `decision` | The helm asked the human with `lobstah man ask` and no answer is recorded. Key `decision:<rid>`. | Answered (the glass or `man answer`), withdrawn (`man ask --withdraw`), or replaced by a newer ask on the same dispatch. |
|
|
541
|
-
| `landed` | The dispatch is `done` or `failed` after its grounds' reported-through cursor (the grounds listing the repo, else `
|
|
541
|
+
| `landed` | The dispatch is `done` or `failed` after its grounds' reported-through cursor (the grounds listing the repo, else `home`; at most 24 h back). Opt-in. | `man report` (or the helm park's digest) advances the cursor. |
|
|
542
542
|
| `pr:draft` | An open PR is a draft, and the user opted into this kind. | Ready for review, merged, or closed. |
|
|
543
543
|
| `pr:review` | An open PR has unresolved review questions, or requested changes that lobstah cannot repair, has exhausted, or is configured not to repair. | Every thread resolved and no changes requested, or merged / closed. |
|
|
544
544
|
| `pr:checks` | An open PR has a failed latest check, and lobstah cannot repair it, has exhausted attempts, or is configured not to repair. | Green on the head, or merged / closed. |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "lobstah",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.6",
|
|
4
4
|
"description": "Harness-agnostic, token-efficient supervision framework for coding agents",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "aequitas labs LLC",
|
|
@@ -33,5 +33,8 @@
|
|
|
33
33
|
"optionalDependencies": {
|
|
34
34
|
"@anthropic-ai/claude-agent-sdk": "^0.3.0",
|
|
35
35
|
"@openai/codex-sdk": "^0.152.0"
|
|
36
|
+
},
|
|
37
|
+
"dependencies": {
|
|
38
|
+
"ws": "^8.22.0"
|
|
36
39
|
}
|
|
37
40
|
}
|