gcf-board 0.2.6 → 0.2.9

package/README.md

@@ -30,7 +30,7 @@ It puts **GCF Board** on the desktop (Windows: a shortcut whose server console s
 
 ## What it does
 
-- **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model.
+- **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model. A running card shows when its run log was last written (`active 12 s ago`), and `quiet 6 min` when the log has been silent for 5 minutes or more. A run's end report gives each item's cost when the agent reported it.
 - **An item**: its file, its plan and its run log as it grows, and the moves the core offers for it (`items[].moves`, Methodology §4.1): verdict, decide, block, unblock, drop, close, submit. The board keeps only each move's form; the core still checks the rest itself, and the board shows its answer.
 - **Drag**:
   - a ready card into **running** starts its run;
@@ -42,7 +42,7 @@ It puts **GCF Board** on the desktop (Windows: a shortcut whose server console s
   - `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
   - `run_mode: main`: one item at a time in the project folder. A run asked for meanwhile waits in the board's **queue**; **remove from queue** takes it out.
 
-  A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash): run it again and the run resumes its work. When a run ends, a toast lists each item's result. The queue lives in the board's memory: a board restart forgets it.
+  A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash, the usage limit): **resume** continues its agent session with all its context, **start fresh** drops it. After the usage limit the card reads **paused: limit** and the board resumes it by itself at the reset time; the header shows **resumes HH:MM** with **cancel**. When a run ends, a toast lists each item's result. The queue lives in the board's memory: a board restart forgets it.
 - **Run next N independent**: the framework's gate picks the ready items that can run together now, by priority, and the board runs them after asking.
 - **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
 - **Questions**: each D1 shows its question and proposed answer; **Answer** writes yours into its record (`gcf question answer`), and the next agent on its units puts it in place.

package/dist/server/app.js

@@ -14,7 +14,7 @@ import { followLog, readShown, shownShape } from './files.js';
 import { HttpError } from './http-error.js';
 import { moveArgs, runIds } from './moves.js';
 import { addProject, listProjects, projectOf, removeProject } from './registry.js';
-import { resumeQueue, runsOf, startRun, unqueue } from './runs.js';
+import { cancelResume, forgetProject, resumeQueue, runsOf, startRun, unqueue } from './runs.js';
 const send = (res, status, body) => {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(body));
@@ -49,6 +49,15 @@ function jsonOf(r, what) {
         throw new HttpError(502, `ai-factory ${what} gave no report: ${(r.err || r.out).trim()}`);
     }
 }
+/** The ISO time a file was last written, or null when it is not there. */
+const activeAt = (file) => {
+    try {
+        return statSync(file).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+};
 const TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'text/javascript; charset=utf-8',
@@ -116,6 +125,7 @@ export function createApp(o) {
             /^\/api\/projects\/([^/]+)$/,
             async (_req, res, m) => {
                 await removeProject(m[1]);
+                forgetProject(m[1]);
                 watchers.get(m[1])?.();
                 watchers.delete(m[1]);
                 send(res, 200, { ok: true });
@@ -129,7 +139,12 @@ export function createApp(o) {
                 // The board's own runs ride along: what it started and what waits in its queue; and the
                 // count of plan writes, which tells the page an open plan's text changed.
                 const own = { runs: runsOf(p.name), plans_rev: planRev(p.name) };
-                send(res, 200, { ...(await boardOf(p)), ...own });
+                const board = await boardOf(p);
+                // A running item's last log write tells a working session from a stuck one.
+                for (const i of board.items)
+                    if (i.running)
+                        i.active_at = i.log ? activeAt(path.join(p.path, i.log)) : null;
+                send(res, 200, { ...board, ...own });
             },
         ],
         [
@@ -191,8 +206,9 @@ export function createApp(o) {
             /^\/api\/p\/([^/]+)\/run$/,
             async (req, res, m) => {
                 const p = await projectOf(m[1]);
-                const ids = runIds(await bodyOf(req));
-                send(res, 202, startRun(o.entry, p, ids, (await boardOf(p)).run_mode));
+                const body = await bodyOf(req);
+                const mode = (await boardOf(p)).run_mode;
+                send(res, 202, startRun(o.entry, p, runIds(body), mode, body.fresh === true));
             },
         ],
         [
@@ -224,6 +240,15 @@ export function createApp(o) {
                 send(res, 200, { ok: true });
             },
         ],
+        [
+            // The resume a usage limit scheduled; the queue stays paused.
+            'DELETE',
+            /^\/api\/p\/([^/]+)\/schedule$/,
+            async (_req, res, m) => {
+                cancelResume((await projectOf(m[1])).name);
+                send(res, 200, { ok: true });
+            },
+        ],
         [
             'DELETE',
             /^\/api\/p\/([^/]+)\/queue\/([a-z0-9][a-z0-9-]*)$/,

package/dist/server/events.js

@@ -29,6 +29,7 @@ export function broadcast(event) {
 // that stopped. shortcut: a copy of the core's constant, read it from the board JSON once the core
 // reports a mark's expiry.
 const SESSION_TTL_MS = 120 * 60_000;
+const LOG_STEP_MS = 10_000;
 const alive = (pid) => {
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
@@ -42,8 +43,8 @@ const alive = (pid) => {
 };
 /**
  * What makes items `running` in a runs directory: its entries, whether each lock's process
- * lives, whether each session mark is fresh. A run that died or a session that expired changes
- * it with no file written.
+ * lives, whether each session mark is fresh; and how recently each run log was written. A run
+ * that died or a session that expired changes it with no file written.
  */
 export function runsState(dir, now = Date.now()) {
     let names;
@@ -61,6 +62,10 @@ export function runsState(dir, now = Date.now()) {
                 return `${n} ${alive(Number(readFileSync(file, 'utf8').split('\n')[0]))}`;
             if (n.endsWith('.session'))
                 return `${n} ${now - statSync(file).mtimeMs < SESSION_TTL_MS}`;
+            // A session writes its log many times a second: its card's activity time moves by steps
+            // of LOG_STEP_MS, each one a board read, not one per line.
+            if (n.endsWith('.log'))
+                return `${n} ${Math.floor(statSync(file).mtimeMs / LOG_STEP_MS)}`;
         }
         catch {
             // Gone meanwhile: the next poll sees it.

package/dist/server/runs.js

@@ -12,13 +12,123 @@ const active = new Set();
 const queues = new Map();
 // Projects whose queue waits after a failure the next run would repeat (`stalled`).
 const paused = new Set();
+// shortcut: the scheduled resume after a usage limit lives in memory, like the queue: a board
+// restart loses it, and the operator resumes by hand; persist it if restarts become common.
+const scheduled = new Map();
+// The paused projects whose pause the usage limit set: its reset may lift it, nothing else.
+const limitPaused = new Set();
+// Runs going on for a project the operator removed: their end touches no project state.
+const forgotten = new WeakSet();
 export const activeRuns = (project) => [...active].filter((r) => r.project === project);
 /** What runs and what waits, for a project; a paused queue waits for `resumeQueue`. */
-export const runsOf = (project) => ({
-    active: activeRuns(project),
-    queued: (queues.get(project) ?? []).flatMap((q) => q.ids),
-    paused: paused.has(project),
-});
+export function runsOf(project) {
+    const s = scheduled.get(project);
+    return {
+        active: activeRuns(project),
+        queued: (queues.get(project) ?? []).flatMap((q) => q.ids),
+        paused: paused.has(project),
+        // When the items a usage limit stopped run again by themselves, and the queue with them.
+        resume: s ? { at: s.at.toISOString(), ids: s.run.ids } : null,
+    };
+}
+/**
+ * The time a usage limit resets, as Claude names it (`3am`, `3:30pm`, `15:00`, with or without
+ * `(Europe/Berlin)`): its next occurrence after `now`, a minute late to be safe; null when the
+ * text is no such time.
+ */
+export function resetAt(text, now = new Date()) {
+    // shortcut: the time is read on this machine's clock and the zone it names is ignored: the
+    // board runs where the operator's claude does; convert through Intl if a zone ever differs.
+    const m = /^\s*(\d{1,2})(?::(\d{2}))?\s*([ap]m)?\s*(\(.*\))?\s*$/i.exec(text);
+    if (!m || (!m[2] && !m[3]))
+        return null;
+    let hour = Number(m[1]);
+    const minute = Number(m[2] ?? 0);
+    if (m[3]) {
+        if (hour < 1 || hour > 12)
+            return null;
+        hour = (hour % 12) + (m[3].toLowerCase() === 'pm' ? 12 : 0);
+    }
+    if (hour > 23 || minute > 59)
+        return null;
+    const at = new Date(now);
+    at.setHours(hour, minute + 1, 0, 0);
+    if (at <= now)
+        at.setDate(at.getDate() + 1);
+    return at;
+}
+/** Drop the scheduled resume; the queue stays as it is. */
+export function cancelResume(project) {
+    clearTimeout(scheduled.get(project)?.timer);
+    scheduled.delete(project);
+    broadcast({ type: 'board', project });
+}
+/** Lift a pause the usage limit set; a pause for another cause waits for the operator. */
+function liftLimitPause(project) {
+    if (limitPaused.delete(project))
+        paused.delete(project);
+}
+/** A project left the board: nothing of it may run or fire any more. */
+export function forgetProject(project) {
+    for (const r of activeRuns(project))
+        forgotten.add(r);
+    clearTimeout(scheduled.get(project)?.timer);
+    scheduled.delete(project);
+    queues.delete(project);
+    paused.delete(project);
+    limitPaused.delete(project);
+}
+/**
+ * At the reset: run the stopped items again (the harness resumes their sessions), then the queue.
+ * A second limited run joins the first: all their items go, at the later reset.
+ */
+function schedule(run, at) {
+    const project = run.p.name;
+    const before = scheduled.get(project);
+    clearTimeout(before?.timer);
+    const ids = [...new Set([...(before?.run.ids ?? []), ...run.ids])];
+    const when = before && before.at > at ? before.at : at;
+    const timer = setTimeout(() => {
+        const s = scheduled.get(project);
+        scheduled.delete(project);
+        liftLimitPause(project);
+        try {
+            if (s)
+                startRun(s.run.entry, s.run.p, s.run.ids, s.run.mode);
+        }
+        catch {
+            // Started from the board meanwhile: the queue still goes on after it.
+            advance(project);
+        }
+        broadcast({ type: 'board', project });
+    }, when.getTime() - Date.now());
+    timer.unref();
+    scheduled.set(project, { at: when, run: { ...run, ids }, timer });
+}
+/**
+ * A run some of whose items hit the usage limit: the main queue would hit it too, so it pauses,
+ * and those items run again at the reset when the message names a time. The reason, for its
+ * `run` event.
+ */
+function limited(run, result) {
+    const items = result
+        ?.items;
+    const hit = (items ?? []).filter((i) => i.limit_resets !== undefined);
+    if (!hit.length)
+        return '';
+    const project = run.p.name;
+    if (run.mode === 'main') {
+        paused.add(project);
+        limitPaused.add(project);
+    }
+    const resets = hit.find((i) => i.limit_resets)?.limit_resets ?? '';
+    const at = resetAt(resets);
+    if (at)
+        schedule({ ...run, ids: hit.map((i) => i.id), fresh: false }, at);
+    const when = at ? `they resume at ${at.toTimeString().slice(0, 5)}` : 'run them after the reset';
+    const queue = run.mode === 'main' ? ', the queue is paused' : '';
+    return `usage limit${resets ? `, resets ${resets}` : ''}${queue}: ${when}`;
+}
 /** Start the next queued batch when the checkout is free: after a run, or on the operator's resume. */
 function advance(project) {
     if (paused.has(project) || activeRuns(project).some((r) => r.mode === 'main'))
@@ -30,6 +140,7 @@ function advance(project) {
 /** The operator resumes a paused queue (after fixing what stopped it). */
 export function resumeQueue(project) {
     paused.delete(project);
+    limitPaused.delete(project);
     advance(project);
     broadcast({ type: 'board', project });
 }
@@ -52,10 +163,12 @@ export function stalled(ok, result) {
     const items = result?.items ?? [];
     return (items.length > 0 && items.every((i) => /another run works in the main/.test(i.error ?? '')));
 }
-function spawnRun({ entry, p, ids }, mode) {
+function spawnRun(q, mode) {
+    const { entry, p, ids } = q;
     const run = { project: p.name, ids, started: new Date().toISOString(), mode };
     active.add(run);
-    const child = spawn(process.execPath, [entry, 'gcf-harness', 'run', ...ids, '--json'], {
+    const args = [entry, 'gcf-harness', 'run', ...ids, '--json', ...(q.fresh ? ['--fresh'] : [])];
+    const child = spawn(process.execPath, args, {
         cwd: p.path,
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -77,10 +190,17 @@ function spawnRun({ entry, p, ids }, mode) {
         catch {
             // No report: the error says why.
         }
-        const stop = mode === 'main' && queues.get(p.name)?.length && stalled(ok, result);
-        if (stop)
+        // A run of a project removed meanwhile only reports: it pauses and schedules nothing.
+        const kept = !forgotten.has(run);
+        const stop = kept && mode === 'main' && queues.get(p.name)?.length && stalled(ok, result);
+        if (stop) {
             paused.add(p.name);
-        const why = stop ? '\nthe queue is paused: fix the cause, then resume it on the board' : '';
+            limitPaused.delete(p.name);
+        }
+        const note = !kept
+            ? ''
+            : limited(q, result) ||
+                (stop ? 'the queue is paused: fix the cause, then resume it on the board' : '');
         const brief = err && briefError(err);
         broadcast({
             type: 'run',
@@ -88,8 +208,10 @@ function spawnRun({ entry, p, ids }, mode) {
             ids,
             ok,
             result,
-            err: (brief + message + why).trim(),
+            err: (brief + message).trim(),
+            note,
         });
+        // The checkout is free now, for whatever queue the name has: a project added back meanwhile.
         if (mode === 'main')
             advance(p.name);
         broadcast({ type: 'board', project: p.name });
@@ -100,19 +222,29 @@ function spawnRun({ entry, p, ids }, mode) {
 }
 /**
  * Start a batch in the project's run mode, or queue it behind the main run going on. Its end
- * is a `run` event with the harness report, or what went wrong.
+ * is a `run` event with the harness report, or what went wrong. `fresh` starts new agent
+ * sessions where the harness would resume the interrupted ones.
  */
-export function startRun(entry, p, ids, mode = 'worktree') {
+export function startRun(entry, p, ids, mode = 'worktree', fresh = false) {
     // A second click on the same card: the harness would refuse it on its lock, noisily.
     const { active: going, queued } = runsOf(p.name);
     const busy = ids.filter((id) => queued.includes(id) || going.some((r) => r.ids.includes(id)));
     if (busy.length)
         throw new HttpError(409, `already running from this board: ${busy.join(', ')}`);
+    // The operator runs an item the limit stopped before its reset: they know better, so it goes
+    // now, and the limit's pause with it; the rest of the schedule stays.
+    const s = scheduled.get(p.name);
+    if (s?.run.ids.some((id) => ids.includes(id))) {
+        s.run = { ...s.run, ids: s.run.ids.filter((id) => !ids.includes(id)) };
+        if (!s.run.ids.length)
+            cancelResume(p.name);
+        liftLimitPause(p.name);
+    }
     // A paused queue holds a new main run too: it would repeat the failure, and jump the queue.
     if (mode === 'main' && (paused.has(p.name) || going.some((r) => r.mode === 'main'))) {
-        queues.set(p.name, [...(queues.get(p.name) ?? []), { entry, p, ids, mode }]);
+        queues.set(p.name, [...(queues.get(p.name) ?? []), { entry, p, ids, mode, fresh }]);
         broadcast({ type: 'board', project: p.name });
         return { queued: ids };
     }
-    return { started: spawnRun({ entry, p, ids, mode }, mode) };
+    return { started: spawnRun({ entry, p, ids, mode, fresh }, mode) };
 }