lobstah 0.6.9 → 0.6.10

package/dist/main.js

@@ -1875,6 +1875,10 @@ function expandHome(p) {
 function loadConfig() {
   const file = configPath();
   const raw = fs8.existsSync(file) ? parse(fs8.readFileSync(file, "utf8")) : {};
+  const readySettleSecs = raw.readySettleSecs ?? 600;
+  if (typeof readySettleSecs !== "number" || !Number.isFinite(readySettleSecs) || readySettleSecs < 0) {
+    throw new Error(`readySettleSecs must be a non-negative number in ${configPath()}`);
+  }
   const reposRaw = raw.repos ?? {};
   const repos = {};
   for (const [key, r] of Object.entries(reposRaw)) {
@@ -1911,6 +1915,7 @@ function loadConfig() {
     notifyCommand: raw.notifyCommand ? String(raw.notifyCommand) : void 0,
     notifyVerbs: Array.isArray(raw.notifyVerbs) ? raw.notifyVerbs.map(String) : void 0,
     remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0,
+    readySettleSecs,
     attentionKinds: parseAttentionKinds(raw.attentionKinds)
   };
 }
@@ -5120,7 +5125,7 @@ function normalizeChecks(rollup) {
   }
   return [...latest.values()].map((v) => v.check).sort((a, b) => a.name.localeCompare(b.name));
 }
-function prStandingKinds(pr) {
+function prStandingKinds(pr, settle2) {
   if (pr.state !== "OPEN")
     return [];
   const out = [];
@@ -5134,8 +5139,11 @@ function prStandingKinds(pr) {
     out.push("pr:checks");
   if (isConflicting(pr.mergeStateStatus))
     out.push("pr:conflict");
-  if (!pr.checks.unknown && !pr.draft && !review && isMergeable(pr.mergeStateStatus) && failed === 0 && pending === 0 && (pr.reviewDecision === "APPROVED" || total > 0))
-    out.push("pr:ready");
+  if (!pr.checks.unknown && !pr.draft && !review && isMergeable(pr.mergeStateStatus) && failed === 0 && pending === 0 && (pr.reviewDecision === "APPROVED" || total > 0)) {
+    const since = Date.parse(pr.standingSince?.["pr:ready"] ?? pr.observedAt);
+    if (!settle2 || settle2.readySettleSecs === 0 || settle2.now >= since + settle2.readySettleSecs * 1e3)
+      out.push("pr:ready");
+  }
   return out;
 }
 function prReview(view) {
@@ -5491,7 +5499,7 @@ function upsertPr(pr, dispatchId) {
     const merged = { ...before ?? {}, ...pr, failingChecks: pr.failingChecks };
     const standingSince = {};
     for (const kind of prStandingKinds(merged)) {
-      standingSince[kind] = before?.standingSince?.[kind] ?? pr.observedAt;
+      standingSince[kind] = kind === "pr:ready" && before?.headSha !== pr.headSha ? pr.observedAt : before?.standingSince?.[kind] ?? pr.observedAt;
     }
     const after = {
       ...merged,
@@ -6238,6 +6246,21 @@ async function allocate(repo, id, fromRemoteBranch = repo.trunk) {
   await runSetup(repo, dir);
   return dir;
 }
+async function recoverWorktree(repo, id) {
+  const dir = worktreePath(id);
+  try {
+    if (fs31.statSync(path27.join(dir, ".git")).isFile()) {
+      const branch = await git2(dir, "symbolic-ref", "--quiet", "HEAD");
+      const root = await git2(dir, "rev-parse", "--show-toplevel");
+      const common = await git2(dir, "rev-parse", "--path-format=absolute", "--git-common-dir");
+      const mine = await git2(repo.path, "rev-parse", "--path-format=absolute", "--git-common-dir");
+      if (branch === `refs/heads/lobstah/${id}` && realpath(root) === realpath(dir) && realpath(common) === realpath(mine))
+        return dir;
+    }
+  } catch {
+  }
+  throw new Error(`unrecorded worktree at ${dir} for ${id} \u2014 ownership not proven (expected lobstah/${id} in ${repo.path}); inspect and preserve it, then relocate the conflicting checkout before retrying`);
+}
 async function runSetup(repo, dir) {
   for (const cmd of repo.setup ?? []) {
     await shell(cmd, { cwd: dir, env: { ...process.env, ...repo.env ?? {} } });
@@ -7776,17 +7799,19 @@ async function main(activeDir, lane, seams = {}) {
   });
   const wtFile = path64.join(activeDir, "worktree.json");
   let recorded;
+  let recovered = false;
   let choice;
   if (fs77.existsSync(wtFile)) {
     recorded = JSON.parse(fs77.readFileSync(wtFile, "utf8")).path;
     if (!fs77.existsSync(recorded))
       throw new Error(`recorded worktree ${recorded} is gone`);
   } else if (fs77.existsSync(worktreePath(id))) {
-    throw new Error(`unrecorded worktree already exists for ${id} \u2014 refusing to proceed`);
+    recorded = await recoverWorktree(repo, id);
+    recovered = true;
   } else if (descriptor.followUp && cfg.limits.reuseWorktree !== false) {
     choice = await deps.chooseWorktree({ id, lane, repoKey: descriptor.repo, repo, followUp: descriptor.followUp });
   }
-  const worktreeNote = choice ? choice.reuse ? `reusing worktree of ${short3(choice.from)}` : `fresh worktree (${choice.reason})` : void 0;
+  const worktreeNote = choice ? choice.reuse ? `reusing worktree of ${short3(choice.from)}` : `fresh worktree (${choice.reason})` : recovered ? "recovered own unrecorded worktree" : void 0;
   const firstModel = modelForHarness(plan.harness, resolved.model);
   const firstNote = [
     wake ? `woke from pause: ${wake}` : attempts > 1 ? `attempt ${attempts}` : void 0,
@@ -7805,7 +7830,13 @@ async function main(activeDir, lane, seams = {}) {
   let cwd;
   if (recorded) {
     cwd = recorded;
-    acquireWorktreeLock(cwd, id, lane);
+    const held = acquireWorktreeLock(cwd, id, lane);
+    if (held)
+      throw new Error(`worktree at ${cwd} is in use by ${held.id} \u2014 wait for that dispatch to release it before retrying`);
+    if (recovered) {
+      await deps.prepareReuse(repo, cwd);
+      fs77.writeFileSync(wtFile, JSON.stringify({ path: cwd }, null, 2));
+    }
   } else if (choice?.reuse) {
     cwd = choice.path;
     const { setupRan } = await deps.prepareReuse(repo, cwd);
@@ -10433,8 +10464,7 @@ function removeAck(key) {
 }
 var sha2 = (v) => createHash7("sha1").update(JSON.stringify(v)).digest("hex").slice(0, 16);
 function prStateHash(pr) {
-  const readySince = pr.standingSince?.["pr:ready"];
-  if (readySince) return sha2({ "pr:ready": readySince });
+  if (prStandingKinds(pr).includes("pr:ready")) return prReadyStateHash(pr.headSha);
   return sha2({
     headSha: pr.headSha,
     state: pr.state,
@@ -10447,15 +10477,18 @@ function prStateHash(pr) {
     repair: pr.repair ? { headSha: pr.repair.headSha, kind: pr.repair.kind, status: pr.repair.status, reason: pr.repair.reason } : void 0
   });
 }
+var prReadyStateHash = (headSha) => sha2({ "pr:ready": headSha });
 function currentAck(key, stateHash) {
   const a = readAck(key);
   return a && a.stateHash === stateHash ? a : void 0;
 }
 function pruneStaleAcks(standing) {
-  const hashes = new Map(standing.map((s) => [s.key, s.stateHash]));
+  const items = new Map(standing.map((s) => [s.key, s]));
   const pruned = [];
   for (const a of listAcks()) {
-    const h = hashes.get(a.key);
+    const item = items.get(a.key);
+    if (a.kind === "pr:ready" && item?.headSha && a.stateHash === prReadyStateHash(item.headSha)) continue;
+    const h = item?.stateHash;
     if (h !== void 0 && h !== a.stateHash && removeAck(a.key)) pruned.push(a.key);
   }
   return pruned;
@@ -11632,7 +11665,7 @@ function prAttention(now2, observed = observedPrs(), cfg = loadConfig()) {
   );
   const out = [];
   for (const { id, lane, pr, dispatch } of observed) {
-    const kinds = prKinds(pr).filter(
+    const kinds = prKinds(pr, { readySettleSecs: cfg.readySettleSecs, now: now2 }).filter(
       (kind) => kind !== "pr:ready" || !readyBlockedByStack(
         pr,
         observed.map((x) => x.pr)
@@ -11648,7 +11681,8 @@ function prAttention(now2, observed = observedPrs(), cfg = loadConfig()) {
       if (!human.show) continue;
       const repairCannotAct = human.reason !== void 0 && !["auto-repair is off", "not owned by lobstah", "no active PR watch"].includes(human.reason);
       if (!repairCannotAct && onTheHook(kind, chain, { reviewRounds, watchFollowUp })) continue;
-      const standingSince = pr.standingSince?.[kind] ?? pr.observedAt;
+      const conditionSince = pr.standingSince?.[kind] ?? pr.observedAt;
+      const standingSince = kind === "pr:ready" ? new Date(Date.parse(conditionSince) + cfg.readySettleSecs * 1e3).toISOString() : conditionSince;
       out.push({
         kind,
         key: ref?.key ?? pr.url,
@@ -12379,6 +12413,7 @@ function renderDigest(d) {
 }
 
 // apps/cli/src/charter.ts
+var HELM_REMINDER = "Helm reminder: any question or choice for the human goes on a card with lobstah man ask, not only in chat.";
 function charter(g) {
   const repos = g.repos.length > 0 ? g.repos.join(", ") : "(no repos configured)";
   return `the helm charter \u2014 grounds "${g.name}" (${repos})
@@ -12389,6 +12424,7 @@ Role:
 - Triage incoming work. Dispatch it. Review each catch. Decide requeue or cancel.
 - Do not do the work yourself. Write a self-contained brief and dispatch it.
 - Answer a worker's question when you can decide. Send the answer. Ask the human with \`lobstah man ask\` when the choice is theirs.
+- ${HELM_REMINDER}
 
 Fences:
 - The daemon claims, spawns, and restarts workers. Do not supervise a running catch.
@@ -16666,7 +16702,7 @@ var COMMANDS = {
   "man:init": { flags: { "--shared": {}, "--global": {}, "--marker": {} } },
   "man:haul": { flags: { "--timeout": { value: "<secs>" }, "--park": {} } },
   "man:brief": { flags: {} },
-  hook: { flags: {}, subverbs: ["session-start", "stop", "post-tool-use", "session-end"], maxPositionals: 1 },
+  hook: { flags: {}, subverbs: ["session-start", "user-prompt-submit", "stop", "post-tool-use", "session-end"], maxPositionals: 1 },
   "man:file": {
     flags: { "--attach": { value: "<file>", repeatable: true }, "--title": { value: "<text>" }, "--grounds": { value: "<name>" }, "--session": { value: "<id>" } },
     positionals: "<file.md>"
@@ -16824,7 +16860,8 @@ Stores the answer; the helm's man wait receives it as decision-answer.`,
   "man:brief": `SessionStart-hook entry point: announce the session id and fleet state into
 the conversation.`,
   hook: `The plugin hook entry points. Each detects the session's role (helm, trap, or
-neither): session-start runs man brief, stop runs man haul (--park, --timeout),
+neither): session-start runs man brief, user-prompt-submit adds a helm card reminder,
+stop runs man haul (--park, --timeout),
 post-tool-use runs soak beat, session-end runs stow --quiet. The older commands
 stay as aliases.`,
   __runner: `Internal: run one dispatch inside the compiled binary (the daemon re-execs
@@ -17062,7 +17099,7 @@ lobstah man (orchestrator sessions \u2014 bare \`lobstah man\` prints the manual
                                   ~/.claude/settings.json with --global (any
                                   directory with a .lobstah-man file then
                                   parks); --marker touches .lobstah-man.
-  hook session-start|stop|post-tool-use|session-end
+  hook session-start|user-prompt-submit|stop|post-tool-use|session-end
                                   the plugin hook entry points: each
                                   detects the session's role (helm, trap,
                                   or neither). session-start = man brief,
@@ -17410,6 +17447,16 @@ var HOOK_COMMANDS = {
 };
 async function mainCli() {
   let [cmd, ...args] = process.argv.slice(2);
+  if (cmd === "hook" && args[0] === "user-prompt-submit") {
+    try {
+      const hook = readHookStdin();
+      if (hook?.session_id && !trapBySession(hook.session_id) && helmOf(hook.session_id)) {
+        console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: HELM_REMINDER } }));
+      }
+    } catch {
+    }
+    return;
+  }
   if (cmd === "soak" && args[0] === "beat" || cmd === "hook" && args[0] === "post-tool-use") {
     runBeat();
     return;

package/dist/runner.js

@@ -962,6 +962,10 @@ function expandHome(p) {
 function loadConfig() {
   const file = configPath();
   const raw = fs3.existsSync(file) ? parse(fs3.readFileSync(file, "utf8")) : {};
+  const readySettleSecs = raw.readySettleSecs ?? 600;
+  if (typeof readySettleSecs !== "number" || !Number.isFinite(readySettleSecs) || readySettleSecs < 0) {
+    throw new Error(`readySettleSecs must be a non-negative number in ${configPath()}`);
+  }
   const reposRaw = raw.repos ?? {};
   const repos = {};
   for (const [key, r] of Object.entries(reposRaw)) {
@@ -998,6 +1002,7 @@ function loadConfig() {
     notifyCommand: raw.notifyCommand ? String(raw.notifyCommand) : void 0,
     notifyVerbs: Array.isArray(raw.notifyVerbs) ? raw.notifyVerbs.map(String) : void 0,
     remindSecs: raw.remindSecs !== void 0 ? Number(raw.remindSecs) : void 0,
+    readySettleSecs,
     attentionKinds: parseAttentionKinds(raw.attentionKinds)
   };
 }
@@ -2788,6 +2793,21 @@ async function allocate(repo, id, fromRemoteBranch = repo.trunk) {
   await runSetup(repo, dir);
   return dir;
 }
+async function recoverWorktree(repo, id) {
+  const dir = worktreePath(id);
+  try {
+    if (fs18.statSync(path15.join(dir, ".git")).isFile()) {
+      const branch = await git(dir, "symbolic-ref", "--quiet", "HEAD");
+      const root = await git(dir, "rev-parse", "--show-toplevel");
+      const common = await git(dir, "rev-parse", "--path-format=absolute", "--git-common-dir");
+      const mine = await git(repo.path, "rev-parse", "--path-format=absolute", "--git-common-dir");
+      if (branch === `refs/heads/lobstah/${id}` && realpath(root) === realpath(dir) && realpath(common) === realpath(mine))
+        return dir;
+    }
+  } catch {
+  }
+  throw new Error(`unrecorded worktree at ${dir} for ${id} \u2014 ownership not proven (expected lobstah/${id} in ${repo.path}); inspect and preserve it, then relocate the conflicting checkout before retrying`);
+}
 async function runSetup(repo, dir) {
   for (const cmd of repo.setup ?? []) {
     await shell(cmd, { cwd: dir, env: { ...process.env, ...repo.env ?? {} } });
@@ -3545,16 +3565,18 @@ async function main(activeDir, lane, seams = {}) {
   });
   const wtFile = path17.join(activeDir, "worktree.json");
   let recorded;
+  let recovered = false;
   let choice;
   if (fs20.existsSync(wtFile)) {
     recorded = JSON.parse(fs20.readFileSync(wtFile, "utf8")).path;
     if (!fs20.existsSync(recorded)) throw new Error(`recorded worktree ${recorded} is gone`);
   } else if (fs20.existsSync(worktreePath(id))) {
-    throw new Error(`unrecorded worktree already exists for ${id} \u2014 refusing to proceed`);
+    recorded = await recoverWorktree(repo, id);
+    recovered = true;
   } else if (descriptor.followUp && cfg.limits.reuseWorktree !== false) {
     choice = await deps.chooseWorktree({ id, lane, repoKey: descriptor.repo, repo, followUp: descriptor.followUp });
   }
-  const worktreeNote = choice ? choice.reuse ? `reusing worktree of ${short3(choice.from)}` : `fresh worktree (${choice.reason})` : void 0;
+  const worktreeNote = choice ? choice.reuse ? `reusing worktree of ${short3(choice.from)}` : `fresh worktree (${choice.reason})` : recovered ? "recovered own unrecorded worktree" : void 0;
   const firstModel = modelForHarness(plan.harness, resolved.model);
   const firstNote = [
     wake ? `woke from pause: ${wake}` : attempts > 1 ? `attempt ${attempts}` : void 0,
@@ -3573,7 +3595,12 @@ async function main(activeDir, lane, seams = {}) {
   let cwd;
   if (recorded) {
     cwd = recorded;
-    acquireWorktreeLock(cwd, id, lane);
+    const held = acquireWorktreeLock(cwd, id, lane);
+    if (held) throw new Error(`worktree at ${cwd} is in use by ${held.id} \u2014 wait for that dispatch to release it before retrying`);
+    if (recovered) {
+      await deps.prepareReuse(repo, cwd);
+      fs20.writeFileSync(wtFile, JSON.stringify({ path: cwd }, null, 2));
+    }
   } else if (choice?.reuse) {
     cwd = choice.path;
     const { setupRan } = await deps.prepareReuse(repo, cwd);

package/docs/configuration.md

@@ -16,6 +16,7 @@ keys of that section.
 | `notifyVerbs` | `["needs-decision", "blocked", "done", "failed"]` | Which verbs fire `notifyCommand`. |
 | `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. |
+| `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. |
 
 ## `[repos.<key>]` — workspace definitions
 

package/docs/vocabulary.md

@@ -534,7 +534,7 @@ never until someone acknowledges it.
 | `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. |
 | `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. |
 | `pr:conflict` | An open PR conflicts with its base, and lobstah cannot repair it, has exhausted attempts, or is configured not to repair. | The merge state leaves `DIRTY`, or merged / closed. |
-| `pr:ready` | An open, non-draft PR has no review condition, a mergeable state (`CLEAN`, `HAS_HOOKS`, or `UNSTABLE`), and no failed, pending, or unknown latest checks. It is approved or has at least one check. | Merged or closed, or the ready conditions stop holding. |
+| `pr:ready` | An open, non-draft PR has no review condition, a mergeable state (`CLEAN`, `HAS_HOOKS`, or `UNSTABLE`), and no failed, pending, or unknown latest checks. It is approved or has at least one check, continuously on the same head for `readySettleSecs` (default 600; `0` is immediate). Attention reads re-evaluate expiry without requiring a new forge event. | Merged or closed, or the ready conditions stop holding; any not-ready observation or new head resets settling. |
 | `report` | A filed report (`report --report`, `man file`) has no ack for this filing. Opt-in. Key `report:<lane>:<uuid>` or `report:helm:<grounds>:<rid>`. | Not cleared: it stays listed until culled. `lobstah attention ack <key>` acks it, and a newer report in the same chain acks the older; an acked report no longer walks. |
 
 `pr:*` kinds read only the `pr:` watch's evidence — never a forge call —
@@ -563,7 +563,7 @@ reminder loop apply the same predicate.
 
 | Word | Meaning |
 | ---- | ------- |
-| 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 `notifyCommand` 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 when `pr:ready` began standing (its `standingSince`), so repeat observations of the same ready state keep the ack and ready → not ready → ready re-stands it once. |
+| 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 `notifyCommand` 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. |
 | 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. |
 | 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. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lobstah",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
   "license": "MIT",
   "author": "aequitas labs LLC",