lobstah 0.3.0 → 0.3.1

package/dist/main.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // apps/cli/src/main.ts
-import * as fs27 from "node:fs";
+import * as fs28 from "node:fs";
 import * as os6 from "node:os";
-import * as path21 from "node:path";
+import * as path22 from "node:path";
 import { randomUUID as randomUUID4 } from "node:crypto";
 import { spawnSync as spawnSync6 } from "node:child_process";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
@@ -1984,6 +1984,38 @@ var PickupState = class {
   }
 };
 
+// apps/pick/dist/pr-evidence.js
+import * as fs16 from "node:fs";
+import * as path11 from "node:path";
+function prUrlKey(url) {
+  return url.replace(/\/+$/, "");
+}
+function prEvidenceIndex() {
+  const byUrl = /* @__PURE__ */ new Map();
+  const stateDir = laneDirs("work").state;
+  let files;
+  try {
+    files = fs16.readdirSync(stateDir).filter((f) => f.endsWith(".evidence"));
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+  for (const f of files) {
+    const file = path11.join(stateDir, f);
+    try {
+      const prUrl = JSON.parse(fs16.readFileSync(file, "utf8")).prUrl;
+      if (!prUrl)
+        continue;
+      const key = prUrlKey(prUrl);
+      const mtime = fs16.statSync(file).mtimeMs;
+      const cur = byUrl.get(key);
+      if (!cur || mtime > cur.mtime)
+        byUrl.set(key, { uuid: f.slice(0, -".evidence".length), mtime });
+    } catch {
+    }
+  }
+  return new Map([...byUrl].map(([url, v]) => [url, v.uuid]));
+}
+
 // apps/pick/dist/sources/github.js
 var API = "https://api.github.com";
 var GithubSource = class {
@@ -2032,26 +2064,70 @@ ${issue.body ?? ""}
 When the change is complete, commit it, push the branch, and open a PR against ${this.cfg.repo} referencing #${issue.number}.`
       });
     }
+    const evidence = prEvidenceIndex();
     const pulls = await this.api("GET", `/repos/${this.cfg.repo}/pulls?state=open&per_page=50`);
     for (const pr of pulls) {
       const m = /^lobstah\/([0-9a-f-]{36})$/.exec(pr.head.ref);
-      if (!m)
+      const uuid = m?.[1] ?? evidence.get(prUrlKey(pr.html_url));
+      if (!uuid)
         continue;
-      const reviews = await this.latestReviews(pr.number);
-      const changes = reviews.find((r) => r.state === "CHANGES_REQUESTED" && r.commit_id === pr.head.sha);
-      if (!changes)
+      const feedback = await this.latestFeedback(pr.number);
+      if (!feedback)
         continue;
+      const subject = `gh:${this.cfg.repo}#pr${pr.number}`;
       items.push({
-        key: `gh:${this.cfg.repo}#pr${pr.number}@${pr.head.sha}`,
+        key: `${subject}@${feedback}`,
+        subject,
         kind: "review",
         repoKey: this.cfg.key,
         title: pr.title,
-        followUp: m[1],
-        brief: `Address the review feedback on ${pr.html_url} (branch ${pr.head.ref}). Check out that branch in this worktree, read the review comments with \`gh pr view ${pr.number} --comments\`, implement the requested changes, and push. Reply to review threads where a reply is warranted.`
+        followUp: uuid,
+        brief: `Address the review feedback on ${pr.html_url} (branch ${pr.head.ref}). Check out that branch in this worktree, read the full review discussion with \`gh pr view ${pr.number} --comments\`, implement what the feedback asks, and push. Reply to review threads where a reply is warranted. When the feedback is addressed, report status done.`
       });
     }
     return items;
   }
