@tiens.nguyen/gu-cli 1.0.686

package/job-pools.mjs

@@ -0,0 +1,89 @@
+/**
+ * Concurrency for the worker's claim loop (task #152).
+ *
+ * WHY THIS IS A MODULE. An agent turn used to be `await runAgentChatJob(job); return;` inside
+ * the poll loop, so one folder's turn — 100 seconds to an hour — held the loop for its whole
+ * duration and a second `gu` in another folder was told "no worker has claimed the job".
+ * The claim loop itself cannot be unit-tested (importing gu-cli.mjs starts a daemon), and
+ * the two things that decide whether concurrent folders work correctly are exactly the two
+ * things worth testing: how many turns may run, and what happens to work that arrives while
+ * the resource is taken.
+ *
+ * Both are deliberately tiny and pure. The bug being fixed was not complicated — it was
+ * invisible, because it lived in a line of control flow nothing could assert on.
+ */
+
+/**
+ * A bounded set of in-flight promises.
+ *
+ * `track` never rejects: a task that throws must still free its slot, or one failure
+ * permanently shrinks the pool — the kind of leak that only shows up after a long uptime.
+ */
+export function createTaskPool({ limit = 1 } = {}) {
+  const max = Math.max(1, Number(limit) || 1);
+  const inFlight = new Set();
+  return {
+    get size() {
+      return inFlight.size;
+    },
+    get limit() {
+      return max;
+    },
+    hasRoom: () => inFlight.size < max,
+    track(task) {
+      inFlight.add(task);
+      Promise.resolve(task)
+        .catch(() => {})
+        .finally(() => inFlight.delete(task));
+      return task;
+    },
+  };
+}
+
+/**
+ * Serialise work across folders WITHOUT throwing any of it away.
+ *
+ * The between-turns RAG index used a single boolean and `return`ed when it was set, so while
+ * folder A indexed, folder B's pass was silently DROPPED — folder B was then left with no
+ * knowledge base and nothing said why. The GPU reasoning behind serialising was right; the
+ * disposal was the bug.
+ *
+ * One pending entry per folder, newest wins: a folder that asks twice while waiting wants the
+ * later state of its files, not two passes over the earlier one.
+ */
+export function createFolderQueue() {
+  const running = new Set();
+  const pending = new Map();
+  return {
+    get runningCount() {
+      return running.size;
+    },
+    get pendingCount() {
+      return pending.size;
+    },
+    /**
+     * @returns "start" — run it now (the caller must call finish() when done)
+     *          "already" — this folder is mid-run; nothing to do
+     *          "queued" — another folder holds the slot; it will run later
+     */
+    request(folder, args) {
+      if (running.has(folder)) return "already";
+      if (running.size > 0) {
+        pending.set(folder, args); // newest supersedes an older wait for the same folder
+        return "queued";
+      }
+      running.add(folder);
+      return "start";
+    },
+    /** Release `folder` and hand the slot to whoever waited longest. */
+    finish(folder) {
+      running.delete(folder);
+      const next = pending.entries().next();
+      if (next.done) return null;
+      const [nextFolder, args] = next.value;
+      pending.delete(nextFolder);
+      running.add(nextFolder);
+      return { folder: nextFolder, args };
+    },
+  };
+}