lobstah 0.1.0 → 0.1.1

package/README.md

@@ -1,32 +1,41 @@
-# lobstah
+# lobstah 🦞✨
+
+*Nobody stares at the water.*
 
 [![CI](https://github.com/aequitas-labs/lobstah/actions/workflows/ci.yml/badge.svg)](https://github.com/aequitas-labs/lobstah/actions/workflows/ci.yml)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
 ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)
+[![npm](https://img.shields.io/npm/v/lobstah)](https://www.npmjs.com/package/lobstah)
 ![Harnesses](https://img.shields.io/badge/harnesses-Claude%20Code%20%7C%20Codex-8A2BE2)
 
-Harness-agnostic, token-efficient supervisor for local coding agents.
+Harness-agnostic, token-efficient supervision framework for coding agents.
 
-One coding agent in a terminal is fine. Three is tab-juggling: which one is
-stuck, which one is waiting on a question nobody saw, which one died forty
-minutes ago? And the cloud sandboxes can't help when the work needs your
-actual machine — private toolchains, local services, unpushed branches,
-credentials that never leave the laptop.
+You were promised agents that do the work. Somehow, watching them became the
+work: which one is stuck, which one is waiting on an answer nobody saw, which
+one died forty minutes ago. Watching is why you run two agents instead of
+ten.
 
-Lobstah runs coding agents like services instead of terminal tabs. Each
-dispatch gets an isolated git worktree; a daemon tells a dead process from a
-wedged one and treats them differently (auto-restart vs. a bounded
-fork-with-nudge ladder); status and evidence land on disk. Supervision spends
-zero tokens — no model watches the models.
+A trap doesn't fish faster for being watched, and an agent doesn't code
+faster either. You **lob** bait into a trap and walk away. Each dispatch runs
+in its own git worktree; the daemon tells a dead process from a wedged one
+and recovers each; status and evidence land on disk. Supervision costs
+nothing — no tokens, no attention — so the whole fleet fits in one
+conversation, and **your agents just bring home the lobstahs**.
 
-## Requirements
+## Requirements 📋
 
 - Node 20+, git, pnpm
 - An authenticated harness CLI: `claude` (Claude Code) and/or Codex. Lobstah
   never handles harness login — you authenticate your own CLI; lobstah invokes it.
 
-## Install
+## Install ⚓
+
+```bash
+npm i -g lobstah
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/aequitas-labs/lobstah
@@ -35,7 +44,7 @@ pnpm install && pnpm build
 ln -s "$PWD/bin/lobstah" /usr/local/bin/lobstah   # Windows: add .\bin to PATH
 ```
 
-## Quick start
+## Quick start 🪝
 
 ```bash
 lobstah init                 # ~/.lobstah + example config
@@ -65,29 +74,31 @@ lobstah swap <uuid> --harness codex   # hand an active dispatch to a fresh sessi
 lobstah catch <uuid>                  # the evidence: branch, commits, PR, session
 lobstah cancel <uuid>
 lobstah cull --apply                  # sweep aged results and orphaned worktrees
+lobstah man tend                      # the whole string: fleet verdict, waiting
+                                      # questions, each item's chain + PR + gate
 ```
 
-(Prefer the water? `set --bait`, `buoys`, and `buoy` alias `dispatch`, `ls`,
-and `status`.)
+Prefer the water? 🌊 `set --bait`, `buoys`, and `buoy` alias `dispatch`,
+`ls`, and `status`.
 
-Dispatches report six verbs — `working`, `needs-decision`, `blocked`,
-`paused`, `done`, `failed` — validated at the write path. `done` means the
-brief is fulfilled; merging is never the dispatch's job.
+Dispatches report six verbs: `working`, `needs-decision`, `blocked`,
+`paused`, `done`, `failed`. The write path rejects anything else. `done`
+means the brief is fulfilled. Merging is never the dispatch's job.
 
-Everything lives under `$LOBSTAH_HOME` (default `~/.lobstah`); multiple
-isolated instances are just multiple homes, one daemon per home (enforced).
+Everything lives under `$LOBSTAH_HOME` (default `~/.lobstah`). To run more
+instances, use more homes. One daemon per home, enforced.
 
-## When something needs you
+## When something needs you 🛎️
 
-Set one config line and the daemon pings you on `needs-decision`, `blocked`,
-`done`, and `failed` — `notifyCommand = "ntfy pub my-topic ..."` — no model in
-the loop. Driving lobstah from an agent session instead? `lobstah man` prints
-the lobsterman's manual: `man wait` blocks until a dispatch needs attention
-(unanswered questions re-fire until answered), and `man init` installs a
-Claude Code Stop hook that parks the session on the fleet and continues the
-turn the moment something does.
+Set one config line — `notifyCommand = "ntfy pub my-topic ..."` — and the
+daemon pings you on `needs-decision`, `blocked`, `done`, and `failed`. No
+model in the loop. Driving lobstah from an agent session instead? `lobstah
+man` prints the lobsterman's manual. `man wait` blocks until a dispatch needs
+attention, and unanswered questions re-fire until answered. `man init`
+installs a Claude Code Stop hook that parks the session on the fleet and
+continues the turn the moment something needs it.
 
-## Add-ons
+## Add-ons 🎣
 
 - **Tracker pickup** — `lobstah pick` polls Linear and GitHub outbound (no
   webhooks, no tunnel), dispatches assigned work, streams status back as
@@ -100,7 +111,7 @@ turn the moment something does.
   supervises, and hands you outcomes, woken by the `lobstah man` commands.
   [docs/lobsterman.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/lobsterman.md)
 
-## How it holds together
+## How it holds together 🧭
 
 ```
 CLI / pick / OpenClaw plugin / anything ──writes──>  ~/.lobstah/queue/
@@ -111,10 +122,12 @@ daemon ──spawn──> runner (one per dispatch) ──SDK──> harness CLI
    └── dead/wedged classification · bounded restart ladder · zero tokens
 ```
 
-Design: [docs/design.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/design.md).
-Verified by CI on Linux and Windows, live end-to-end runs on both harnesses,
-and fault-injection drills (SIGKILL'd runners respawn and complete; SIGSTOP'd
-ones are classified wedged, killed cleanly, and recover with a nudge).
+Design: [docs/design.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/design.md). Every verb, verdict, and gate in
+one place: [docs/vocabulary.md](https://github.com/aequitas-labs/lobstah/blob/main/docs/vocabulary.md).
+Verified by CI on Linux and Windows, by live end-to-end runs on both
+harnesses, and by fault-injection drills. A SIGKILL'd runner respawns and
+completes. A SIGSTOP'd one is classified wedged, killed cleanly, and recovers
+with a nudge.
 
 ## Non-goals
 

package/dist/main.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // apps/cli/src/main.ts
-import * as fs16 from "node:fs";
-import * as path12 from "node:path";
+import * as fs18 from "node:fs";
+import * as path14 from "node:path";
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { spawnSync } from "node:child_process";
 
@@ -1152,9 +1152,17 @@ function reconcileOne(st, cfg, log) {
   const statusLog = readStatusLog(st.id, st.lane);
   const lastVerb = statusLog.at(-1)?.verb;
   const alive = st.runner ? pidAlive(st.runner.pid, st.runner.processStartTime) : void 0;
-  if (cancelRequested(st.id, st.lane) && st.runner && alive) {
-    log(`${st.id}: cancel requested, killing group ${st.runner.pid}`);
-    killGroup(st.runner.pid);
+  if (cancelRequested(st.id, st.lane)) {
+    if (st.runner && alive) {
+      log(`${st.id}: cancel requested, killing group ${st.runner.pid}`);
+      killGroup(st.runner.pid);
+      return;
+    }
+    if (lastVerb !== "done" && lastVerb !== "failed") {
+      appendStatus(st.id, st.lane, "failed", "cancelled by request; work preserved");
+    }
+    finalize(st);
+    log(`${st.id}: cancelled, finalized`);
     return;
   }
   const cls = classify({
@@ -1396,9 +1404,15 @@ function loadPickupConfig() {
   if (ln) {
     const token = resolveTokenSource({ tokenEnv: "LINEAR_TOKEN", ...ln }, "pickup.linear");
     token();
+    const assignField = ln.assignField ? String(ln.assignField) : "assignee";
+    if (assignField !== "assignee" && assignField !== "delegate") {
+      throw new Error(`pickup.linear.assignField must be "assignee" or "delegate", got "${assignField}"`);
+    }
     out.linear = {
       token,
+      assignField,
       startState: String(ln.startState ?? "Todo"),
+      startStateTypes: Array.isArray(ln.startStateTypes) ? ln.startStateTypes.map(String) : void 0,
       claimedState: String(ln.claimedState ?? "In Progress"),
       doneState: String(ln.doneState ?? "In Review"),
       route: ln.route ?? {}
@@ -1624,6 +1638,15 @@ When the change is complete, commit it, push the branch, and open a PR against $
     const pr = await this.api("GET", `/repos/${this.cfg.repo}/pulls/${n}`);
     return pr.state === "open" ? this.toCandidate(pr) : void 0;
   }
+  async disposition(n) {
+    const pr = await this.api("GET", `/repos/${this.cfg.repo}/pulls/${n}`);
+    if (pr.state === "open")
+      return "open";
+    return pr.merged_at ? "merged" : "closed";
+  }
+  forgeRepo() {
+    return this.cfg.repo;
+  }
   async updateBranch(n) {
     await this.api("PUT", `/repos/${this.cfg.repo}/pulls/${n}/update-branch`, {});
   }
@@ -1669,12 +1692,14 @@ var LinearSource = class {
     }
     return json.data;
   }
-  async assigned(stateName) {
-    const data = await this.gql(`query($state: String!) {
-        issues(filter: { assignee: { isMe: { eq: true } }, state: { name: { eq: $state } } }, first: 50) {
-          nodes { id identifier title description state { name } team { key id } }
+  async assigned(stateName, byTypes) {
+    const field = this.cfg.assignField ?? "assignee";
+    const stateFilter = byTypes?.length ? { type: { in: byTypes } } : { name: { eq: stateName } };
+    const data = await this.gql(`query($filter: IssueFilter!) {
+        issues(filter: $filter, first: 50) {
+          nodes { id identifier title description state { name type } team { key id } }
         }
-      }`, { state: stateName });
+      }`, { filter: { [field]: { isMe: { eq: true } }, state: stateFilter } });
     return data.issues.nodes;
   }
   async stateId(teamId, name) {
@@ -1692,7 +1717,7 @@ var LinearSource = class {
   }
   async issueByKey(key) {
     const identifier = key.replace(/^linear:/, "");
-    const data = await this.gql(`query($id: String!) { issue(id: $id) { id identifier title description state { name } team { key id } } }`, { id: identifier });
+    const data = await this.gql(`query($id: String!) { issue(id: $id) { id identifier title description state { name type } team { key id } } }`, { id: identifier });
     return data.issue;
   }
   async moveTo(issue, stateName) {
@@ -1703,7 +1728,7 @@ var LinearSource = class {
     await this.gql(`mutation($id: String!, $body: String!) { commentCreate(input: { issueId: $id, body: $body }) { success } }`, { id: issue.id, body });
   }
   async poll() {
-    const issues = await this.assigned(this.cfg.startState);
+    const issues = await this.assigned(this.cfg.startState, this.cfg.startStateTypes);
     return issues.flatMap((issue) => {
       const repoKey = this.cfg.route[issue.team.key];
       if (!repoKey)
@@ -1725,7 +1750,8 @@ When the change is complete, commit it, push the branch, and open a PR whose des
   }
   async claim(item) {
     const issue = await this.issueByKey(item.key);
-    if (issue.state.name !== this.cfg.startState)
+    const stillWaiting = this.cfg.startStateTypes?.length ? this.cfg.startStateTypes.includes(issue.state.type) : issue.state.name === this.cfg.startState;
+    if (!stillWaiting)
       return false;
     await this.moveTo(issue, this.cfg.claimedState);
     return true;
@@ -1887,8 +1913,57 @@ async function reconcileLoop(source, state, log = () => {
 
 // apps/pick/dist/loops/merge.js
 import { randomUUID as randomUUID2 } from "node:crypto";
+import * as fs15 from "node:fs";
+import * as path11 from "node:path";
+
+// apps/pick/dist/merge-view.js
 import * as fs14 from "node:fs";
 import * as path10 from "node:path";
+function viewPath() {
+  return path10.join(lobstahHome(), "pickup", "merge-view.json");
+}
+function readMergeView() {
+  try {
+    return JSON.parse(fs14.readFileSync(viewPath(), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function writeMergeView(view) {
+  const file = viewPath();
+  fs14.mkdirSync(path10.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs14.writeFileSync(tmp, JSON.stringify(view, null, 2));
+  fs14.renameSync(tmp, file);
+}
+var RECENT_RETENTION_MS = 48 * 36e5;
+async function recordMergeView(repo, open, disposition, now = /* @__PURE__ */ new Date()) {
+  const prev = readMergeView();
+  const recent = (prev?.recent ?? []).filter((r) => now.getTime() - Date.parse(r.at) < RECENT_RETENTION_MS);
+  const stillOpen = new Set(open.map((p) => p.number));
+  for (const was of prev?.open ?? []) {
+    if (stillOpen.has(was.number))
+      continue;
+    try {
+      const d = await disposition(was.number);
+      if (d === "open")
+        continue;
+      recent.push({ number: was.number, url: was.url, disposition: d, at: now.toISOString() });
+    } catch {
+    }
+  }
+  writeMergeView({ updatedAt: now.toISOString(), repo, open, recent });
+}
+function readPickupMap() {
+  try {
+    const raw = JSON.parse(fs14.readFileSync(path10.join(lobstahHome(), "pickup", "state.json"), "utf8"));
+    return raw.map ?? {};
+  } catch {
+    return {};
+  }
+}
+
+// apps/pick/dist/loops/merge.js
 function qualifyingSet(policy, pr) {
   const restricted = pr.labels.some((l) => policy.restrictedLabels.includes(l));
   if (restricted || !policy.assigneeApproves)
@@ -1915,7 +1990,7 @@ function rebaseBrief(pr) {
 }
 function choreVerdict(uuid) {
   const d = laneDirs("chore");
-  if (fs14.existsSync(path10.join(d.active, uuid)) || fs14.existsSync(path10.join(d.queue, `${uuid}.json`)))
+  if (fs15.existsSync(path11.join(d.active, uuid)) || fs15.existsSync(path11.join(d.queue, `${uuid}.json`)))
     return "active";
   const last = readStatusLog(uuid, "chore").at(-1)?.verb;
   return last === "done" ? "done" : "failed";
@@ -1924,54 +1999,78 @@ async function mergeLoop(ms, policy, state, log = () => {
 }) {
   if (!policy.enabled)
     return;
+  const observed = [];
+  const observe = (pr, gate) => {
+    const m = /^lobstah\/([0-9a-f-]{36})$/.exec(pr.headRef);
+    observed.push({
+      number: pr.number,
+      url: pr.url,
+      headRef: pr.headRef,
+      headSha: pr.headSha,
+      mergeableState: pr.mergeableState,
+      gate,
+      uuid: m?.[1]
+    });
+  };
   for (const candidate of await ms.mergeCandidates()) {
     const prKey = `${ms.name}#${candidate.number}`;
     const rebase = state.rebase(prKey);
     if (rebase) {
-      if (rebase.failed)
+      if (rebase.failed) {
+        observe(candidate, "rebase-failed");
         continue;
+      }
       const verdict = choreVerdict(rebase.uuid);
-      if (verdict === "active")
+      if (verdict === "active") {
+        observe(candidate, `conflict-chore:${rebase.uuid}`);
         continue;
+      }
       if (verdict === "failed") {
         await ms.comment(candidate.number, `Automated rebase failed (dispatch ${rebase.uuid}) \u2014 needs a human.`);
         await ms.addLabel(candidate.number, "needs-human");
         state.failRebase(prKey);
         log(`${prKey}: rebase chore failed, flagged for a human`);
+        observe(candidate, "rebase-failed");
         continue;
       }
       state.clearRebase(prKey);
     }
     const provisional = qualifiedApproval(policy, candidate);
-    if (!provisional)
-      continue;
-    if (state.approvalConsumed(approvalDedupKey(candidate, provisional)))
+    if (!provisional || state.approvalConsumed(approvalDedupKey(candidate, provisional))) {
+      observe(candidate, "waiting-approval");
       continue;
+    }
     const pr = await ms.refresh(candidate.number);
     if (!pr)
       continue;
     const approval = qualifiedApproval(policy, pr);
     if (!approval) {
       log(`${prKey}: gate no longer holds on fresh fetch \u2014 skipping`);
+      observe(pr, "waiting-approval");
       continue;
     }
     const dedupKey = approvalDedupKey(pr, approval);
-    if (state.approvalConsumed(dedupKey))
+    if (state.approvalConsumed(dedupKey)) {
+      observe(pr, "waiting-approval");
       continue;
+    }
     switch (pr.mergeableState) {
       case "blocked":
       case "draft":
         log(`${prKey}: ${pr.mergeableState} \u2014 not merging`);
+        observe(pr, pr.mergeableState);
         break;
       case "behind":
         await ms.updateBranch(pr.number);
         log(`${prKey}: behind base, updated branch \u2014 gate re-enters next tick`);
+        observe(pr, "behind-updated");
         break;
       case "dirty": {
         const uuid = randomUUID2();
         enqueue({ id: uuid, repo: ms.repoKey(), brief: rebaseBrief(pr) }, "chore");
         state.setRebase(prKey, uuid);
         log(`${prKey}: real conflict \u2014 wrote rebase chore ${uuid}`);
+        observe(pr, `conflict-chore:${uuid}`);
         break;
       }
       default: {
@@ -1981,6 +2080,7 @@ async function mergeLoop(ms, policy, state, log = () => {
       }
     }
   }
+  await recordMergeView(ms.forgeRepo(), observed, (n) => ms.disposition(n));
 }
 
 // apps/pick/dist/run.js
@@ -2066,14 +2166,179 @@ function mergeHaulHook(existing) {
   return { settings, changed: true };
 }
 
+// apps/cli/src/tend.ts
+import * as fs16 from "node:fs";
+import * as path12 from "node:path";
+var HEARTBEAT_STALE_MS = 9e4;
+var CLAIM_STALE_MS = 12e4;
+var DAY_MS = 24 * 36e5;
+function readJson(file) {
+  try {
+    return JSON.parse(fs16.readFileSync(file, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function doneIds(lane) {
+  try {
+    return fs16.readdirSync(laneDirs(lane).done).filter((f) => !f.startsWith("."));
+  } catch {
+    return [];
+  }
+}
+function describeDispatch(id, lane, bucket) {
+  const log = readStatusLog(id, lane);
+  const last = log.at(-1);
+  const state = bucket === "queued" ? "queued" : reconcile({ log, lastEventAt: lastEventAt(id, lane) });
+  const evidence = readEvidence(id, lane);
+  return { id, lane, bucket, state, note: last?.note, at: last?.at, prUrl: evidence.prUrl };
+}
+function followUps(uuid) {
+  const out = [];
+  const d = laneDirs("work");
+  const scan = (id, bucket, file) => {
+    const desc = readJson(file);
+    if (desc?.followUp === uuid) out.push({ id, bucket });
+  };
+  for (const id of pendingIds("work")) scan(id, "queued", path12.join(d.queue, `${id}.json`));
+  for (const id of activeIds("work")) scan(id, "active", path12.join(d.active, id, "descriptor.json"));
+  for (const id of doneIds("work")) scan(id, "done", path12.join(d.done, id, "descriptor.json"));
+  return out;
+}
+function bucketOf(uuid) {
+  const d = laneDirs("work");
+  if (fs16.existsSync(path12.join(d.active, uuid))) return "active";
+  if (fs16.existsSync(path12.join(d.done, uuid))) return "done";
+  if (fs16.existsSync(path12.join(d.queue, `${uuid}.json`))) return "queued";
+  return void 0;
+}
+function buildTendReport(now = Date.now()) {
+  const cfg = loadConfig();
+  const heartbeat = readJson(executorPath())?.heartbeat;
+  const daemonUp = heartbeat !== void 0 && now - Date.parse(heartbeat) < HEARTBEAT_STALE_MS;
+  const queued = pendingIds("work");
+  const active = activeIds("work");
+  const choresActive = activeIds("chore").length + pendingIds("chore").length;
+  let done24h = 0;
+  let failed24h = 0;
+  for (const lane of ["work", "chore"]) {
+    for (const id of doneIds(lane)) {
+      const last = readStatusLog(id, lane).at(-1);
+      if (!last || now - Date.parse(last.at) > DAY_MS) continue;
+      if (last.verb === "failed") failed24h += 1;
+      else if (last.verb === "done") done24h += 1;
+    }
+  }
+  const remindMs = (cfg.remindSecs ?? 900) * 1e3;
+  const attention = attentionNow(false, remindMs, now).map((ev) => ({
+    id: ev.id,
+    lane: ev.lane,
+    verb: ev.entry.verb,
+    ageSecs: Math.max(0, Math.round((now - Date.parse(ev.entry.at)) / 1e3)),
+    note: ev.entry.note
+  }));
+  const oldestQueuedAge = queued.reduce((max, id) => {
+    const st = fs16.statSync(path12.join(laneDirs("work").queue, `${id}.json`), { throwIfNoEntry: false });
+    return st ? Math.max(max, now - st.mtimeMs) : max;
+  }, 0);
+  const stalled = daemonUp && queued.length > 0 && active.length < cfg.limits.maxConcurrent && oldestQueuedAge > CLAIM_STALE_MS;
+  const merge = readMergeView();
+  const gateFor = (uuid, prUrl) => {
+    const open = merge?.open.find((p) => p.uuid === uuid || prUrl !== void 0 && p.url === prUrl);
+    if (open) return open.gate;
+    const recent = merge?.recent.find((r) => prUrl !== void 0 && r.url === prUrl);
+    return recent?.disposition;
+  };
+  const storied = /* @__PURE__ */ new Set();
+  const stories = [];
+  for (const [key, entry] of Object.entries(readPickupMap())) {
+    const bucket = bucketOf(entry.uuid);
+    if (!bucket) continue;
+    const chain = [describeDispatch(entry.uuid, "work", bucket)];
+    for (const f of followUps(entry.uuid)) chain.push(describeDispatch(f.id, "work", f.bucket));
+    for (const d of chain) storied.add(d.id);
+    const fresh = chain.some((d) => d.bucket !== "done" || d.at !== void 0 && now - Date.parse(d.at) < DAY_MS);
+    if (!fresh) continue;
+    const prUrl = chain.map((d) => d.prUrl).find((u) => u !== void 0);
+    stories.push({ key, dispatches: chain, prUrl, gate: gateFor(entry.uuid, prUrl) });
+  }
+  for (const id of [...active, ...queued]) {
+    if (storied.has(id)) continue;
+    const d = describeDispatch(id, "work", bucketOf(id) ?? "active");
+    stories.push({ key: "(direct)", dispatches: [d], prUrl: d.prUrl, gate: gateFor(id, d.prUrl) });
+  }
+  const verdict = !daemonUp ? "daemon-down" : stalled ? "stalled" : attention.length > 0 ? "needs-attention" : active.length + queued.length > 0 ? "working" : "idle";
+  return {
+    verdict,
+    daemon: { up: daemonUp, lastHeartbeat: heartbeat },
+    counts: { queued: queued.length, active: active.length, choresActive, done24h, failed24h },
+    attention,
+    stories,
+    merge
+  };
+}
+function renderTend(r) {
+  const lines = [];
+  lines.push(
+    toonKV({
+      verdict: r.verdict,
+      daemon: r.daemon.up ? "up" : `down (last heartbeat ${r.daemon.lastHeartbeat ?? "never"})`,
+      queued: r.counts.queued,
+      active: r.counts.active,
+      chores: r.counts.choresActive,
+      done24h: r.counts.done24h,
+      failed24h: r.counts.failed24h
+    })
+  );
+  if (r.attention.length > 0) {
+    lines.push("");
+    lines.push(
+      toonTable(
+        "attention",
+        r.attention.map((a) => ({ id: a.id, verb: a.verb, waitingMins: Math.round(a.ageSecs / 60), note: a.note ?? "" })),
+        ["id", "verb", "waitingMins", "note"]
+      )
+    );
+  }
+  if (r.stories.length > 0) {
+    lines.push("");
+    lines.push(
+      toonTable(
+        "work",
+        r.stories.map((s) => ({
+          key: s.key,
+          dispatches: s.dispatches.map((d) => `${d.id.slice(0, 8)}:${d.state}`).join(" \u2192 "),
+          pr: s.prUrl ?? "",
+          gate: s.gate ?? ""
+        })),
+        ["key", "dispatches", "pr", "gate"]
+      )
+    );
+  }
+  if (r.merge && (r.merge.open.length > 0 || r.merge.recent.length > 0)) {
+    lines.push("");
+    lines.push(
+      toonTable(
+        `prs (${r.merge.repo}, observed ${r.merge.updatedAt})`,
+        [
+          ...r.merge.open.map((p) => ({ pr: `#${p.number}`, state: p.mergeableState, gate: p.gate, url: p.url })),
+          ...r.merge.recent.map((p) => ({ pr: `#${p.number}`, state: p.disposition, gate: "", url: p.url }))
+        ],
+        ["pr", "state", "gate", "url"]
+      )
+    );
+  }
+  return lines.join("\n");
+}
+
 // apps/cli/src/cull.ts
-import * as fs15 from "node:fs";
-import * as path11 from "node:path";
+import * as fs17 from "node:fs";
+import * as path13 from "node:path";
 import { execFileSync as execFileSync2 } from "node:child_process";
 var DAY = 864e5;
 function idsIn(dir) {
   try {
-    return new Set(fs15.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => f.replace(/\.json$/, "")));
+    return new Set(fs17.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => f.replace(/\.json$/, "")));
   } catch {
     return /* @__PURE__ */ new Set();
   }
@@ -2088,39 +2353,39 @@ function planCull(olderThanDays, now = Date.now()) {
     for (const id of idsIn(d.queue)) live.add(id);
     for (const id of idsIn(d.active)) live.add(id);
     for (const id of idsIn(d.done)) {
-      const p = path11.join(d.done, id);
-      const m = fs15.statSync(p).mtimeMs;
+      const p = path13.join(d.done, id);
+      const m = fs17.statSync(p).mtimeMs;
       doneMtimes.set(id, m);
       if (m < cutoff) items.push({ kind: "done", id, target: p, ageDays: Math.floor((now - m) / DAY) });
     }
   }
-  const wtRoot = path11.join(lobstahHome(), "worktrees");
+  const wtRoot = path13.join(lobstahHome(), "worktrees");
   for (const id of idsIn(wtRoot)) {
     if (live.has(id)) continue;
     const doneAt = doneMtimes.get(id);
     if (doneAt !== void 0 && doneAt >= cutoff) continue;
-    const p = path11.join(wtRoot, id);
-    items.push({ kind: "worktree", id, target: p, ageDays: Math.floor((now - fs15.statSync(p).mtimeMs) / DAY) });
+    const p = path13.join(wtRoot, id);
+    items.push({ kind: "worktree", id, target: p, ageDays: Math.floor((now - fs17.statSync(p).mtimeMs) / DAY) });
   }
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
     const seen = /* @__PURE__ */ new Set();
-    for (const f of fs15.readdirSync(d.state)) {
+    for (const f of fs17.readdirSync(d.state)) {
       const id = f.replace(/\.(status|events|evidence|attn|notified|runner\.log)$/, "");
       if (id === f || seen.has(id) || live.has(id) || doneMtimes.has(id)) continue;
-      const m = fs15.statSync(path11.join(d.state, f)).mtimeMs;
+      const m = fs17.statSync(path13.join(d.state, f)).mtimeMs;
       if (m >= cutoff) continue;
       seen.add(id);
-      items.push({ kind: "state", id, target: path11.join(d.state, `${id}.*`), ageDays: Math.floor((now - m) / DAY) });
+      items.push({ kind: "state", id, target: path13.join(d.state, `${id}.*`), ageDays: Math.floor((now - m) / DAY) });
     }
   }
   return items;
 }
 function removeWorktree(id, dir) {
   for (const lane of ["work", "chore"]) {
-    const descFile = path11.join(laneDirs(lane).done, id, "descriptor.json");
+    const descFile = path13.join(laneDirs(lane).done, id, "descriptor.json");
     try {
-      const desc = JSON.parse(fs15.readFileSync(descFile, "utf8"));
+      const desc = JSON.parse(fs17.readFileSync(descFile, "utf8"));
       const repo = loadConfig().repos[desc.repo];
       if (repo) {
         execFileSync2("git", ["worktree", "remove", "--force", dir], { cwd: repo.path, stdio: "ignore" });
@@ -2129,15 +2394,15 @@ function removeWorktree(id, dir) {
     } catch {
     }
   }
-  fs15.rmSync(dir, { recursive: true, force: true });
+  fs17.rmSync(dir, { recursive: true, force: true });
 }
 function applyCull(items) {
   for (const item of items.filter((i) => i.kind === "worktree")) removeWorktree(item.id, item.target);
-  for (const item of items.filter((i) => i.kind === "done")) fs15.rmSync(item.target, { recursive: true, force: true });
+  for (const item of items.filter((i) => i.kind === "done")) fs17.rmSync(item.target, { recursive: true, force: true });
   for (const item of items.filter((i) => i.kind === "state")) {
-    const dir = path11.dirname(item.target);
-    for (const f of fs15.readdirSync(dir)) {
-      if (f.startsWith(`${item.id}.`)) fs15.rmSync(path11.join(dir, f), { force: true });
+    const dir = path13.dirname(item.target);
+    for (const f of fs17.readdirSync(dir)) {
+      if (f.startsWith(`${item.id}.`)) fs17.rmSync(path13.join(dir, f), { force: true });
     }
   }
 }
@@ -2160,6 +2425,9 @@ your working set:
   lobstah catch <id>                            land the catch (evidence)
   lobstah cancel <id>                           cut one away
   lobstah cull [--apply]                        sweep aged catch and lost gear
+  lobstah man tend [--json]                     tend the string: fleet verdict,
+                                                unanswered questions, each work
+                                                item's chain + PR + merge gate
 
 getting woken instead of asking:
   lobstah man wait          block until a dispatch needs attention (arm it as a
@@ -2179,7 +2447,7 @@ paste into your liaison instructions:
 full pattern and trade-offs: docs/lobsterman.md \xB7 config: docs/configuration.md`;
 
 // apps/cli/src/main.ts
-var HELP = `lobstah \u2014 supervisor for local coding agents
+var HELP = `lobstah \u2014 supervision framework for coding agents
 
 work (humans and agents):
   dispatch --repo <key> (--brief <file> | --brief-text <text>)   (alias: set --bait)
@@ -2213,6 +2481,11 @@ host processes (run under launchd/systemd/pm2):
                                   assigned work, report back, reconcile, merge
 
 lobsterman (orchestrator sessions \u2014 bare \`lobstah man\` prints the manual):
+  man tend [--json]               tend the whole string: fleet verdict (daemon
+                                  up, stalled vs idle), unanswered questions
+                                  with ages, each work item's dispatch chain,
+                                  PR, and merge-gate status from pick's last
+                                  observation. Pure disk read \u2014 no forge calls.
   man wait [--timeout <secs>] [--peek]
                                   block until a dispatch needs attention, then
                                   print the event and what to do next; exit 2
@@ -2245,7 +2518,7 @@ function arg(args, flag) {
 function findLane(id) {
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
-    if (fs16.existsSync(path12.join(d.active, id)) || fs16.existsSync(path12.join(d.queue, `${id}.json`)) || fs16.existsSync(path12.join(d.done, id)) || fs16.existsSync(path12.join(d.state, `${id}.status`))) {
+    if (fs18.existsSync(path14.join(d.active, id)) || fs18.existsSync(path14.join(d.queue, `${id}.json`)) || fs18.existsSync(path14.join(d.done, id)) || fs18.existsSync(path14.join(d.state, `${id}.status`))) {
       return lane;
     }
   }
@@ -2253,7 +2526,7 @@ function findLane(id) {
 }
 function rowsFor(lane, bucket) {
   const dir = laneDirs(lane)[bucket];
-  const entries = fs16.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => ({ f, m: fs16.statSync(path12.join(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
+  const entries = fs18.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => ({ f, m: fs18.statSync(path14.join(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
   const sliced = bucket === "done" ? entries.slice(0, 10) : entries;
   return sliced.map(({ f, m }) => {
     const id = f.replace(/\.json$/, "");
@@ -2281,7 +2554,7 @@ async function mainCli() {
       const d = {
         id: arg(args, "--id") ?? randomUUID3(),
         repo,
-        brief: briefText ?? fs16.readFileSync(briefFile, "utf8"),
+        brief: briefText ?? fs18.readFileSync(briefFile, "utf8"),
         harness: arg(args, "--harness"),
         model: arg(args, "--model"),
         effort: arg(args, "--effort"),
@@ -2318,17 +2591,17 @@ async function mainCli() {
       if (!id) throw new Error("logs requires a dispatch id");
       const lane = findLane(id);
       const file = eventsPath(id, lane);
-      if (fs16.existsSync(file)) process.stdout.write(fs16.readFileSync(file, "utf8"));
+      if (fs18.existsSync(file)) process.stdout.write(fs18.readFileSync(file, "utf8"));
       if (args.includes("--follow")) {
-        let size = fs16.existsSync(file) ? fs16.statSync(file).size : 0;
+        let size = fs18.existsSync(file) ? fs18.statSync(file).size : 0;
         setInterval(() => {
-          if (!fs16.existsSync(file)) return;
-          const now = fs16.statSync(file).size;
+          if (!fs18.existsSync(file)) return;
+          const now = fs18.statSync(file).size;
           if (now > size) {
-            const fd = fs16.openSync(file, "r");
+            const fd = fs18.openSync(file, "r");
             const buf = Buffer.alloc(now - size);
-            fs16.readSync(fd, buf, 0, buf.length, size);
-            fs16.closeSync(fd);
+            fs18.readSync(fd, buf, 0, buf.length, size);
+            fs18.closeSync(fd);
             process.stdout.write(buf.toString("utf8"));
             size = now;
           }
@@ -2384,16 +2657,16 @@ async function mainCli() {
         );
       }
       const dirs = laneDirs(lane);
-      const descriptorFile = ["active", "done"].map((b) => path12.join(dirs[b], id, "descriptor.json")).find((f) => fs16.existsSync(f));
-      const harness = descriptorFile ? JSON.parse(fs16.readFileSync(descriptorFile, "utf8")).harness ?? "claude" : "claude";
+      const descriptorFile = ["active", "done"].map((b) => path14.join(dirs[b], id, "descriptor.json")).find((f) => fs18.existsSync(f));
+      const harness = descriptorFile ? JSON.parse(fs18.readFileSync(descriptorFile, "utf8")).harness ?? "claude" : "claude";
       let sessionId;
       try {
-        sessionId = JSON.parse(fs16.readFileSync(path12.join(dirs.state, `${id}.evidence`), "utf8")).sessionId;
+        sessionId = JSON.parse(fs18.readFileSync(path14.join(dirs.state, `${id}.evidence`), "utf8")).sessionId;
       } catch {
       }
       if (!sessionId) throw new Error(`${id} has no recorded harness session to attach to`);
-      const worktree = path12.join(lobstahHome(), "worktrees", id);
-      const cwd = fs16.existsSync(worktree) ? worktree : process.cwd();
+      const worktree = path14.join(lobstahHome(), "worktrees", id);
+      const cwd = fs18.existsSync(worktree) ? worktree : process.cwd();
       const invocation = harness === "codex" ? { file: "codex", argv: ["resume", sessionId] } : { file: "claude", argv: ["--resume", sessionId] };
       if (args.includes("--print")) {
         console.log(toonKV({ id, harness, sessionId, cwd, command: `${invocation.file} ${invocation.argv.join(" ")}` }));
@@ -2407,19 +2680,19 @@ async function mainCli() {
       const id = args[0];
       if (!id) throw new Error("swap requires a dispatch id");
       const lane = findLane(id);
-      const activeDir = path12.join(laneDirs(lane).active, id);
-      if (!fs16.existsSync(activeDir)) throw new Error(`${id} is not active \u2014 swap only applies to in-flight dispatches`);
-      const descFile = path12.join(activeDir, "descriptor.json");
-      const descriptor = JSON.parse(fs16.readFileSync(descFile, "utf8"));
+      const activeDir = path14.join(laneDirs(lane).active, id);
+      if (!fs18.existsSync(activeDir)) throw new Error(`${id} is not active \u2014 swap only applies to in-flight dispatches`);
+      const descFile = path14.join(activeDir, "descriptor.json");
+      const descriptor = JSON.parse(fs18.readFileSync(descFile, "utf8"));
       const fromHarness = descriptor.harness ?? "default";
       for (const key of ["harness", "model", "effort"]) {
         const v = arg(args, `--${key}`);
         if (v) descriptor[key] = v;
       }
-      fs16.writeFileSync(descFile, JSON.stringify(descriptor, null, 2));
-      const worktree = path12.join(lobstahHome(), "worktrees", id);
+      fs18.writeFileSync(descFile, JSON.stringify(descriptor, null, 2));
+      const worktree = path14.join(lobstahHome(), "worktrees", id);
       let progress = "No worktree progress recorded.";
-      if (fs16.existsSync(worktree)) {
+      if (fs18.existsSync(worktree)) {
         const git = (...a) => spawnSync("git", a, { cwd: worktree, encoding: "utf8" }).stdout?.trim() ?? "";
         const commits = git("log", "--oneline", "-15");
         const status = git("status", "--short");
@@ -2429,17 +2702,17 @@ ${commits || "(none)"}
 Uncommitted changes:
 ${status || "(clean)"}`;
       }
-      fs16.writeFileSync(
-        path12.join(activeDir, "handoff"),
+      fs18.writeFileSync(
+        path14.join(activeDir, "handoff"),
         `You are taking over this dispatch from a previous agent session (harness: ${fromHarness}). Its conversation is not available \u2014 the worktree state below is the ground truth. Review it, then continue the brief from where it stops.
 
 ${progress}`
       );
-      const runnerFile = path12.join(activeDir, "runner.json");
-      if (fs16.existsSync(runnerFile)) {
-        const runner = JSON.parse(fs16.readFileSync(runnerFile, "utf8"));
+      const runnerFile = path14.join(activeDir, "runner.json");
+      if (fs18.existsSync(runnerFile)) {
+        const runner = JSON.parse(fs18.readFileSync(runnerFile, "utf8"));
         if (pidAlive(runner.pid, runner.processStartTime)) killGroup(runner.pid, "SIGKILL");
-        fs16.unlinkSync(runnerFile);
+        fs18.unlinkSync(runnerFile);
       }
       appendStatus(id, lane, "working", `swapped to ${descriptor.harness ?? "default"} \u2014 awaiting respawn`);
       console.log(toonKV({ id, harness: descriptor.harness ?? "default", model: descriptor.model, swapped: true }));
@@ -2490,6 +2763,11 @@ ${progress}`
       console.log(MANUAL);
       break;
     }
+    case "man:tend": {
+      const report = buildTendReport();
+      console.log(args.includes("--json") ? JSON.stringify(report, null, 2) : renderTend(report));
+      break;
+    }
     case "cancel": {
       const id = args[0];
       if (!id) throw new Error("cancel requires a dispatch id");
@@ -2529,20 +2807,20 @@ ${progress}`
       break;
     }
     case "man:init": {
-      const file = path12.join(".claude", args.includes("--shared") ? "settings.json" : "settings.local.json");
+      const file = path14.join(".claude", args.includes("--shared") ? "settings.json" : "settings.local.json");
       let existing;
       try {
-        existing = JSON.parse(fs16.readFileSync(file, "utf8"));
+        existing = JSON.parse(fs18.readFileSync(file, "utf8"));
       } catch {
         existing = void 0;
       }
       const { settings, changed } = mergeHaulHook(existing);
       if (changed) {
-        fs16.mkdirSync(".claude", { recursive: true });
-        fs16.writeFileSync(file, `${JSON.stringify(settings, null, 2)}
+        fs18.mkdirSync(".claude", { recursive: true });
+        fs18.writeFileSync(file, `${JSON.stringify(settings, null, 2)}
 `);
       }
-      if (args.includes("--marker")) fs16.writeFileSync(".lobstah-man", "");
+      if (args.includes("--marker")) fs18.writeFileSync(".lobstah-man", "");
       console.log(
         toonKV({
           hook: "lobstah man haul",
@@ -2555,9 +2833,9 @@ ${progress}`
     }
     case "man:haul": {
       try {
-        if (process.env.LOBSTAH_MAN !== "1" && !fs16.existsSync(".lobstah-man")) break;
+        if (process.env.LOBSTAH_MAN !== "1" && !fs18.existsSync(".lobstah-man")) break;
         const anyActive = ["work", "chore"].some(
-          (l) => fs16.readdirSync(laneDirs(l).active).some((f) => !f.startsWith("."))
+          (l) => fs18.readdirSync(laneDirs(l).active).some((f) => !f.startsWith("."))
         );
         if (!anyActive) break;
         const timeoutSecs = Number(arg(args, "--timeout") ?? "14000");
@@ -2598,8 +2876,8 @@ ${progress}`
       break;
     }
     case "init": {
-      if (!fs16.existsSync(configPath())) {
-        fs16.writeFileSync(
+      if (!fs18.existsSync(configPath())) {
+        fs18.writeFileSync(
           configPath(),
           `# lobstah workspace definitions \u2014 the descriptor's repo key resolves here.
 # Top-level keys must come before any [section].
@@ -2626,7 +2904,7 @@ wallClockSecs      = 3600
       }
       console.log(
         toonKV({
-          home: path12.dirname(configPath()),
+          home: path14.dirname(configPath()),
           config: configPath(),
           reference: "docs/configuration.md",
           initialized: true

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lobstah",
-  "version": "0.1.0",
-  "description": "Harness-agnostic, token-efficient supervisor for local coding agents",
+  "version": "0.1.1",
+  "description": "Harness-agnostic, token-efficient supervision framework for coding agents",
   "license": "MIT",
   "author": "aequitas labs LLC",
   "type": "module",