beadcyte 0.4.0

package/src/stage-waits.mjs

@@ -0,0 +1,69 @@
+// stage-waits.mjs — how long beads on this project WAIT, per stage, from the
+// beads themselves (bp-m0g; bp-7c9 adds the stages the tracker does not yet
+// hold). The scheduler's second clock reads these medians: work is what the
+// estimator predicts, waiting is what history says surrounds it.
+//
+//   unclaimed  created_at → started_at   on closed beads: the queue wait.
+//   assigned   created_at → first assignee (bead.history.assigned_at, from
+//              the walk, bp-7c9): how long a filed bead sits before anyone owns it.
+//   review     recorded metadata.economics.hours_in_review first; else first
+//              MR opened (metadata.ship.mr_opened_at, bp-7c9) → closed; else
+//              first in_review (bead.history.in_review_at) → closed. Never invented.
+//
+// Medians, on samples inside (0, 180) days like the estimator's own lead
+// samples, and null when there are none — a null wait is "unknown", which
+// the scheduler covers with the lead-time floor, not "zero".
+
+const MS_PER_DAY = 86_400_000;
+
+function median(xs) {
+  if (xs.length === 0) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+const days = (from, to) => (Date.parse(to) - Date.parse(from)) / MS_PER_DAY;
+const sane = (d) => Number.isFinite(d) && d > 0 && d < 180;
+
+/**
+ * @param {ReadonlyArray<{status?: string, created_at?: string|null, started_at?: string|null, closed_at?: string|null,
+ *   history?: {in_review_at?: string|null} | null, metadata?: {economics?: {hours_in_review?: unknown}} | null}>} beads
+ * @returns {{ unclaimedDays: number | null, unclaimedN: number, assignedDays: number | null, assignedN: number, reviewDays: number | null, reviewN: number }}
+ */
+export function stageWaits(beads) {
+  const unclaimed = [];
+  const assigned = [];
+  const review = [];
+  for (const b of beads ?? []) {
+    if (b?.status !== "closed" || !b.closed_at) continue;
+    if (b.created_at && b.started_at) {
+      const d = days(b.created_at, b.started_at);
+      if (sane(d)) unclaimed.push(d);
+    }
+    if (b.created_at && b.history?.assigned_at) {
+      const d = days(b.created_at, b.history.assigned_at);
+      if (sane(d)) assigned.push(d);
+    }
+    const recorded = b.metadata?.economics?.hours_in_review;
+    const mrOpened = b.metadata?.ship?.mr_opened_at;
+    if (typeof recorded === "number" && Number.isFinite(recorded) && recorded > 0) {
+      const d = recorded / 24;
+      if (sane(d)) review.push(d);
+    } else if (typeof mrOpened === "string" && mrOpened) {
+      const d = days(mrOpened, b.closed_at);
+      if (sane(d)) review.push(d);
+    } else if (b.history?.in_review_at) {
+      const d = days(b.history.in_review_at, b.closed_at);
+      if (sane(d)) review.push(d);
+    }
+  }
+  return {
+    unclaimedDays: median(unclaimed),
+    unclaimedN: unclaimed.length,
+    assignedDays: median(assigned),
+    assignedN: assigned.length,
+    reviewDays: median(review),
+    reviewN: review.length,
+  };
+}

package/src/start.mjs

@@ -0,0 +1,111 @@
+// start.mjs — `beadcyte start`: run the server in the background and return.
+//
+// Spawns `beadcyte serve` detached, with its output going to a log file, waits
+// for the child to record where it is listening (see server-state.mjs), prints
+// the child's startup output and how to stop it, and exits. The child writes
+// the record rather than this process guessing, because only the child knows
+// the port once serve has fallen through from a busy 4173.
+//
+// Runs on import like the other subcommands; bin/beadcyte.mjs dispatches here.
+
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import {
+  clearState,
+  describeRunning,
+  isAlive,
+  logFileFor,
+  readState,
+  stateFileFor,
+} from "./server-state.mjs";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+const cwd = process.cwd();
+const stateFile = stateFileFor(cwd);
+const logFile = logFileFor(cwd);
+
+// One server per directory. A record whose process has gone is just a
+// leftover from a crash or a reboot, and is replaced.
+const existing = readState(stateFile);
+if (existing && isAlive(existing.pid)) {
+  console.log(
+    describeRunning(existing).replace(/^beadcyte is running/, "beadcyte is already running"),
+  );
+  process.exit(0);
+}
+if (existing) clearState(stateFile);
+
+mkdirSync(dirname(logFile), { recursive: true });
+const logFd = openSync(logFile, "w");
+const dispatcher = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "beadcyte.mjs");
+const child = spawn(process.execPath, [dispatcher, "serve", ...argv], {
+  cwd,
+  detached: true,
+  stdio: ["ignore", logFd, logFd],
+  env: { ...process.env, BEADCYTE_STATE_FILE: stateFile, BEADCYTE_LOG_FILE: logFile },
+});
+closeSync(logFd); // the child holds its own copy
+let exitCode = null;
+child.on("exit", (code, signal) => {
+  exitCode = code ?? (signal ? 1 : 0);
+});
+child.unref();
+
+const TIMEOUT_MS = 30_000;
+const deadline = Date.now() + TIMEOUT_MS;
+while (Date.now() < deadline) {
+  const state = readState(stateFile);
+  if (state && state.pid === child.pid) {
+    process.stdout.write(logSoFar());
+    console.log(describeRunning(state));
+    process.exit(0);
+  }
+  if (exitCode !== null) {
+    process.stderr.write(logSoFar());
+    console.error(
+      `beadcyte serve exited with code ${exitCode} before it was listening. Log: ${logFile}`,
+    );
+    process.exit(1);
+  }
+  await sleep(100);
+}
+process.stderr.write(logSoFar());
+console.error(
+  `beadcyte serve (pid ${child.pid}) has not reported listening after ${TIMEOUT_MS / 1000}s. ` +
+    `It may still be starting: check ${logFile}, or run \`beadcyte stop\` to end it.`,
+);
+process.exit(1);
+
+function logSoFar() {
+  try {
+    return readFileSync(logFile, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function printHelp() {
+  console.log(`beadcyte start — run the interactive app in the background
+
+Usage:
+  beadcyte start [--port N] [--roster PATH] [--cache-ttl MS]
+
+Starts \`beadcyte serve\` for the CURRENT WORKING DIRECTORY as a detached
+process, prints its address once it is listening, and returns. Output goes to
+a log file whose path is printed. One server per directory: a second start
+reports the running one.
+
+  beadcyte stop     ends it, from the same directory
+  beadcyte serve    runs the same server in the foreground instead
+
+Flags are passed through to serve; see \`beadcyte serve --help\`.
+`);
+}

package/src/stop.mjs

@@ -0,0 +1,66 @@
+// stop.mjs — `beadcyte stop`: end the background server for this directory.
+//
+// Finds the record `beadcyte start` left for the current working directory
+// (see server-state.mjs), sends SIGTERM, waits briefly, and clears the record.
+// Not running is a normal outcome, not an error: the user wanted it stopped
+// and it is.
+//
+// Runs on import like the other subcommands; bin/beadcyte.mjs dispatches here.
+
+import { setTimeout as sleep } from "node:timers/promises";
+import { clearState, isAlive, readState, stateFileFor } from "./server-state.mjs";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+const cwd = process.cwd();
+const stateFile = stateFileFor(cwd);
+const state = readState(stateFile);
+
+if (!state) {
+  console.log(`beadcyte is not running for ${cwd}.`);
+  process.exit(0);
+}
+if (!isAlive(state.pid)) {
+  clearState(stateFile);
+  console.log(`beadcyte (pid ${state.pid}) was already gone; cleared its record.`);
+  process.exit(0);
+}
+
+try {
+  process.kill(state.pid, "SIGTERM");
+} catch (e) {
+  console.error(`beadcyte: could not signal pid ${state.pid}: ${e.message}`);
+  process.exit(1);
+}
+
+const GRACE_MS = 5_000;
+const deadline = Date.now() + GRACE_MS;
+while (isAlive(state.pid) && Date.now() < deadline) await sleep(100);
+if (isAlive(state.pid)) {
+  try {
+    process.kill(state.pid, "SIGKILL");
+  } catch {}
+  await sleep(200);
+}
+clearState(stateFile);
+
+if (isAlive(state.pid)) {
+  console.error(`beadcyte (pid ${state.pid}) did not exit; cleared its record anyway.`);
+  process.exit(1);
+}
+console.log(`stopped beadcyte (pid ${state.pid}) at ${state.url}`);
+
+function printHelp() {
+  console.log(`beadcyte stop — end the background server started in this directory
+
+Usage:
+  beadcyte stop
+
+Sends SIGTERM to the server \`beadcyte start\` launched for the CURRENT
+WORKING DIRECTORY and clears its record. Exits 0 when nothing was running.
+`);
+}

package/src/velocity.mjs

@@ -0,0 +1,209 @@
+// velocity.mjs — observed per-human close-rate, used to calibrate the
+// scheduler's WIP cap against reality.
+//
+// The scheduler's raw WIP-cap model (roster.humans[i].cap, default 5) sets
+// a hard ceiling on concurrent work per person. In practice teams don't
+// run at full WIP forever — throughput is bounded by whoever's actually
+// shipping. If alice ships one bead a week and bob three, projecting
+// alice at cap 5 makes the whole plan fiction.
+//
+// This module walks the shipped history (ship evidence + closed_at) and
+// reports a per-human close-rate over a lookback window. Consumers
+// (scheduler, CLI, UI footer) fold that into an effective cap:
+//   calibratedCap = min(wipCap, round(closesPerWeek))
+//
+// Humans with zero closes in the lookback keep their raw cap — new hires
+// or brand-new projects shouldn't get zeroed out.
+
+import { isShipped } from "./ship.mjs";
+
+const MS_PER_DAY = 86_400_000;
+const MS_PER_WEEK = 7 * MS_PER_DAY;
+const DEFAULT_LOOKBACK_DAYS = 60;
+
+/**
+ * @param {Array} beads   — all beads (bd list --all shape)
+ * @param {Object} [opts]
+ * @param {number} [opts.lookbackDays=60]  — window for close-rate
+ * @param {Date} [opts.asOf=new Date()]    — reference "now" (test hook)
+ * @returns {{
+ *   asOf: Date,
+ *   lookbackDays: number,
+ *   perHuman: Map<string, {
+ *     handle: string,
+ *     closedInWindow: number,
+ *     closesPerWeek: number,
+ *     lastClosedAt: string | null,
+ *     hoursInWindow: number,
+ *     hoursPerWeek: number,
+ *     weekly: number[],   // ships per week, same buckets as the project series (bp-67g.43)
+ *   }>,
+ *   totalClosedInWindow: number,
+ *   totalHoursInWindow: number,
+ *   activeCount: number,
+ *   weekly: Array<{ weekStart: Date, count: number }>,
+ *   weeklyTotal: number,
+ *   weeklyWeeks: number
+ * }}
+ */
+export function computeVelocity(beads, opts = {}) {
+  const lookbackDays = opts.lookbackDays ?? DEFAULT_LOOKBACK_DAYS;
+  const asOf = opts.asOf ?? new Date();
+  const cutoff = asOf.getTime() - lookbackDays * MS_PER_DAY;
+
+  const perHuman = new Map();
+  let totalClosedInWindow = 0;
+  let totalHoursInWindow = 0;
+
+  // The weekly series, accumulated in the same pass as the close counts so
+  // the trend and the rate can never disagree about what a ship is.
+  //
+  // Buckets are WHOLE weeks ending at asOf, counted backwards — not forwards
+  // from the close-rate cutoff. Forwards leaves a partial final bucket
+  // whenever lookbackDays isn't a multiple of 7 (60 days is 8 weeks and 4
+  // days), and a partial bucket makes the most recent point dip for
+  // arithmetic reasons rather than real ones, which is exactly the reading a
+  // trend chart is for. The cost is dropping the oldest remainder days, so
+  // this window is `weeklyWeeks * 7` days, which is reported rather than
+  // assumed to equal lookbackDays.
+  const weeklyWeeks = Math.max(1, Math.floor(lookbackDays / 7));
+  const weeklyStart = asOf.getTime() - weeklyWeeks * MS_PER_WEEK;
+  const weeklyCounts = new Array(weeklyWeeks).fill(0);
+
+  const getEntry = (handle) => {
+    let entry = perHuman.get(handle);
+    if (!entry) {
+      entry = {
+        handle,
+        closedInWindow: 0,
+        closesPerWeek: 0,
+        lastClosedAt: null,
+        hoursInWindow: 0,
+        hoursPerWeek: 0,
+        // The person's own weekly series, in the project's buckets, so a
+        // person's trend and the project's are the same chart on the same
+        // definition of a ship (bp-67g.43).
+        weekly: new Array(weeklyWeeks).fill(0),
+      };
+      perHuman.set(handle, entry);
+    }
+    return entry;
+  };
+
+  // Pass 1: bead-close events (existing signal).
+  for (const b of beads) {
+    if (b.status !== "closed") continue;
+    if (!isShipped(b)) continue; // real ships only — see ship.mjs
+    if (!b.closed_at) continue;
+    const closedAt = new Date(b.closed_at).getTime();
+    if (Number.isNaN(closedAt)) continue;
+    // The weekly window is shorter than the close-rate window, so a ship can
+    // count toward one and not the other. Bucket before the cutoff test.
+    const handle = b.assignee ?? "__unassigned";
+    if (closedAt >= weeklyStart && closedAt < asOf.getTime()) {
+      const bucket = Math.floor((closedAt - weeklyStart) / MS_PER_WEEK);
+      // Guard the boundary: a close landing exactly on asOf would index off
+      // the end, and clamping is cheaper than trusting float division.
+      const i = Math.min(weeklyWeeks - 1, bucket);
+      weeklyCounts[i]++;
+      getEntry(handle).weekly[i]++;
+    }
+    if (closedAt < cutoff) continue;
+    const entry = getEntry(handle);
+    entry.closedInWindow++;
+    if (!entry.lastClosedAt || b.closed_at > entry.lastClosedAt) {
+      entry.lastClosedAt = b.closed_at;
+    }
+    totalClosedInWindow++;
+  }
+
+  // Pass 2: agent-hour sessions (richer signal). metadata.economics.by_seat
+  // records per-human session dates + hours; we sum every session whose
+  // date falls inside the window. Unlike close-rate this attributes work
+  // to WHOEVER actually put in the hours, not just the closing assignee.
+  for (const b of beads) {
+    const bySeat = b.metadata?.economics?.by_seat;
+    if (!bySeat || typeof bySeat !== "object") continue;
+    for (const seatData of Object.values(bySeat)) {
+      const sessions = seatData?.sessions;
+      if (!Array.isArray(sessions)) continue;
+      for (const s of sessions) {
+        if (!s?.date || typeof s.hours !== "number") continue;
+        const sessionAt = new Date(s.date).getTime();
+        if (isNaN(sessionAt) || sessionAt < cutoff) continue;
+        const handle = s.human ?? "__unassigned";
+        const entry = getEntry(handle);
+        entry.hoursInWindow += s.hours;
+        totalHoursInWindow += s.hours;
+      }
+    }
+  }
+
+  for (const entry of perHuman.values()) {
+    entry.closesPerWeek = entry.closedInWindow / (lookbackDays / 7);
+    entry.hoursPerWeek = entry.hoursInWindow / (lookbackDays / 7);
+  }
+
+  return {
+    asOf,
+    lookbackDays,
+    perHuman,
+    totalClosedInWindow,
+    totalHoursInWindow,
+    activeCount: perHuman.size,
+    weekly: weeklyCounts.map((count, i) => ({
+      weekStart: new Date(weeklyStart + i * MS_PER_WEEK),
+      count,
+    })),
+    weeklyTotal: weeklyCounts.reduce((a, n) => a + n, 0),
+    weeklyWeeks,
+  };
+}
+
+/**
+ * Fold observed velocity into a roster's per-human caps. Returns a new
+ * roster object; the original is untouched.
+ *
+ * Applies Little's Law — average WIP = throughput × cycle time — so a
+ * human's cap becomes the number of beads they can *realistically* have
+ * in flight at once given how fast they ship and how long each bead takes:
+ *
+ *   calibratedCap = clamp(round(closesPerWeek × cycleDays / 7), 1, rawCap)
+ *
+ * That's much stricter than a naive round(closesPerWeek). A human
+ * shipping 4/week with median cycle time 5 days ends up capped at
+ * ceil(4·5/7) = 3 in-flight, not 4. Humans with no shipped history keep
+ * their raw cap so brand-new projects still get a projection.
+ */
+export function calibrateRoster(roster, velocity, options = {}) {
+  const defaultCap = roster.cap ?? 5;
+  const cycleDays = options.medianCycleDays ?? 5;
+  const humans = (roster.humans ?? []).map((h) => {
+    const v = velocity.perHuman.get(h.handle);
+    const rawCap = h.cap ?? defaultCap;
+    let calibratedCap = rawCap;
+    let derivation = "raw (no history)";
+    // A fixed cap is a decision, not an estimate: roster.json can say so
+    // (`"cap_fixed": true`), and a what-if cap always does (bp-q56) — the
+    // point of asking "what if their cap were 3" is to see 3, not to have
+    // history clamp it back.
+    if (h.cap_fixed) {
+      derivation = "fixed";
+    } else if (v && v.closesPerWeek > 0) {
+      const wipEstimate = (v.closesPerWeek * cycleDays) / 7;
+      calibratedCap = Math.max(1, Math.min(rawCap, Math.round(wipEstimate)));
+      derivation = `Little: ${v.closesPerWeek.toFixed(1)}/wk × ${cycleDays.toFixed(1)}d`;
+    }
+    return {
+      ...h,
+      cap: calibratedCap,
+      _rawCap: rawCap,
+      _closedInWindow: v?.closedInWindow ?? 0,
+      _closesPerWeek: v?.closesPerWeek ?? 0,
+      _hoursInWindow: v?.hoursInWindow ?? 0,
+      _hoursPerWeek: v?.hoursPerWeek ?? 0,
+      _capDerivation: derivation,
+    };
+  });
+  return { ...roster, humans, _calibrated: true, _cycleDays: cycleDays };
+}