gcf-board 0.2.5 → 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

@@ -7,14 +7,14 @@ import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { BOARD_SCHEMA } from '../shared/board.js';
-import { admit, COOKIE, hostAllowed, tokenInUrl } from './auth.js';
+import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
 import { briefError, runCli } from './cli.js';
-import { broadcast, subscribe, watchProject } from './events.js';
-import { followLog, readShown } from './files.js';
+import { broadcast, planRev, subscribe, watchProject } from './events.js';
+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 });
@@ -126,8 +136,15 @@ export function createApp(o) {
             /^\/api\/p\/([^/]+)\/board$/,
             async (_req, res, m) => {
                 const p = await projectOf(m[1]);
-                // The board's own runs ride along: what it started and what waits in its queue.
-                send(res, 200, { ...(await boardOf(p)), runs: runsOf(p.name) });
+                // 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) };
+                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 });
             },
         ],
         [
@@ -135,7 +152,12 @@ export function createApp(o) {
             /^\/api\/p\/([^/]+)\/file$/,
             async (_req, res, m, url) => {
                 const p = await projectOf(m[1]);
-                send(res, 200, { text: await readShown(p.path, url.searchParams.get('path') ?? '') });
+                const rel = url.searchParams.get('path') ?? '';
+                // A plan an item links (`plan:`) may lie anywhere in the project: the core names it.
+                const linked = !shownShape(rel) &&
+                    // A board the core cannot read links nothing: the path is refused, not a 500.
+                    (await boardOf(p).catch(() => ({ items: [] }))).items.some((i) => i.plan_file === rel);
+                send(res, 200, { text: await readShown(p.path, rel, linked) });
             },
         ],
         [
@@ -184,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));
             },
         ],
         [
@@ -217,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-]*)$/,
@@ -234,7 +266,7 @@ export function createApp(o) {
         const visit = req.method === 'GET' && !url.pathname.startsWith('/api/');
         if (visit && hostAllowed(req, o.port) && tokenInUrl(url, o.token)) {
             res.writeHead(302, {
-                'set-cookie': `${COOKIE}=${session}; HttpOnly; SameSite=Strict; Path=/`,
+                'set-cookie': `${cookieName(o.port)}=${session}; HttpOnly; SameSite=Strict; Path=/`,
                 // Always the root: a path like `//elsewhere` would send the browser off the board.
                 location: '/',
             });

package/dist/server/auth.js

@@ -8,7 +8,9 @@ import { mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { writeAtomic } from './atomic.js';
 import { homeDir } from './registry.js';
-export const COOKIE = 'gcf_board';
+// A browser keeps one cookie per name for all of 127.0.0.1: the port in the name lets two boards
+// on two ports stay signed in side by side.
+export const cookieName = (port) => `gcf_board_${port}`;
 // An empty or short token would let everyone in: such a file is replaced.
 const STRONG = /^[0-9a-f]{48}$/;
 /** The token of this machine's board: made once, kept in `~/.gcf/board-token`. */
@@ -23,10 +25,10 @@ export async function boardToken() {
     return token;
 }
 const same = (a, b) => b.length > 0 && a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
-function cookieOf(req) {
+function cookieOf(req, name) {
     for (const part of (req.headers.cookie ?? '').split(';')) {
         const [k, ...v] = part.trim().split('=');
-        if (k === COOKIE)
+        if (k === name)
             return v.join('=');
     }
     return '';
@@ -42,7 +44,7 @@ export function admit(req, port, token) {
     const origin = req.headers.origin;
     if (write && !(origin && hosts.some((h) => origin === `http://${h}`)))
         return { ok: false, status: 403, message: 'a change comes from the board page only' };
-    if (!same(cookieOf(req), token))
+    if (!same(cookieOf(req, cookieName(port)), token))
         return { ok: false, status: 401, message: 'open the URL gcf-board printed at start' };
     return { ok: true };
 }

package/dist/server/desktop.js

@@ -11,11 +11,15 @@ export function openInBrowser(url) {
         : process.platform === 'darwin'
             ? ['open', [url]]
             : ['xdg-open', [url]];
+    // No browser to open: the operator opens the printed URL. A missing opener fails as an event,
+    // which unheard would end the server.
     try {
-        spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+        spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true })
+            .on('error', () => { })
+            .unref();
     }
     catch {
-        // No browser to open: the operator opens the printed URL.
+        // Refused at once: the same.
     }
 }
 /** A PowerShell single-quoted string: a quote inside is doubled. */

package/dist/server/events.js

@@ -1,6 +1,6 @@
-// Server-sent events: a project's `gcf/` or its run locks changed, a run the board started ended.
-// The page reads the board again on each one; the event carries no state of its own.
-import { watch, watchFile, unwatchFile } from 'node:fs';
+// Server-sent events: a project's `gcf/`, its plans or its run marks changed, a run the board
+// started ended. The page reads the board again on each one; the event carries no state of its own.
+import { readdirSync, readFileSync, statSync, watch } from 'node:fs';
 import path from 'node:path';
 const clients = new Set();
 /** Open an event stream on `res`. */
@@ -25,10 +25,64 @@ export function broadcast(event) {
     for (const c of clients)
         c.write(line);
 }
+// The core's SESSION_TTL_MS (session-mark.js): a mark nobody refreshed for this long is a session
+// 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;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+};
+/**
+ * What makes items `running` in a runs directory: its entries, whether each lock's process
+ * 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;
+    try {
+        names = readdirSync(dir).sort();
+    }
+    catch {
+        return '';
+    }
+    return names
+        .map((n) => {
+        const file = path.join(dir, n);
+        try {
+            if (n.endsWith('.lock'))
+                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.
+        }
+        return n;
+    })
+        .join('\n');
+}
+// Each project's plan writes, counted: a plan's text can change while its checkbox progress stays,
+// so the page reads an open plan again when the count moves.
+const planRevs = new Map();
+export const planRev = (project) => planRevs.get(project) ?? 0;
 /**
- * Watch a project: `gcf/` (every move writes there) and `.gcf-session/runs` (a run's lock comes
- * and goes). The runs directory may not exist yet, so it is polled, not watched. Bursts of
- * writes make one event. Returns the stop.
+ * Watch a project: `gcf/` (every move writes there), `.ai-factory/plans` (a plan is written and
+ * edited) and `.gcf-session/runs` (a run's lock or session mark comes, goes or goes stale). The
+ * runs directory may not exist yet, so it is polled, not watched. Bursts of writes make one
+ * event. Returns the stop.
  */
 export function watchProject(p, debounceMs = 300) {
     let timer = null;
@@ -37,19 +91,38 @@ export function watchProject(p, debounceMs = 300) {
             clearTimeout(timer);
         timer = setTimeout(() => broadcast({ type: 'board', project: p.name }), debounceMs);
     };
-    let gcf = null;
-    try {
-        gcf = watch(path.join(p.path, 'gcf'), { recursive: true }, fire);
-        gcf.on('error', () => gcf?.close());
-    }
-    catch {
-        // gcf/ is gone: the board read shows the error, nothing to watch.
-    }
+    const watchers = [];
+    const watchDir = (dir, onChange) => {
+        try {
+            const w = watch(dir, { recursive: true }, (_e, file) => onChange(file));
+            w.on('error', () => w.close());
+            watchers.push(w);
+        }
+        catch {
+            // Not there: the board read shows what is missing.
+        }
+    };
+    watchDir(path.join(p.path, 'gcf'), fire);
+    // shortcut: a plan an item links outside .ai-factory/plans shows its new text only when its
+    // checkbox count moves; watch those files too if operators edit such plans by hand.
+    watchDir(path.join(p.path, '.ai-factory'), (file) => {
+        if (!/^plans[\\/]/.test(file ?? ''))
+            return;
+        planRevs.set(p.name, planRev(p.name) + 1);
+        fire();
+    });
     const runs = path.join(p.path, '.gcf-session', 'runs');
-    watchFile(runs, { interval: 1500 }, fire);
+    let last = runsState(runs);
+    const poll = setInterval(() => {
+        const now = runsState(runs);
+        if (now !== last)
+            fire();
+        last = now;
+    }, 1500);
     return () => {
-        gcf?.close();
-        unwatchFile(runs, fire);
+        for (const w of watchers)
+            w.close();
+        clearInterval(poll);
         if (timer)
             clearTimeout(timer);
     };

package/dist/server/files.js

@@ -1,5 +1,5 @@
-// The files a board shows: an item, its plan, its run log. Only those shapes, only inside the
-// project, symlinks resolved: the API is not a way to read the disk.
+// The files a board shows: an item, its plan, its run log. Only those shapes (or a plan an item
+// links), only inside the project, symlinks resolved: the API is not a way to read the disk.
 import { realpath, readFile, stat, open } from 'node:fs/promises';
 import path from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
@@ -11,9 +11,11 @@ const SHOWN = [
     /^\.gcf-session\/runs\/[\w.-]+\.log$/,
 ];
 const MAX = 1024 * 1024;
-/** The absolute path of a shown file, or a 403. */
-export async function shownFile(root, rel) {
-    if (!SHOWN.some((r) => r.test(rel)) || rel.split('/').includes('..'))
+/** Whether `rel` has a shape the board shows without asking the core. */
+export const shownShape = (rel) => SHOWN.some((r) => r.test(rel));
+/** The absolute path of a shown file (or a plan an item links, `linked`), or a 403. */
+export async function shownFile(root, rel, linked = false) {
+    if (!(linked || shownShape(rel)) || rel.split('/').includes('..'))
         throw new HttpError(403, `${rel} is not a file the board shows`);
     const file = path.join(root, rel);
     const real = await realpath(file).catch(() => {
@@ -25,8 +27,8 @@ export async function shownFile(root, rel) {
     return real;
 }
 /** The text of a shown file; a large one is cut to its last megabyte. */
-export async function readShown(root, rel) {
-    const file = await shownFile(root, rel);
+export async function readShown(root, rel, linked = false) {
+    const file = await shownFile(root, rel, linked);
     const { size } = await stat(file);
     if (size <= MAX)
         return readFile(file, 'utf8');

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,18 +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(', ')}`);
-    if (mode === 'main' && going.some((r) => r.mode === 'main')) {
-        queues.set(p.name, [...(queues.get(p.name) ?? []), { entry, p, ids, mode }]);
+    // 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, 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) };
 }