+  /**
+   * The newest human feedback event on a PR, as an opaque round tag —
+   * `rv<id>` for a submitted review, `rc<id>` for an inline review-thread
+   * comment, `ic<id>` for a conversation comment. Feedback means: a
+   * CHANGES_REQUESTED review on any sha (a review of a slightly stale head
+   * still asks for changes), a COMMENTED review with a body, or any comment
+   * — always by someone other than the configured identity, and never a
+   * marker comment. APPROVED reviews are the merge loop's signal, not
+   * feedback. Returns undefined when no human has spoken.
+   */
+  async latestFeedback(n) {
+    const events = [];
+    const human = (login) => login !== this.cfg.identity;
+    const reviews = await this.paged(`/repos/${this.cfg.repo}/pulls/${n}/reviews`);
+    for (const r of reviews) {
+      if (!human(r.user.login))
+        continue;
+      const actionable = r.state === "CHANGES_REQUESTED" || r.state === "COMMENTED" && (r.body ?? "").trim() !== "";
+      if (actionable)
+        events.push({ at: r.submitted_at, tag: `rv${r.id}` });
+    }
+    for (const c of await this.paged(`/repos/${this.cfg.repo}/pulls/${n}/comments`)) {
+      if (human(c.user.login))
+        events.push({ at: c.created_at, tag: `rc${c.id}` });
+    }
+    for (const c of await this.paged(`/repos/${this.cfg.repo}/issues/${n}/comments`)) {
+      if (human(c.user.login) && !MARKER.test(c.body))
+        events.push({ at: c.created_at, tag: `ic${c.id}` });
+    }
+    events.sort((a, b) => a.at === b.at ? a.tag.localeCompare(b.tag) : a.at.localeCompare(b.at));
+    return events.at(-1)?.tag;
+  }
+  async paged(url) {
+    const all = [];
+    for (let page = 1; ; page++) {
+      const batch = await this.api("GET", `${url}?per_page=100&page=${page}`);
+      all.push(...batch);
+      if (batch.length < 100)
+        return all;
+    }
+  }
   async claim(item) {
     if (item.kind === "review")
       return true;
@@ -2298,36 +2374,14 @@ When the change is complete, commit it, push the branch, and open a PR whose des
 
 // apps/pick/dist/loops/dispatch.js
 import { randomUUID } from "node:crypto";
-async function dispatchLoop(source, state, log = () => {
-}) {
-  const items = await source.poll();
-  for (const item of items) {
-    if (state.get(item.key))
-      continue;
-    if (!await source.claim(item)) {
-      log(`${item.key}: claim lost \u2014 another machine has it`);
-      continue;
-    }
-    const id = randomUUID();
-    enqueue({
-      id,
-      repo: item.repoKey,
-      brief: item.brief,
-      // A review dispatch forks the implementation session; issues start cold.
-      ...item.kind === "review" && item.followUp ? { followUp: item.followUp } : {}
-    }, "work");
-    state.set(item.key, { uuid: id, kind: item.kind, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
-    log(`${item.key}: dispatched as ${id}`);
-  }
-}
 
 // apps/pick/dist/loops/report.js
-import * as fs16 from "node:fs";
-import * as path11 from "node:path";
+import * as fs17 from "node:fs";
+import * as path12 from "node:path";
 function dispatchLane(uuid) {
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
-    if (fs16.existsSync(path11.join(d.active, uuid)) || fs16.existsSync(path11.join(d.queue, `${uuid}.json`)) || fs16.existsSync(path11.join(d.done, uuid)) || fs16.existsSync(path11.join(d.state, `${uuid}.status`))) {
+    if (fs17.existsSync(path12.join(d.active, uuid)) || fs17.existsSync(path12.join(d.queue, `${uuid}.json`)) || fs17.existsSync(path12.join(d.done, uuid)) || fs17.existsSync(path12.join(d.state, `${uuid}.status`))) {
       return lane;
     }
   }
@@ -2367,13 +2421,58 @@ async function reportLoop(source, state, log = () => {
   }
 }
 
+// apps/pick/dist/loops/dispatch.js
+function terminal(uuid) {
+  const lane = dispatchLane(uuid);
+  if (!lane)
+    return true;
+  const verb = reconcile({ log: readStatusLog(uuid, lane), lastEventAt: lastEventAt(uuid, lane) });
+  return verb === "done" || verb === "failed";
+}
+function roundPlan(item, state) {
+  const rounds = item.subject ? state.entries().filter(([k]) => k.startsWith(`${item.subject}@`)).map(([, e]) => e) : [];
+  const chain = [...rounds.map((e) => e.uuid), ...item.followUp ? [item.followUp] : []];
+  if (chain.some((uuid) => !terminal(uuid)))
+    return { hold: true };
+  const forkable = rounds.filter((e) => dispatchLane(e.uuid)).sort((a, b) => a.createdAt.localeCompare(b.createdAt)).at(-1)?.uuid;
+  const target = forkable ?? item.followUp;
+  return { hold: false, followUp: target && dispatchLane(target) ? target : void 0 };
+}
+async function dispatchLoop(source, state, log = () => {
+}) {
+  const items = await source.poll();
+  for (const item of items) {
+    if (state.get(item.key))
+      continue;
+    const plan = item.kind === "review" ? roundPlan(item, state) : { hold: false, followUp: void 0 };
+    if (plan.hold) {
+      log(`${item.key}: a prior round is still in flight \u2014 holding`);
+      continue;
+    }
+    if (!await source.claim(item)) {
+      log(`${item.key}: claim lost \u2014 another machine has it`);
+      continue;
+    }
+    const id = randomUUID();
+    enqueue({
+      id,
+      repo: item.repoKey,
+      brief: item.brief,
+      // A review dispatch forks the latest session in its chain; issues start cold.
+      ...plan.followUp ? { followUp: plan.followUp } : {}
+    }, "work");
+    state.set(item.key, { uuid: id, kind: item.kind, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
+    log(`${item.key}: dispatched as ${id}`);
+  }
+}
+
 // apps/pick/dist/loops/reconcile.js
-import * as fs17 from "node:fs";
-import * as path12 from "node:path";
+import * as fs18 from "node:fs";
+import * as path13 from "node:path";
 function dispatchActive(uuid) {
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
-    if (fs17.existsSync(path12.join(d.active, uuid)) || fs17.existsSync(path12.join(d.queue, `${uuid}.json`))) {
+    if (fs18.existsSync(path13.join(d.active, uuid)) || fs18.existsSync(path13.join(d.queue, `${uuid}.json`))) {
       return lane;
     }
   }
@@ -2413,28 +2512,28 @@ async function reconcileLoop(source, state, log = () => {
 
 // apps/pick/dist/loops/merge.js
 import { randomUUID as randomUUID2 } from "node:crypto";
-import * as fs19 from "node:fs";
-import * as path14 from "node:path";
+import * as fs20 from "node:fs";
+import * as path15 from "node:path";
 
 // apps/pick/dist/merge-view.js
-import * as fs18 from "node:fs";
-import * as path13 from "node:path";
+import * as fs19 from "node:fs";
+import * as path14 from "node:path";
 function viewPath() {
-  return path13.join(lobstahHome(), "pickup", "merge-view.json");
+  return path14.join(lobstahHome(), "pickup", "merge-view.json");
 }
 function readMergeView() {
   try {
-    return JSON.parse(fs18.readFileSync(viewPath(), "utf8"));
+    return JSON.parse(fs19.readFileSync(viewPath(), "utf8"));
   } catch {
     return void 0;
   }
 }
 function writeMergeView(view) {
   const file = viewPath();
-  fs18.mkdirSync(path13.dirname(file), { recursive: true });
+  fs19.mkdirSync(path14.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
-  fs18.writeFileSync(tmp, JSON.stringify(view, null, 2));
-  fs18.renameSync(tmp, file);
+  fs19.writeFileSync(tmp, JSON.stringify(view, null, 2));
+  fs19.renameSync(tmp, file);
 }
 var RECENT_RETENTION_MS = 48 * 36e5;
 async function recordMergeView(repo, open, disposition, now = /* @__PURE__ */ new Date()) {
@@ -2456,7 +2555,7 @@ async function recordMergeView(repo, open, disposition, now = /* @__PURE__ */ ne
 }
 function readPickupMap() {
   try {
-    const raw = JSON.parse(fs18.readFileSync(path13.join(lobstahHome(), "pickup", "state.json"), "utf8"));
+    const raw = JSON.parse(fs19.readFileSync(path14.join(lobstahHome(), "pickup", "state.json"), "utf8"));
     return raw.map ?? {};
   } catch {
     return {};
@@ -2490,7 +2589,7 @@ function rebaseBrief(pr) {
 }
 function choreVerdict(uuid) {
   const d = laneDirs("chore");
-  if (fs19.existsSync(path14.join(d.active, uuid)) || fs19.existsSync(path14.join(d.queue, `${uuid}.json`)))
+  if (fs20.existsSync(path15.join(d.active, uuid)) || fs20.existsSync(path15.join(d.queue, `${uuid}.json`)))
     return "active";
   const last = readStatusLog(uuid, "chore").at(-1)?.verb;
   return last === "done" ? "done" : "failed";
@@ -2584,8 +2683,8 @@ async function mergeLoop(ms, policy, state, log = () => {
 }
 
 // apps/pick/dist/loops/watch.js
-import * as fs20 from "node:fs";
-import * as path15 from "node:path";
+import * as fs21 from "node:fs";
+import * as path16 from "node:path";
 import { randomUUID as randomUUID3 } from "node:crypto";
 var DEFAULT_BRIEF = `You are resuming earlier work. The watched source {key} produced new events:
 
@@ -2595,7 +2694,7 @@ Read them, act on what they ask, and report the outcome.`;
 function laneOf(id) {
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
-    if (fs20.existsSync(path15.join(d.active, id)) || fs20.existsSync(path15.join(d.queue, `${id}.json`)) || fs20.existsSync(path15.join(d.done, id)) || fs20.existsSync(path15.join(d.state, `${id}.status`))) {
+    if (fs21.existsSync(path16.join(d.active, id)) || fs21.existsSync(path16.join(d.queue, `${id}.json`)) || fs21.existsSync(path16.join(d.done, id)) || fs21.existsSync(path16.join(d.state, `${id}.status`))) {
       return lane;
     }
   }
@@ -2604,13 +2703,13 @@ function laneOf(id) {
 function descriptorOf(id, lane) {
   const d = laneDirs(lane);
   for (const bucket of ["active", "done"]) {
-    const f = path15.join(d[bucket], id, "descriptor.json");
-    if (fs20.existsSync(f))
-      return JSON.parse(fs20.readFileSync(f, "utf8"));
+    const f = path16.join(d[bucket], id, "descriptor.json");
+    if (fs21.existsSync(f))
+      return JSON.parse(fs21.readFileSync(f, "utf8"));
   }
-  const q = path15.join(d.queue, `${id}.json`);
-  if (fs20.existsSync(q))
-    return JSON.parse(fs20.readFileSync(q, "utf8"));
+  const q = path16.join(d.queue, `${id}.json`);
+  if (fs21.existsSync(q))
+    return JSON.parse(fs21.readFileSync(q, "utf8"));
   return void 0;
 }
 function isTerminal(id) {
@@ -2843,21 +2942,21 @@ function mergeHaulHook(existing) {
 }
 
 // apps/cli/src/tend.ts
-import * as fs21 from "node:fs";
-import * as path16 from "node:path";
+import * as fs22 from "node:fs";
+import * as path17 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(fs21.readFileSync(file, "utf8"));
+    return JSON.parse(fs22.readFileSync(file, "utf8"));
   } catch {
     return void 0;
   }
 }
 function doneIds(lane) {
   try {
-    return fs21.readdirSync(laneDirs(lane).done).filter((f) => !f.startsWith("."));
+    return fs22.readdirSync(laneDirs(lane).done).filter((f) => !f.startsWith("."));
   } catch {
     return [];
   }
@@ -2876,16 +2975,16 @@ function followUps(uuid) {
     const desc = readJson(file);
     if (desc?.followUp === uuid) out.push({ id, bucket });
   };
-  for (const id of pendingIds("work")) scan(id, "queued", path16.join(d.queue, `${id}.json`));
-  for (const id of activeIds("work")) scan(id, "active", path16.join(d.active, id, "descriptor.json"));
-  for (const id of doneIds("work")) scan(id, "done", path16.join(d.done, id, "descriptor.json"));
+  for (const id of pendingIds("work")) scan(id, "queued", path17.join(d.queue, `${id}.json`));
+  for (const id of activeIds("work")) scan(id, "active", path17.join(d.active, id, "descriptor.json"));
+  for (const id of doneIds("work")) scan(id, "done", path17.join(d.done, id, "descriptor.json"));
   return out;
 }
 function bucketOf(uuid) {
   const d = laneDirs("work");
-  if (fs21.existsSync(path16.join(d.active, uuid))) return "active";
-  if (fs21.existsSync(path16.join(d.done, uuid))) return "done";
-  if (fs21.existsSync(path16.join(d.queue, `${uuid}.json`))) return "queued";
+  if (fs22.existsSync(path17.join(d.active, uuid))) return "active";
+  if (fs22.existsSync(path17.join(d.done, uuid))) return "done";
+  if (fs22.existsSync(path17.join(d.queue, `${uuid}.json`))) return "queued";
   return void 0;
 }
 function buildTendReport(now = Date.now()) {
@@ -2945,7 +3044,7 @@ function buildTendReport(now = Date.now()) {
     }
   }
   const oldestQueuedAge = queued.reduce((max, id) => {
-    const st = fs21.statSync(path16.join(laneDirs("work").queue, `${id}.json`), { throwIfNoEntry: false });
+    const st = fs22.statSync(path17.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;
@@ -3082,13 +3181,13 @@ function renderTend(r) {
 }
 
 // apps/cli/src/cull.ts
-import * as fs22 from "node:fs";
-import * as path17 from "node:path";
+import * as fs23 from "node:fs";
+import * as path18 from "node:path";
 import { execFileSync as execFileSync2 } from "node:child_process";
 var DAY = 864e5;
 function idsIn(dir) {
   try {
-    return new Set(fs22.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => f.replace(/\.json$/, "")));
+    return new Set(fs23.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => f.replace(/\.json$/, "")));
   } catch {
     return /* @__PURE__ */ new Set();
   }
@@ -3103,39 +3202,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 = path17.join(d.done, id);
-      const m = fs22.statSync(p).mtimeMs;
+      const p = path18.join(d.done, id);
+      const m = fs23.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 = path17.join(lobstahHome(), "worktrees");
+  const wtRoot = path18.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 = path17.join(wtRoot, id);
-    items.push({ kind: "worktree", id, target: p, ageDays: Math.floor((now - fs22.statSync(p).mtimeMs) / DAY) });
+    const p = path18.join(wtRoot, id);
+    items.push({ kind: "worktree", id, target: p, ageDays: Math.floor((now - fs23.statSync(p).mtimeMs) / DAY) });
   }
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
     const seen = /* @__PURE__ */ new Set();
-    for (const f of fs22.readdirSync(d.state)) {
+    for (const f of fs23.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 = fs22.statSync(path17.join(d.state, f)).mtimeMs;
+      const m = fs23.statSync(path18.join(d.state, f)).mtimeMs;
       if (m >= cutoff) continue;
       seen.add(id);
-      items.push({ kind: "state", id, target: path17.join(d.state, `${id}.*`), ageDays: Math.floor((now - m) / DAY) });
+      items.push({ kind: "state", id, target: path18.join(d.state, `${id}.*`), ageDays: Math.floor((now - m) / DAY) });
     }
   }
   return items;
 }
 function removeWorktree(id, dir) {
   for (const lane of ["work", "chore"]) {
-    const descFile = path17.join(laneDirs(lane).done, id, "descriptor.json");
+    const descFile = path18.join(laneDirs(lane).done, id, "descriptor.json");
     try {
-      const desc = JSON.parse(fs22.readFileSync(descFile, "utf8"));
+      const desc = JSON.parse(fs23.readFileSync(descFile, "utf8"));
       const repo = loadConfig().repos[desc.repo];
       if (repo) {
         execFileSync2("git", ["worktree", "remove", "--force", dir], { cwd: repo.path, stdio: "ignore" });
@@ -3144,15 +3243,15 @@ function removeWorktree(id, dir) {
     } catch {
     }
   }
-  fs22.rmSync(dir, { recursive: true, force: true });
+  fs23.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")) fs22.rmSync(item.target, { recursive: true, force: true });
+  for (const item of items.filter((i) => i.kind === "done")) fs23.rmSync(item.target, { recursive: true, force: true });
   for (const item of items.filter((i) => i.kind === "state")) {
-    const dir = path17.dirname(item.target);
-    for (const f of fs22.readdirSync(dir)) {
-      if (f.startsWith(`${item.id}.`)) fs22.rmSync(path17.join(dir, f), { force: true });
+    const dir = path18.dirname(item.target);
+    for (const f of fs23.readdirSync(dir)) {
+      if (f.startsWith(`${item.id}.`)) fs23.rmSync(path18.join(dir, f), { force: true });
     }
   }
 }
@@ -3206,7 +3305,7 @@ paste into your liaison instructions:
 full pattern and trade-offs: docs/lobsterman.md \xB7 config: docs/configuration.md`;
 
 // apps/cli/src/doctor.ts
-import * as fs23 from "node:fs";
+import * as fs24 from "node:fs";
 import { spawnSync as spawnSync2 } from "node:child_process";
 var HEARTBEAT_STALE_MS2 = 9e4;
 function git(repoPath, ...args) {
@@ -3229,13 +3328,13 @@ function runDoctor(now = Date.now()) {
     codexPath ? "on PATH" : codexSdk ? "vendored SDK (attach uses it too)" : "neither codex nor the SDK \u2014 codex dispatches will fail"
   );
   const cfgFile = configPath();
-  if (!fs23.existsSync(cfgFile)) {
+  if (!fs24.existsSync(cfgFile)) {
     push("config", "fail", `${cfgFile} missing \u2014 run \`lobstah init\``);
     return rows;
   }
   let parsed;
   try {
-    parsed = parse(fs23.readFileSync(cfgFile, "utf8"));
+    parsed = parse(fs24.readFileSync(cfgFile, "utf8"));
     push("config", "ok", cfgFile);
   } catch (err) {
     push("config", "fail", `${cfgFile}: ${err instanceof Error ? err.message : String(err)}`);
@@ -3246,7 +3345,7 @@ function runDoctor(now = Date.now()) {
   if (repoKeys.length === 0) push("repos", "warn", "none configured \u2014 add one with `lobstah repos add <path>`");
   for (const [key, repo] of Object.entries(cfg.repos)) {
     const label = `repo ${key}`;
-    if (!fs23.existsSync(repo.path)) {
+    if (!fs24.existsSync(repo.path)) {
       push(label, "fail", `path ${repo.path} does not exist`);
       continue;
     }
@@ -3274,11 +3373,11 @@ function runDoctor(now = Date.now()) {
     }
   }
   const hb = executorPath();
-  if (!fs23.existsSync(hb)) {
+  if (!fs24.existsSync(hb)) {
     push("daemon", "warn", "no heartbeat \u2014 daemon not running (`lobstah daemon install`)");
   } else {
     try {
-      const payload = JSON.parse(fs23.readFileSync(hb, "utf8"));
+      const payload = JSON.parse(fs24.readFileSync(hb, "utf8"));
       const age = now - new Date(payload.heartbeat ?? 0).getTime();
       push(
         "daemon",
@@ -3294,9 +3393,9 @@ function runDoctor(now = Date.now()) {
 }
 
 // apps/cli/src/service.ts
-import * as fs24 from "node:fs";
+import * as fs25 from "node:fs";
 import * as os5 from "node:os";
-import * as path18 from "node:path";
+import * as path19 from "node:path";
 import { spawnSync as spawnSync3 } from "node:child_process";
 function xml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -3320,8 +3419,8 @@ function renderLaunchdPlist(spec) {
   </dict>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
-  <key>StandardOutPath</key><string>${xml(path18.posix.join(spec.logDir, `${spec.kind}.log`))}</string>
-  <key>StandardErrorPath</key><string>${xml(path18.posix.join(spec.logDir, `${spec.kind}.err`))}</string>
+  <key>StandardOutPath</key><string>${xml(path19.posix.join(spec.logDir, `${spec.kind}.log`))}</string>
+  <key>StandardErrorPath</key><string>${xml(path19.posix.join(spec.logDir, `${spec.kind}.err`))}</string>
 </dict>
 </plist>
 `;
@@ -3336,8 +3435,8 @@ Restart=always
 RestartSec=5
 Environment=PATH=${spec.pathEnv}
 Environment=LOBSTAH_HOME=${spec.home}
-StandardOutput=append:${path18.posix.join(spec.logDir, `${spec.kind}.log`)}
-StandardError=append:${path18.posix.join(spec.logDir, `${spec.kind}.err`)}
+StandardOutput=append:${path19.posix.join(spec.logDir, `${spec.kind}.log`)}
+StandardError=append:${path19.posix.join(spec.logDir, `${spec.kind}.err`)}
 
 [Install]
 WantedBy=default.target
@@ -3345,8 +3444,8 @@ WantedBy=default.target
 }
 function servicePathEnv(nodePath, home = os5.homedir()) {
   const dirs = [
-    path18.posix.dirname(nodePath),
-    path18.posix.join(home, ".local", "bin"),
+    path19.posix.dirname(nodePath),
+    path19.posix.join(home, ".local", "bin"),
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -3355,7 +3454,7 @@ function servicePathEnv(nodePath, home = os5.homedir()) {
   return [...new Set(dirs)].join(":");
 }
 function serviceFile(kind) {
-  return process.platform === "darwin" ? path18.join(os5.homedir(), "Library", "LaunchAgents", `lobstah.${kind}.plist`) : path18.join(os5.homedir(), ".config", "systemd", "user", `lobstah-${kind}.service`);
+  return process.platform === "darwin" ? path19.join(os5.homedir(), "Library", "LaunchAgents", `lobstah.${kind}.plist`) : path19.join(os5.homedir(), ".config", "systemd", "user", `lobstah-${kind}.service`);
 }
 function run(cmd, args) {
   const res = spawnSync3(cmd, args, { encoding: "utf8" });
@@ -3365,28 +3464,28 @@ function installService(kind) {
   if (process.platform === "win32") {
     throw new Error(`no service manager support on Windows \u2014 run \`lobstah ${kind}\` under your process manager of choice`);
   }
-  const entry = fs24.realpathSync(process.argv[1]);
+  const entry = fs25.realpathSync(process.argv[1]);
   const spec = {
     kind,
     nodePath: process.execPath,
     entry,
     pathEnv: servicePathEnv(process.execPath),
     home: lobstahHome(),
-    logDir: path18.join(lobstahHome(), "logs")
+    logDir: path19.join(lobstahHome(), "logs")
   };
   if (!onPath("git", spec.pathEnv)) {
     throw new Error(`git is not reachable on the service PATH (${spec.pathEnv}) \u2014 the daemon cannot allocate worktrees`);
   }
-  fs24.mkdirSync(spec.logDir, { recursive: true });
+  fs25.mkdirSync(spec.logDir, { recursive: true });
   const file = serviceFile(kind);
-  fs24.mkdirSync(path18.dirname(file), { recursive: true });
+  fs25.mkdirSync(path19.dirname(file), { recursive: true });
   if (process.platform === "darwin") {
-    if (fs24.existsSync(file)) run("launchctl", ["unload", file]);
-    fs24.writeFileSync(file, renderLaunchdPlist(spec));
+    if (fs25.existsSync(file)) run("launchctl", ["unload", file]);
+    fs25.writeFileSync(file, renderLaunchdPlist(spec));
     const load = run("launchctl", ["load", file]);
     return { file, loaded: load.ok, detail: load.ok ? `label lobstah.${kind}` : load.out };
   }
-  fs24.writeFileSync(file, renderSystemdUnit(spec));
+  fs25.writeFileSync(file, renderSystemdUnit(spec));
   run("systemctl", ["--user", "daemon-reload"]);
   const enable = run("systemctl", ["--user", "enable", "--now", `lobstah-${kind}.service`]);
   return { file, loaded: enable.ok, detail: enable.ok ? `unit lobstah-${kind}.service` : enable.out };
@@ -3394,19 +3493,19 @@ function installService(kind) {
 function uninstallService(kind) {
   const file = serviceFile(kind);
   if (process.platform === "darwin") {
-    if (fs24.existsSync(file)) run("launchctl", ["unload", file]);
+    if (fs25.existsSync(file)) run("launchctl", ["unload", file]);
   } else {
     run("systemctl", ["--user", "disable", "--now", `lobstah-${kind}.service`]);
   }
-  const removed = fs24.existsSync(file);
-  if (removed) fs24.unlinkSync(file);
+  const removed = fs25.existsSync(file);
+  if (removed) fs25.unlinkSync(file);
   if (process.platform !== "darwin") run("systemctl", ["--user", "daemon-reload"]);
   return { file, removed };
 }
 
 // apps/cli/src/repos.ts
-import * as fs25 from "node:fs";
-import * as path19 from "node:path";
+import * as fs26 from "node:fs";
+import * as path20 from "node:path";
 import { spawnSync as spawnSync4 } from "node:child_process";
 function git2(dir, ...args) {
   const res = spawnSync4("git", ["-C", dir, ...args], { encoding: "utf8" });
@@ -3422,41 +3521,41 @@ var LOCKFILE_SETUP = [
   ["poetry.lock", ["poetry install"]]
 ];
 function detectRepo(dir) {
-  const abs = path19.resolve(dir);
+  const abs = path20.resolve(dir);
   if (git2(abs, "rev-parse", "--is-inside-work-tree") !== "true") return void 0;
   const top = git2(abs, "rev-parse", "--show-toplevel");
   const canon2 = (p) => {
-    const real = path19.resolve(fs25.realpathSync.native(p));
+    const real = path20.resolve(fs26.realpathSync.native(p));
     return process.platform === "win32" ? real.toLowerCase() : real;
   };
   if (!top || canon2(top) !== canon2(abs)) return void 0;
   const origin = git2(abs, "remote", "get-url", "origin");
   const headRef = git2(abs, "symbolic-ref", "--short", "refs/remotes/origin/HEAD");
   const trunk = headRef?.replace(/^origin\//, "") ?? git2(abs, "branch", "--show-current") ?? "main";
-  const setup = LOCKFILE_SETUP.find(([f]) => fs25.existsSync(path19.join(abs, f)))?.[1];
-  return { key: path19.basename(abs), path: abs, trunk, origin, setup };
+  const setup = LOCKFILE_SETUP.find(([f]) => fs26.existsSync(path20.join(abs, f)))?.[1];
+  return { key: path20.basename(abs), path: abs, trunk, origin, setup };
 }
 function scanForRepos(roots) {
   const found = [];
   for (const root of roots) {
-    const abs = path19.resolve(root);
-    if (!fs25.existsSync(abs)) continue;
+    const abs = path20.resolve(root);
+    if (!fs26.existsSync(abs)) continue;
     const self = detectRepo(abs);
     if (self) {
       found.push(self);
       continue;
     }
-    for (const entry of fs25.readdirSync(abs, { withFileTypes: true })) {
+    for (const entry of fs26.readdirSync(abs, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const child = detectRepo(path19.join(abs, entry.name));
+      const child = detectRepo(path20.join(abs, entry.name));
       if (child) found.push(child);
     }
   }
   return found;
 }
 function configuredRepoKeys(file = configPath()) {
-  if (!fs25.existsSync(file)) return /* @__PURE__ */ new Set();
-  const raw = parse(fs25.readFileSync(file, "utf8"));
+  if (!fs26.existsSync(file)) return /* @__PURE__ */ new Set();
+  const raw = parse(fs26.readFileSync(file, "utf8"));
   return new Set(Object.keys(raw.repos ?? {}));
 }
 function appendRepoBlock(repo, opts = {}, file = configPath()) {
@@ -3464,7 +3563,7 @@ function appendRepoBlock(repo, opts = {}, file = configPath()) {
   if (repo.origin) lines.push(`origin = ${JSON.stringify(repo.origin)}`);
   if (repo.setup) lines.push(`setup  = [${repo.setup.map((s) => JSON.stringify(s)).join(", ")}]`);
   if (opts.pickup) lines.push(`pickup = true`);
-  fs25.appendFileSync(file, `${lines.join("\n")}
+  fs26.appendFileSync(file, `${lines.join("\n")}
 `);
 }
 
@@ -3477,8 +3576,8 @@ function parseReportArgs(rest) {
 }
 
 // apps/cli/src/soak-site.ts
-import * as fs26 from "node:fs";
-import * as path20 from "node:path";
+import * as fs27 from "node:fs";
+import * as path21 from "node:path";
 import { spawnSync as spawnSync5 } from "node:child_process";
 function git3(dir, ...args) {
   const res = spawnSync5("git", ["-C", dir, ...args], { encoding: "utf8" });
@@ -3486,10 +3585,10 @@ function git3(dir, ...args) {
 }
 function canon(p) {
   try {
-    const real = path20.resolve(fs26.realpathSync.native(p));
+    const real = path21.resolve(fs27.realpathSync.native(p));
     return process.platform === "win32" ? real.toLowerCase() : real;
   } catch {
-    return path20.resolve(p);
+    return path21.resolve(p);
   }
 }
 function inspectSoakSite(cwd, repos) {
@@ -3498,16 +3597,16 @@ function inspectSoakSite(cwd, repos) {
   const gitDir = git3(cwd, "rev-parse", "--git-dir");
   const commonDir = git3(cwd, "rev-parse", "--git-common-dir");
   if (!gitDir || !commonDir) return void 0;
-  const abs = (p) => path20.isAbsolute(p) ? p : path20.join(cwd, p);
+  const abs = (p) => path21.isAbsolute(p) ? p : path21.join(cwd, p);
   const primary = canon(abs(gitDir)) === canon(abs(commonDir));
-  const primaryRoot = canon(path20.dirname(abs(commonDir)));
+  const primaryRoot = canon(path21.dirname(abs(commonDir)));
   const repoKey = Object.entries(repos).find(([, r]) => canon(r.path) === primaryRoot)?.[0];
   return { worktree: canon(top), primary, repoKey };
 }
 function readHookStdin() {
   if (process.stdin.isTTY) return void 0;
   try {
-    const raw = fs26.readFileSync(0, "utf8");
+    const raw = fs27.readFileSync(0, "utf8");
     if (!raw.trim()) return void 0;
     const parsed = JSON.parse(raw);
     return typeof parsed === "object" && parsed !== null ? parsed : void 0;
@@ -3841,7 +3940,7 @@ function emitWatchAttention(attns) {
 function findLane(id) {
   for (const lane of ["work", "chore"]) {
     const d = laneDirs(lane);
-    if (fs27.existsSync(path21.join(d.active, id)) || fs27.existsSync(path21.join(d.queue, `${id}.json`)) || fs27.existsSync(path21.join(d.done, id)) || fs27.existsSync(path21.join(d.state, `${id}.status`))) {
+    if (fs28.existsSync(path22.join(d.active, id)) || fs28.existsSync(path22.join(d.queue, `${id}.json`)) || fs28.existsSync(path22.join(d.done, id)) || fs28.existsSync(path22.join(d.state, `${id}.status`))) {
       return lane;
     }
   }
@@ -3849,7 +3948,7 @@ function findLane(id) {
 }
 function rowsFor(lane, bucket) {
   const dir = laneDirs(lane)[bucket];
-  const entries = fs27.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => ({ f, m: fs27.statSync(path21.join(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m);
+  const entries = fs28.readdirSync(dir).filter((f) => !f.startsWith(".")).map((f) => ({ f, m: fs28.statSync(path22.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$/, "");
@@ -3891,7 +3990,7 @@ ${usageFor(cmd)}`);
       const d = {
         id: arg(args, "--id") ?? randomUUID4(),
         repo,
-        brief: briefText ?? fs27.readFileSync(briefFile, "utf8"),
+        brief: briefText ?? fs28.readFileSync(briefFile, "utf8"),
         harness: arg(args, "--harness"),
         model: arg(args, "--model"),
         effort: arg(args, "--effort"),
@@ -3942,8 +4041,8 @@ ${usageFor(cmd)}`);
       if (!id) throw new Error("logs requires a dispatch id");
       const lane = findLane(id);
       const file = eventsPath(id, lane);
-      if (fs27.existsSync(file)) {
-        const raw = fs27.readFileSync(file, "utf8");
+      if (fs28.existsSync(file)) {
+        const raw = fs28.readFileSync(file, "utf8");
         const lines = raw.split("\n").filter((l) => l.length > 0);
         const LIMIT = 50;
         if (!args.includes("--full") && lines.length > LIMIT) {
@@ -3956,15 +4055,15 @@ ${usageFor(cmd)}`);
         }
       }
       if (args.includes("--follow")) {
-        let size = fs27.existsSync(file) ? fs27.statSync(file).size : 0;
+        let size = fs28.existsSync(file) ? fs28.statSync(file).size : 0;
         setInterval(() => {
-          if (!fs27.existsSync(file)) return;
-          const now = fs27.statSync(file).size;
+          if (!fs28.existsSync(file)) return;
+          const now = fs28.statSync(file).size;
           if (now > size) {
-            const fd = fs27.openSync(file, "r");
+            const fd = fs28.openSync(file, "r");
             const buf = Buffer.alloc(now - size);
-            fs27.readSync(fd, buf, 0, buf.length, size);
-            fs27.closeSync(fd);
+            fs28.readSync(fd, buf, 0, buf.length, size);
+            fs28.closeSync(fd);
             process.stdout.write(buf.toString("utf8"));
             size = now;
           }
@@ -4018,16 +4117,16 @@ ${usageFor(cmd)}`);
         );
       }
       const dirs = laneDirs(lane);
-      const descriptorFile = ["active", "done"].map((b) => path21.join(dirs[b], id, "descriptor.json")).find((f) => fs27.existsSync(f));
-      const harness = descriptorFile ? JSON.parse(fs27.readFileSync(descriptorFile, "utf8")).harness ?? "claude" : "claude";
+      const descriptorFile = ["active", "done"].map((b) => path22.join(dirs[b], id, "descriptor.json")).find((f) => fs28.existsSync(f));
+      const harness = descriptorFile ? JSON.parse(fs28.readFileSync(descriptorFile, "utf8")).harness ?? "claude" : "claude";
       let sessionId;
       try {
-        sessionId = JSON.parse(fs27.readFileSync(path21.join(dirs.state, `${id}.evidence`), "utf8")).sessionId;
+        sessionId = JSON.parse(fs28.readFileSync(path22.join(dirs.state, `${id}.evidence`), "utf8")).sessionId;
       } catch {
       }
       if (!sessionId) throw new Error(`${id} has no recorded harness session to attach to`);
-      const worktree = path21.join(lobstahHome(), "worktrees", id);
-      const cwd = fs27.existsSync(worktree) ? worktree : process.cwd();
+      const worktree = path22.join(lobstahHome(), "worktrees", id);
+      const cwd = fs28.existsSync(worktree) ? worktree : process.cwd();
       const invocation = harness === "codex" ? codexInvocation(["resume", sessionId]) : { file: "claude", argv: ["--resume", sessionId] };
       if (!invocation) throw new Error("no codex CLI found \u2014 neither on PATH nor vendored by @openai/codex-sdk");
       if (args.includes("--print")) {
@@ -4042,19 +4141,19 @@ ${usageFor(cmd)}`);
       const id = args[0];
       if (!id) throw new Error("swap requires a dispatch id");
       const lane = findLane(id);
-      const activeDir = path21.join(laneDirs(lane).active, id);
-      if (!fs27.existsSync(activeDir)) throw new Error(`${id} is not active \u2014 swap only applies to in-flight dispatches`);
-      const descFile = path21.join(activeDir, "descriptor.json");
-      const descriptor = JSON.parse(fs27.readFileSync(descFile, "utf8"));
+      const activeDir = path22.join(laneDirs(lane).active, id);
+      if (!fs28.existsSync(activeDir)) throw new Error(`${id} is not active \u2014 swap only applies to in-flight dispatches`);
+      const descFile = path22.join(activeDir, "descriptor.json");
+      const descriptor = JSON.parse(fs28.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;
       }
-      fs27.writeFileSync(descFile, JSON.stringify(descriptor, null, 2));
-      const worktree = path21.join(lobstahHome(), "worktrees", id);
+      fs28.writeFileSync(descFile, JSON.stringify(descriptor, null, 2));
+      const worktree = path22.join(lobstahHome(), "worktrees", id);
       let progress = "No worktree progress recorded.";
-      if (fs27.existsSync(worktree)) {
+      if (fs28.existsSync(worktree)) {
         const git4 = (...a) => spawnSync6("git", a, { cwd: worktree, encoding: "utf8" }).stdout?.trim() ?? "";
         const commits = git4("log", "--oneline", "-15");
         const status = git4("status", "--short");
@@ -4064,17 +4163,17 @@ ${commits || "(none)"}
 Uncommitted changes:
 ${status || "(clean)"}`;
       }
-      fs27.writeFileSync(
-        path21.join(activeDir, "handoff"),
+      fs28.writeFileSync(
+        path22.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 = path21.join(activeDir, "runner.json");
-      if (fs27.existsSync(runnerFile)) {
-        const runner = JSON.parse(fs27.readFileSync(runnerFile, "utf8"));
+      const runnerFile = path22.join(activeDir, "runner.json");
+      if (fs28.existsSync(runnerFile)) {
+        const runner = JSON.parse(fs28.readFileSync(runnerFile, "utf8"));
         if (pidAlive(runner.pid, runner.processStartTime)) killGroup(runner.pid, "SIGKILL");
-        fs27.unlinkSync(runnerFile);
+        fs28.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 }));
@@ -4179,20 +4278,20 @@ ${progress}`
       break;
     }
     case "man:init": {
-      const file = args.includes("--global") ? path21.join(os6.homedir(), ".claude", "settings.json") : path21.join(".claude", args.includes("--shared") ? "settings.json" : "settings.local.json");
+      const file = args.includes("--global") ? path22.join(os6.homedir(), ".claude", "settings.json") : path22.join(".claude", args.includes("--shared") ? "settings.json" : "settings.local.json");
       let existing;
       try {
-        existing = JSON.parse(fs27.readFileSync(file, "utf8"));
+        existing = JSON.parse(fs28.readFileSync(file, "utf8"));
       } catch {
         existing = void 0;
       }
       const { settings, changed } = mergeHaulHook(existing);
       if (changed) {
-        fs27.mkdirSync(path21.dirname(file), { recursive: true });
-        fs27.writeFileSync(file, `${JSON.stringify(settings, null, 2)}
+        fs28.mkdirSync(path22.dirname(file), { recursive: true });
+        fs28.writeFileSync(file, `${JSON.stringify(settings, null, 2)}
 `);
       }
-      if (args.includes("--marker")) fs27.writeFileSync(".lobstah-man", "");
+      if (args.includes("--marker")) fs28.writeFileSync(".lobstah-man", "");
       console.log(
         toonKV({
           hook: "lobstah man haul",
@@ -4211,9 +4310,9 @@ ${progress}`
           await soakPark(soakReg.sessionId, args);
           break;
         }
-        if (process.env.LOBSTAH_MAN !== "1" && !fs27.existsSync(".lobstah-man")) break;
+        if (process.env.LOBSTAH_MAN !== "1" && !fs28.existsSync(".lobstah-man")) break;
         const anyActive = ["work", "chore"].some(
-          (l) => fs27.readdirSync(laneDirs(l).active).some((f) => !f.startsWith("."))
+          (l) => fs28.readdirSync(laneDirs(l).active).some((f) => !f.startsWith("."))
         );
         const anyWatch = listWatches().some((w) => w.owner === "man");
         if (!anyActive && !anyWatch) break;
@@ -4375,7 +4474,7 @@ ${progress}`
         path: r.path,
         trunk: r.trunk,
         pickup: r.pickup ?? false,
-        exists: fs27.existsSync(r.path)
+        exists: fs28.existsSync(r.path)
       }));
       console.log(toonTable("repos", rows, ["key", "path", "trunk", "pickup", "exists"]));
       break;
@@ -4425,7 +4524,7 @@ ${progress}`
       break;
     }
     case "init": {
-      if (!fs27.existsSync(configPath())) {
+      if (!fs28.existsSync(configPath())) {
         const exampleRepo = args.includes("--scan") ? "" : `[repos.example]
 path  = "~/src/example"
 trunk = "main"
@@ -4434,7 +4533,7 @@ trunk = "main"
 # pickup = true   # opt into [pickup.github] multi-repo tracker pickup
 
 `;
-        fs27.writeFileSync(
+        fs28.writeFileSync(
           configPath(),
           `# lobstah workspace definitions \u2014 the descriptor's repo key resolves here.
 # Top-level keys must come before any [section].
@@ -4472,12 +4571,12 @@ wallClockSecs      = 3600
       let reference = "https://github.com/aequitas-labs/lobstah/blob/main/docs/configuration.md";
       try {
         const local = fileURLToPath2(new URL("../docs/configuration.md", import.meta.url));
-        if (fs27.existsSync(local)) reference = local;
+        if (fs28.existsSync(local)) reference = local;
       } catch {
       }
       console.log(
         toonKV({
-          home: path21.dirname(configPath()),
+          home: path22.dirname(configPath()),
           config: configPath(),
           ...added.length > 0 ? { added: added.join(", ") } : {},
           ...unmarked.length > 0 ? { note: `none marked pickable \u2014 set pickup = true per [repos.*] (or rerun with --pickup)` } : {},

package/docs/pickup.md

@@ -92,12 +92,30 @@ The three loops are tracker-agnostic and drive whichever sources are configured.
 | Rule | Trigger | Descriptor |
 |---|---|---|
 | Issue pickup | Assigned to the configured identity, in the configured start state | Implementation brief from the issue |
-| Review pickup | Open PR authored by the configured identity with `CHANGES_REQUESTED`, or a human review newer than HEAD | Address-review brief from the feedback |
-
-A review dispatch sets `followUp` to the implementation dispatch's UUID,
-forking that session so the feedback lands on the context that made the
-choices. A rebase chore starts cold on purpose — the conflict is about commits
-the original session never saw.
+| Feedback pickup | Human feedback on an open PR that maps back to a dispatch | Address-feedback brief; the agent reads the live thread |
+
+A dispatch reports `done` when its PR opens, so the reviewer's side of the
+conversation has to re-enter the queue as its own work. Feedback pickup
+covers all of it: a `CHANGES_REQUESTED` review on any sha (a review of a
+slightly stale head still asks for changes), a comment review with a body,
+an inline review-thread comment, or a conversation comment — always from
+someone other than the configured identity, never a lobstah marker comment.
+`APPROVED` reviews are the merge loop's signal, not feedback.
+
+The PR maps back to a dispatch two ways: a `lobstah/<uuid>` branch names it
+directly, and any other branch — a soaked session's PR — resolves through
+the PR URL its worker reported as evidence (`report done --pr <url>`). A PR
+that maps to neither is not lobstah's to answer.
+
+Each feedback **round** is keyed by the newest feedback event, so a new
+comment after a round completes opens the next round, while the same standing
+feedback never double-dispatches. Rounds on one PR serialize — a round that
+arrives while the previous one runs buffers until it finishes — and each
+round sets `followUp` to the latest session in the chain (the previous
+round, else the implementation dispatch), so feedback lands on the context
+that made the choices; a fully culled chain starts cold and reads the thread
+like anyone else. A rebase chore starts cold on purpose — the conflict is
+about commits the original session never saw.
 
 ### Claiming
 
@@ -339,7 +357,7 @@ Pickup's three loops and the daemon absorb that whole layer:
 | Fleet-script job | Fate |
 |---|---|
 | Poll tracker, dispatch assigned issues | Dispatch loop, issue rule |
-| Watch PRs for review feedback | Dispatch loop, review rule |
+| Watch PRs for review feedback | Dispatch loop, feedback rule |
 | Per-dispatch outcome checks and cron re-arms | Daemon supervision + `report` |
 | Merge approved PRs | Merge loop |
 | Detect in-progress issues nothing backs | Dead/wedged half → daemon; tracker-drift half → reconciliation loop |

package/package.json

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