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/main.js +15954 -11513
- package/dist/runner.js +39 -4
- package/docs/configuration.md +13 -6
- package/docs/harness/codex.md +20 -0
- package/docs/man.md +109 -10
- package/docs/pickup.md +22 -7
- package/docs/vocabulary.md +1 -1
- package/package.json +1 -1
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
|
-
|
|
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 !==
|
|
5158
|
+
if (ownerRepo !== void 0 && ownerRepo !== repoKey2) {
|
|
5124
5159
|
return { reuse: false, reason: `origin worktree belongs to repo ${ownerRepo}` };
|
|
5125
5160
|
}
|
|
5126
5161
|
try {
|
package/docs/configuration.md
CHANGED
|
@@ -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 `
|
|
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
|
|
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.
|
|
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
|
|
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
|
package/docs/harness/codex.md
CHANGED
|
@@ -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
|
|
193
|
-
|
|
194
|
-
before it waits.
|
|
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
|
-
-
|
|
266
|
-
|
|
267
|
-
|
|
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.
|
|
914
|
-
|
|
915
|
-
|
|
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.
|
|
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
|
|
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.
|
|
294
|
-
|
|
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
|
|
372
|
-
|
|
373
|
-
|
|
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
|
-
|
|
|
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,
|
package/docs/vocabulary.md
CHANGED
|
@@ -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
|
|