lobstah 0.7.6 → 0.7.7

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
@@ -1249,9 +1249,11 @@ var DEFAULT_HELM = {
1249
1249
  idleWorkingNoticeSecs: 60,
1250
1250
  ttlSecs: 1800,
1251
1251
  reportSecs: 900,
1252
- armGraceSecs: 5
1252
+ armGraceSecs: 5,
1253
+ todoStaleDays: 3
1253
1254
  };
1254
1255
  var DEFAULT_GLASS = { port: 4949 };
1256
+ var DEFAULT_WAIT = { baseTimeoutSecs: 900, baseRepeats: 3, maxTimeoutSecs: 14400 };
1255
1257
  var DEFAULT_WATCH = { maxForksPerCycle: 3, autoRepair: true, conflicts: true, checks: true, maxRepairsPerPr: 2, maxRepairsWithoutProgress: 2, repairSettleSecs: 600, repairCooldownSecs: 0, repairTrapWaitSecs: 600 };
1256
1258
  var DEFAULT_LIMITS = {
1257
1259
  maxConcurrent: 2,
@@ -1285,7 +1287,23 @@ function loadConfig() {
1285
1287
  throw new Error(`[pet].open must be "tab", "app", or "helm" in ${configPath()}`);
1286
1288
  const watch = { ...DEFAULT_WATCH, ...raw.watch ?? {} };
1287
1289
  const helm = { ...DEFAULT_HELM, ...raw.helm ?? {} };
1288
- for (const key of ["queuedNoticeSecs", "stalledNoticeSecs", "idleWorkingNoticeSecs"]) {
1290
+ const wait = { ...DEFAULT_WAIT, ...raw.wait ?? {} };
1291
+ for (const key of ["baseTimeoutSecs", "baseRepeats", "maxTimeoutSecs"]) {
1292
+ if (typeof wait[key] !== "number" || !Number.isSafeInteger(wait[key]) || wait[key] <= 0)
1293
+ throw new Error(`[wait].${key} must be a positive whole number in ${configPath()}`);
1294
+ }
1295
+ if (wait.maxTimeoutSecs < wait.baseTimeoutSecs)
1296
+ throw new Error(`[wait].maxTimeoutSecs must be at least baseTimeoutSecs in ${configPath()}`);
1297
+ if (helm.timezone !== void 0) {
1298
+ if (typeof helm.timezone !== "string" || !helm.timezone.trim())
1299
+ throw new Error("[helm].timezone must be an IANA timezone");
1300
+ try {
1301
+ new Intl.DateTimeFormat("en", { timeZone: helm.timezone });
1302
+ } catch {
1303
+ throw new Error("[helm].timezone must be an IANA timezone");
1304
+ }
1305
+ }
1306
+ for (const key of ["queuedNoticeSecs", "stalledNoticeSecs", "idleWorkingNoticeSecs", "todoStaleDays"]) {
1289
1307
  if (typeof helm[key] !== "number" || !Number.isFinite(helm[key]) || helm[key] < 0) {
1290
1308
  throw new Error(`[helm].${key} must be a non-negative number in ${configPath()}`);
1291
1309
  }
@@ -1343,6 +1361,7 @@ function loadConfig() {
1343
1361
  limits: { ...DEFAULT_LIMITS, ...raw.limits ?? {} },
1344
1362
  soak: parseSoak(raw.soak),
1345
1363
  helm,
1364
+ wait,
1346
1365
  glass: { ...DEFAULT_GLASS, ...raw.glass ?? {} },
1347
1366
  pet: { open: petOpen },
1348
1367
  watch,
@@ -1513,7 +1532,7 @@ function parsePrRef(s) {
1513
1532
  const number = Number(n);
1514
1533
  return { owner, repo, number, key: `pr:${owner}/${repo}#${number}`, url: `https://github.com/${owner}/${repo}/pull/${number}` };
1515
1534
  }
1516
- var PR_VIEW_FIELDS = "title,state,isDraft,isCrossRepository,headRefOid,baseRefName,baseRefOid,headRefName,mergeStateStatus,reviewDecision,statusCheckRollup,mergedAt,closedAt,updatedAt,reviews";
1535
+ var PR_VIEW_FIELDS = "title,state,isDraft,isCrossRepository,headRefOid,baseRefName,baseRefOid,headRefName,mergeStateStatus,reviewDecision,statusCheckRollup,createdAt,mergedAt,closedAt,updatedAt,reviews";
1517
1536
  var PR_VIEW_FIELDS_NO_CHECKS = PR_VIEW_FIELDS.split(",").filter((f) => f !== "statusCheckRollup").join(",");
1518
1537
  var FORBIDDEN = /resource not accessible by (integration|personal access token)/i;
1519
1538
  function ghPrView(ref) {
@@ -2619,6 +2638,9 @@ function parseBackendLocation(raw) {
2619
2638
  return { kind: "wharf", url: b.url.replace(/\/$/, ""), account: b.account, tokenEnv: b.tokenEnv };
2620
2639
  }
2621
2640
 
2641
+ // packages/core/dist/todos.js
2642
+ var CLOSED_KEEP_MS = 30 * 24 * 3600 * 1e3;
2643
+
2622
2644
  // packages/core/dist/decisions.js
2623
2645
  var DECISION_DETAIL_MAX = 64 * 1024;
2624
2646
  var ANSWER_TYPES = {
@@ -2642,6 +2664,9 @@ var ANSWER_TYPES = {
2642
2664
  };
2643
2665
  var ANSWER_EXTENSIONS = Object.keys(ANSWER_TYPES);
2644
2666
 
2667
+ // packages/core/dist/grants.js
2668
+ var ONCE_TTL_MS = 60 * 60 * 1e3;
2669
+
2645
2670
  // packages/core/dist/harness.js
2646
2671
  import * as fs23 from "node:fs";
2647
2672
  import * as path19 from "node:path";
@@ -123,10 +123,29 @@ send a continuation.
123
123
  |---|---|---|
124
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. |
125
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
+ | `timezone` | system timezone | IANA timezone (e.g. `America/New_York`) for daily goals. A goals day starts at 04:00 local. |
126
127
  | `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
128
  | `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
129
  | `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. |
129
130
  | `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. |
131
+ | `todoStaleDays` | `3` | Open helm to-dos (`lobstah todo`) older than this many days add one note to `man tend`. `0` disables. |
132
+
133
+ ## `[wait]` — quiet helm and trap waiters
134
+
135
+ | Key | Default | Meaning |
136
+ |-----|---------|---------|
137
+ | `baseTimeoutSecs` | `900` | Initial idle timeout for `man wait`, `soak --wait` and Stop-hook parks, local or on a wharf. A positive `--timeout` overrides the base for that invocation, not the adaptive backoff. |
138
+ | `baseRepeats` | `3` | Consecutive empty timeouts at the base before doubling on each subsequent wait. |
139
+ | `maxTimeoutSecs` | `14400` | Idle timeout cap (4 hours), at least the base. All three settings are positive whole numbers. |
140
+
141
+ The defaults wait 900, 900, 900, 1800, 3600, 7200, then 14400 seconds.
142
+ History is stored per session across re-arms. An event or user prompt resets
143
+ that session; a dispatch or send resets all this boat's waiters. Already-armed
144
+ waiters adopt a fresh base deadline on their next poll. Polling and liveness
145
+ heartbeats keep their usual cadence, so events still wake immediately.
146
+ `--peek` and zero-time trap probes do not advance the backoff.
147
+ For a cap longer than four hours, use a foreground waiter or increase the
148
+ harness's blocking Stop-hook timeout too.
130
149
 
131
150
  ## `[glass]` — the spyglass
132
151
 
@@ -35,6 +35,8 @@ row, and the session-start brief says when the plugin is behind.
35
35
  | Stop hook (`lobstah man haul`) | At turn end, blocks with standing attention, or with the command to arm a watcher while work is in flight. Inert unless the session holds the helm or is soaking. |
36
36
  | PostToolUse hook (`lobstah soak beat`) | After every tool call in a soaking session: refreshes the trap's liveness and writes its catch's activity (the tool name and its primary target, redacted). At most once per 30 seconds per trap. No network, no git; always exits 0, errors go to `~/.lobstah/logs/beat.log`. Inert when not soaking or with `[soak].beat = false`. |
37
37
  | SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends and keeps its worktree. |
38
+ | Grants mod (`hooks/grants.mjs`) | Answers Claude Code's `tool.check` for a trap's Bash and write calls: a call that would be put to a prompt or the auto-mode classifier, and that a person has granted (`lobstah grant`, or Allow on a glass card), runs. It leaves alone a call the rules allow or refuse. Mods need a Claude Code version that supports them; they do not run in WSL or the VS Code chat panel. |
39
+ | PermissionRequest hook (`lobstah hook permission-request`) | The same answer where a permission prompt would show. |
38
40
  | `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken. |
39
41
  | `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 waiting on something external (for ume, the non-blocking push when the await cannot run as a tracked background task). |
40
42
 
@@ -36,6 +36,7 @@ says when the plugin is behind.
36
36
  | Stop hook (`lobstah man haul`) | Parks the session at turn end while work is in flight and wakes it when something needs attention. Inert unless the session holds the helm or is soaking. |
37
37
  | PostToolUse hook (`lobstah soak beat`) | After a tool call in a soaking session: refreshes the trap's liveness and writes its catch's activity. Needs Codex 0.117.0+ (see [below](#post-tool-hook-what-codex-has)). Older Codex ignores the event, and a trap's liveness then comes from its reports and its park only. |
38
38
  | SessionEnd hook (`lobstah stow --quiet`) | Signs a soaking session off when it ends and keeps its worktree. |
39
+ | PermissionRequest hook (`lobstah hook permission-request`) | When Codex is about to ask for approval in a trap, a call a person has granted (`lobstah grant`, or Allow on a glass card) is allowed, before the approval reviewer. Anything not granted goes on to Codex's normal approval. Like every hook, it runs only once trusted in `/hooks`; it is new, so it needs that review once. |
39
40
  | `man` skill | The orchestrator: the helm, the charter, dispatching, tending, getting woken, and sending a follow-up to finished work. |
40
41
  | `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. |
41
42
 
package/docs/man.md CHANGED
@@ -68,6 +68,36 @@ the background, dispatch it with the `lobstah` CLI instead of doing it inline:
68
68
  That's the whole integration — the CLI is self-documenting (`lobstah help`)
69
69
  and its TOON output is built to be read by agents.
70
70
 
71
+ ## Daily goals
72
+
73
+ `lobstah goals` shows today's goals; `lobstah goals set "<line>" [...]`
74
+ replaces them, and `lobstah goals YYYY-MM-DD` reads a past day. Use
75
+ `lobstah goals add "<text>"` to append a goal at any time and
76
+ `lobstah goals rm <n>` to remove the numbered line shown by `lobstah goals`.
77
+ These edit today's file without repeating the first-chat card. Use
78
+ `--grounds <name>` to choose grounds and `--session <id>` to identify the helm
79
+ for writes. Files are editable Markdown at
80
+ `~/.lobstah/goals/<grounds>/YYYY-MM-DD.md` (implicit `home` uses the permanent
81
+ `fleet` storage name). Each day starts at 04:00 in the system timezone;
82
+ `[helm].timezone` can choose an IANA timezone instead.
83
+
84
+ The first user prompt of a new day adds a non-blocking reminder to the helm:
85
+ handle that message, then put yesterday's recap and a draft of today's goals
86
+ on one card. Existing goals, a `Goals for YYYY-MM-DD` card, or an already
87
+ delivered reminder suppress another ask. The helm saves the answered goals
88
+ with `goals set`; the first reminder leaves a comment in that same daily file.
89
+ The helm uses them to order work and choose the next quiet step.
90
+
91
+ `lobstah goals recap-data [YYYY-MM-DD]` prints retained dispatch results, PR
92
+ open/merge times, answered cards and closed to-dos when their
93
+ optional store exists. Its default is yesterday. First observation is not
94
+ the forge's PR creation time (older records may have only that fallback);
95
+ missing/expired records are not reconstructed.
96
+ The helm matches those facts to the goals (done, moved, stuck, plus also done),
97
+ then saves the Markdown with `lobstah goals recap YYYY-MM-DD --file <md>`.
98
+ Today's lines are pinned above `man tend` and the glass; recaps stay in the
99
+ daily files. Goals are local files, not wharf-synced state.
100
+
71
101
  ## Taking over a worker
72
102
 
73
103
  Every dispatch **is** a real harness session, running under the same CLI you
@@ -538,6 +568,20 @@ the helm files to keep.
538
568
  - **Filing a helm report.** `lobstah man file <file.md> [--attach <file> ...]
539
569
  [--title <text>]`. It is stored under the helm's grounds,
540
570
  `reports/<grounds>/<rid>/`, with the same layout, and the author is `helm`.
571
+ - **The helm's to-dos.** Reminders the helm keeps for itself ("merge #2268
572
+ once the API is in production") go in `lobstah todo add "<text>"`, not
573
+ only in the conversation. The text is free: any detail, link, or PR goes
574
+ in it.
575
+ `lobstah todo done <id>` and `lobstah todo drop <id>` close one;
576
+ `lobstah todo ls` (or bare `todo`) lists the open ones, and `--all` adds
577
+ closed ones. They are stored per grounds in `todos/<grounds>.json` with
578
+ created and updated times. `man tend`, `man report`, and the glass deck
579
+ show the open ones, and `man brief` re-injects them beside the charter at
580
+ every session start and after compaction. Open to-dos older than
581
+ `[helm].todoStaleDays` (default 3) add one line to `man tend`, for
582
+ example "3 to-dos older than 3 days: move to the issue tracker?". The helm
583
+ decides whether to raise a card and files them with the user's tracker.
584
+ A trap keeps no to-dos; with a claimed helm, only the helm writes them.
541
585
  - **Title and author.** The title is `--title`, else the page's first `#`
542
586
  heading, else the dispatch's brief title. The author is the trap name, or
543
587
  `headless`, or `helm`. A file larger than `[limits].attachmentMaxBytes` is
@@ -468,6 +468,11 @@ worktree is refused (the session lock); a stale one is adopted.
468
468
  | `soak` | Sign the worktree's trap on and take matching work. From a primary checkout, or with `--repo <key>` from outside any configured repo, it first creates a linked worktree like a dispatch does (fetch trunk, new branch from `origin/<trunk>`, `setup` commands), prints `worktree:`, `created: true`, `branch:`, and, when the session is elsewhere, `instruction: cd <path> ...`; the session works in that directory. If creation fails, nothing is signed on and the partial worktree and branch are removed. `--repo` in a linked worktree must match its repo. A session that already mans a trap re-uses it (resolved from the session id) and never gets a second worktree. `--session` is needed only on first sign-on. `--one` stows after the first catch. `--wait` registers a watcher and waits for work; a quiet timeout exits 3. Workers never run `man` verbs. |
469
469
  | `soak title-set` (alias `trap title-set`) | Confirm this session applied the title sign-on printed (`step: Apply this title: <title>`). The registration records `titleSet` and `titleSetAt` and drops `titlePending`; sign-on is complete. Until then, SessionStart and Stop remind the session once per turn, at most three times. A trap runs `soak title-set`: Claude Code's worktree isolation refuses a command line containing `trap`. |
470
470
  | `stow` | Sign the trap off (in the worktree, or elsewhere by session id: `--session <id>` or `$CLAUDE_CODE_SESSION_ID`); an unfinished catch requeues, done/failed finalizes in `done/`, and a cancelled catch finalizes as failed. Unread messages are held for `[soak].signOffGraceSecs` (default 600): they deliver if the same worktree re-soaks in time, else the daemon bounces them to the helm (at once when stow removed the worktree or the grace is `0`). A trap always stows itself freely; stowing someone else's (`--wt`) is steering — the claimed helm's alone. Stow closes the seat, never the session: an opted-in session can only be asked to stop, and a still-looping worker re-enlists visibly (`trap-signed-on`). By default stow keeps the worktree (`worktree: kept`, `reason: stow keeps the worktree; --remove removes it`), so `man throw` can bring the trap back in it; `--keep` is accepted and changes nothing. `--remove` removes the worktree when soak created it (`createdWorktree: true`) and prints `worktree: removed`, `path:`, and `returnTo:`; it still keeps it (`worktree: kept`, `reason:`) when soak did not create it, or when it holds uncommitted changes, untracked files that are not ignored, commits absent from its upstream, or no upstream. `--remove --force` explicitly allows discarding unsaved checkout files; `--force` alone refuses. The branch is deleted (`branchDeleted:`) only when all its commits are on its upstream (with no upstream: on some remote branch); otherwise `branchKept: <branch> (<reason>)`. `--wt` follows the same rules. The SessionEnd hook (`stow --quiet`) signs off only when the ending session is the trap's registered session (another session in the worktree ending is a no-op) and keeps the worktree; SessionEnd cannot tell a restart or compaction from an exit (Claude Code's `reason` is `clear`, `resume`, `logout`, `prompt_input_exit`, or `other`; Codex's is always `other`), so the grace covers a session that signs on again. |
471
+ | `report needs-decision --ask <command>` (or `--ask-path <file>`) | A trap whose harness check refused a call asks for it. Besides the status, it files a decision card with the exact command or path and three options: **Allow once** (the asking trap, one use, within the hour), **Allow always** (every trap, until revoked), **No**. Only a glass answer can allow; `man answer`, which the helm runs, can only say No. An allow writes a grant and tells the dispatch's inbox the grant id and to run the command again exactly as shown. |
472
+ | `grant <command>` (alias `trap grant`) | A person allows traps to run one command: exactly, or with `--prefix` the command followed by more arguments (never anything joined on with `;`, `&`, `|`, a redirect or a subshell). `--path <file>` allows the write tools on one file, or under a directory with a trailing slash. `--once` (one use, within the hour unless `--expires`), `--harness claude\|codex\|any`, `--trap <name>`. It asks to confirm, and refuses without a terminal or inside an agent session. Grants are kept in `grants/ledger.jsonl`, an append-only, hash-chained list of grants, uses and revocations; a damaged ledger grants nothing. Grants apply to traps only. Claude Code honours them through the plugin's mod (before the auto-mode classifier) and its PermissionRequest hook; Codex through its PermissionRequest hook (before the approval reviewer). A deny rule, a tool's own check and the organization's limits still stand. |
473
+ | `grants` (alias `trap grants`) | The grants in force: id, what, once or always, harness, trap, who granted it, when, uses, expiry. `--all` adds spent, expired and revoked ones; `--json` for machines. A trap checks a relayed approval here: a grant listed is the person's, a message saying they approved is not. |
474
+ | `revoke <id>` (alias `trap revoke`) | Revoke a grant. Anyone may take a permission away. |
475
+ | `trap bypass <trap> on\|off` | A person, at a terminal, starts the trap with no permission checks from its next start: Claude Code `--permission-mode bypassPermissions`, Codex `--dangerously-bypass-approvals-and-sandbox`. It warns that the trap then acts as the person's account with no checks, for isolated machines only, and asks to confirm. A running session keeps its mode. Off needs no terminal. |
471
476
  | sign-off grace | For `[soak].signOffGraceSecs` after a trap signs off (`~/.lobstah/signed-off/<trap>.json`), its address is held: `send wt:<trap>` queues and warns instead of refusing, held messages wait, and work addressed to it raises no `bait-orphaned` notice. A re-soak of the same worktree releases the hold; after the grace, the daemon bounces the held messages (`message-bounced`). |
472
477
  | address | `--for wt:<trap>` targets one trap; `session:<id>` is an alias resolved to the trap at dispatch time. **Sticky:** addressed work is never the daemon's — it waits for its trap; an orphan (trap gone) surfaces as a `bait-orphaned` notice for the helm to re-address, release, or cancel. Delivery stamps a receipt (`deliveredTo`/`deliveredAt`) into evidence. Unaddressed work defers to a parked matching trap for `[soak].deferSecs`, then the daemon spawns headless. |
473
478
  | message | `send wt:<trap> "<text>"` — a conversational continuation, not work: no branch, no catch, no report obligation. Delivered before bait at the trap's next park, stamped with its sender (`helm` / `session:<id>` / `terminal`); undeliverable messages bounce to the helm as notices. |
@@ -517,6 +522,7 @@ silently ignored). Read verbs (`man tend`, `man brief`, `man throw --dry-run`,
517
522
  | `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
523
  | 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
524
  | 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. |
525
+ | to-do | A reminder the helm keeps for itself (`lobstah todo add`), stored per grounds in `todos/<grounds>.json`. Shown in `man tend`, `man report`, and the glass, and re-injected beside the charter by `man brief`. Traps keep none. |
520
526
  | 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
527
 
522
528
  ## Attention contract
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lobstah",
3
- "version": "0.7.6",
3
+ "version": "0.7.7",
4
4
  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
5
5
  "license": "MIT",
6
6
  "author": "aequitas labs LLC",