@voidlabs.gg/voidshift-agents 0.6.0 → 0.8.0

package/dist/runner.js

@@ -2,16 +2,22 @@ import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, needsPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
-import { agentsDir, hasWork, isCardTrigger, resolveProject, resolveStep, stepId, stepIdLabel, workspaceContext, workspaceOf } from "./config.js";
+import { DEFAULTS, agentsDir, hasWork, isCardTrigger, resolveProject, resolveStep, stepId, stepIdLabel, workspaceContext, workspaceOf } from "./config.js";
 import { lastDue, parseCron } from "./cron.js";
-import { runAgent, stopAgents } from "./engine.js";
-import { commitsAhead, enforceCommitPolicy, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
+import { runAgent, runCommand, stopAgents } from "./engine.js";
+import { commitsAhead, enforceCommitPolicy, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, removeWorktree, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
 import { noTracker } from "./tracker.js";
 import { recall, syncMemory, vaultPath } from "./memory.js";
 import { claudeSettingsFile, readRules, rulesSection } from "./profile.js";
-import { acquireWorkspace, clearCurrent, heldByOther, isPaused, liveRuns, readCurrent, readPending, releaseWorkspace, writeCurrent, writePending, writeRun, writeWorkspace, readCronState, writeCronState } from "./state.js";
+import { acquireWorkspace, addUsage, clearCurrent, closeStale, heldByOther, isPaused, liveRuns, queueHandoffs, readCurrent, readHandoffs, readPending, readWindow, releaseWorkspace, takeHandoff, writeHandoffs, writeCurrent, writePending, writeRun, writeWorkspace, readCronState, writeCronState } from "./state.js";
+import { WINDOW_MS, clock, refreshWindow, windowHold, windowStale } from "./usage.js";
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
 class Park extends Error {
+    kind;
+    constructor(message, kind = 'parked') {
+        super(message);
+        this.kind = kind;
+    }
 }
 function withLabels(card, drop, add) {
     return [...new Set([...card.labels.filter((l) => !drop(l)), ...add])];
@@ -21,7 +27,9 @@ const UNATTENDED = `# Running unattended
 You are one step in a workflow. Nobody can answer questions and the
 tracker connection is not available: the card and any plan are included above.
 Do not write plan files; return your output as your final message. Make the
-call the code supports and state it.`;
+call the code supports and state it. If the environment stops you (a missing
+command, denied access, no network), name the command and the error in your
+final message, and in a Plan or Dev step end with \`RESULT: BLOCKED\`.`;
 // Agents keep the memory vault the way you do: durable learnings become notes.
 const memoryNote = (vault) => `# Memory
 
@@ -34,6 +42,10 @@ rather than adding a second one. Skip it when nothing durable came up.`;
 export function summarize(output) {
     return output.split('\n').map((l) => l.trim()).filter(Boolean).slice(0, 3).join(' ').slice(0, 300);
 }
+// The last non-empty line of what a command printed, for run.json.
+export function lastLine(output) {
+    return output.split('\n').map((l) => l.trim()).filter(Boolean).at(-1)?.slice(0, 300) ?? '';
+}
 // The run in progress, so a cancel signal can mark it.
 let active = null;
 const isVerdict = (d) => d.output === 'verdict';
@@ -55,6 +67,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     // Write back settings apply to card runs; a scheduled run has nothing to write to.
     const writeBack = isCardTrigger(trigger) ? (workflow.writeBack ?? {}) : {};
     const labelsOn = writeBack.labels !== false;
+    const cronRun = trigger.source === 'cron';
     const startedAt = new Date().toISOString();
     const workspace = workspaceOf(project);
     const record = { card: card.identifier, title: card.title, url: card.url || undefined, workflow: workflowName, trigger: label || (trigger.source === 'cron' ? trigger.schedule : ''), source: trigger.source, steps: [], outcome: 'running', workspace, startedAt };
@@ -73,11 +86,11 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         save();
         return rec;
     };
-    const end = (rec, result, output, logFile) => {
+    const end = (rec, result, output, logFile, command = false) => {
         rec.endedAt = new Date().toISOString();
         rec.result = result;
         if (output !== undefined)
-            rec.summary = summarize(output);
+            rec.summary = command ? lastLine(output) : summarize(output);
         if (logFile)
             rec.log = basename(logFile);
         save();
@@ -111,8 +124,20 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         await linear.comment(card, `${PLAN_HEADING}\n\n${planToPost}`);
         planToPost = null;
     };
-    async function park(reason) {
-        say(`parked: ${reason}`);
+    const ping = async (kind, reason) => {
+        if (!rc.notify)
+            return;
+        try {
+            await rc.notify({ kind, card: card.identifier, title: card.title, workflow: workflowName, url: card.url || undefined, prUrl: record.prUrl, reason });
+        }
+        catch (err) {
+            say(`discord: ${err.message}`);
+        }
+    };
+    async function park(reason, kind = 'parked') {
+        say(`${kind === 'failed' ? 'failed' : 'parked'}: ${reason}`);
+        // The outcome is on disk before any tracker call, so a hung or failed write never loses it.
+        const outcome = done(kind, reason);
         const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${label}\` again to retry.`;
         const add = labelsOn ? [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])] : [];
         let commented = false;
@@ -123,14 +148,17 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             await endLabels(LABELS.parked, loops || undefined);
         }
         catch (err) {
-            if (!isCardTrigger(trigger))
-                return done('parked', reason);
-            say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
-            // An empty comment is skipped on retry, so it is not posted twice.
-            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
+            if (isCardTrigger(trigger)) {
+                say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
+                // An empty comment is skipped on retry, so it is not posted twice.
+                writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
+            }
         }
-        return done('parked', reason);
+        await ping(kind, reason);
+        return outcome;
     }
+    // Set once a worktree exists, so a scheduled run can remove it at the end.
+    let worktreeMade = '';
     try {
         if (!existsSync(join(project.path, '.git')))
             throw new Park(`The project folder ${project.path} is not a git repository on this Mac.`);
@@ -138,6 +166,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         const from = opts.from ? steps.findIndex((d) => d.id === opts.from) : 0;
         if (from < 0)
             throw new Park(`Workflow ${workflowName} has no ${stepIdLabel(opts.from)} step.`);
+        // Command steps need no branch of their own: a run of only those works in the project folder.
+        const commandOnly = steps.slice(from).every((d) => d.command);
         // A scheduled run has no card to plan on, so its task is the plan unless a Plan step writes one.
         let plan = isCardTrigger(trigger) ? latestPlan(await linear.comments(card.identifier)) : card.description ?? null;
         if (!plan && needsPlan(steps, from)) {
@@ -161,15 +191,53 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             say(pulled);
         const context = workspaceContext(config, workspace);
         const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), context ? `# Workspace\n\n${context}` : '', vault ? memoryNote(vault) : '', rules].filter(Boolean).join('\n\n');
-        const worktree = join(agentsDir(rc.configDir), 'worktrees', card.identifier);
-        ensureWorktree(project.path, worktree, card.branchName, base);
-        say(`working in ${worktree} on ${card.branchName}`);
+        const worktree = commandOnly ? project.path : join(agentsDir(rc.configDir), 'worktrees', card.identifier);
+        if (!commandOnly) {
+            ensureWorktree(project.path, worktree, card.branchName, base);
+            worktreeMade = worktree;
+            say(`working in ${worktree} on ${card.branchName}`);
+        }
         const findings = new Map();
         const runs = { plan: 0, dev: 0 };
         let prUrl = '';
         let logs = 0;
         const planText = () => plan ?? '(No plan was posted on this card. Check the work against the card itself.)';
         const logFile = (name) => join(runDir, `${String(logs++).padStart(2, '0')}-${name}.log`);
+        // Every agent step goes through here. A read step's stray edits are thrown
+        // away, so a later Dev step never commits them, and an agent process that
+        // fails ends the run as failed with its own error.
+        async function agent(def, rec, log, prompt) {
+            const r = def.command
+                ? await runCommand({ command: def.command, cwd: worktree, logFile: log, timeoutMs: def.timeoutMs, env: { VSF_CARD: card.identifier, VSF_RUN_DIR: runDir, VSF_WORKFLOW: workflowName } })
+                : await runAgent({ engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs, platform: rc.platform, prompt });
+            // Saved with the step's end, failed or not.
+            if (r.usage) {
+                rec.usage = r.usage;
+                record.usage = addUsage(record.usage, r.usage);
+            }
+            if (!def.command && (!def.write || def.builtin === 'vs-qa'))
+                resetWorktree(worktree);
+            if (!r.ok) {
+                end(rec, 'failed', r.output, log, !!def.command);
+                throw new Park(`The ${def.label} step failed: ${r.error}. Log: ${basename(log)}`, 'failed');
+            }
+            return r;
+        }
+        // Cards a finished step names with HANDOFF lines go to the workflow it hands to.
+        async function handOff(def, rec, output) {
+            if (!def.handoff)
+                return;
+            if (!config.workflows[def.handoff]) {
+                say(`cannot hand cards to ${def.handoff}: no such workflow`);
+                return;
+            }
+            const cards = [...new Set([...output.matchAll(/^\s*HANDOFF:\s*([A-Za-z][A-Za-z0-9]*-\d+)\s*$/gm)].map((m) => m[1].toUpperCase()))];
+            queueHandoffs(rc.configDir, def.handoff, cards, card.identifier);
+            rec.handoffs = cards;
+            save();
+            if (cards.length)
+                say(`handed ${cards.join(', ')} to ${def.handoff}`);
+        }
         async function check(def, round) {
             const label = def.label;
             const rec = begin(def);
@@ -203,14 +271,10 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 }
             }
             const log = logFile(def.id);
-            const r = await runAgent({
-                engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
-                prompt: buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
-            });
-            if (def.builtin === 'vs-qa')
-                resetWorktree(worktree);
+            const r = await agent(def, rec, log, buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }));
             const verdict = parseVerdict(r.output);
             end(rec, verdict, r.output, log);
+            await handOff(def, rec, r.output);
             return { step: label, verdict, report: r.output };
         }
         let i = from;
@@ -255,14 +319,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 await stage(stageOf(def), runs.plan + 1);
                 const rec = begin(def);
                 const log = logFile(def.builtin ? 'plan' : def.id);
-                const r = await runAgent({
-                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
-                    prompt: buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none yet, you are writing it)', base, round: runs.plan + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
-                });
+                const r = await agent(def, rec, log, buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none yet, you are writing it)', base, round: runs.plan + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }));
                 const result = parseDevResult(r.output);
                 end(rec, result.status === 'blocked' ? 'blocked' : 'done', r.output, log);
                 if (result.status === 'blocked')
                     throw new Park(`The plan agent stopped: ${result.reason}`);
+                await handOff(def, rec, r.output);
                 plan = planBody(r.output);
                 planToPost = plan;
                 runs.plan++;
@@ -280,14 +342,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 const rec = begin(def);
                 const log = logFile(def.builtin ? 'dev' : def.id);
                 const before = headSha(worktree);
-                const dev = await runAgent({
-                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
-                    prompt: buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
-                });
+                const dev = await agent(def, rec, log, buildPrompt({ skill: def.prompt(), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }));
                 const result = parseDevResult(dev.output);
                 end(rec, result.status === 'blocked' ? 'blocked' : 'done', dev.output, log);
                 if (result.status === 'blocked')
                     throw new Park(`The dev agent stopped: ${result.reason}`);
+                await handOff(def, rec, dev.output);
                 if (commitsAhead(worktree, base) === 0)
                     throw new Park('The dev agent made no commits.');
                 // A round sent back with findings must change something, or QA would
@@ -309,13 +369,9 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 await stage(stageOf(def), loops || undefined);
                 const rec = begin(def);
                 const log = logFile(def.id);
-                const r = await runAgent({
-                    engine: def.engine, model: def.model, cwd: worktree, vault, settingsFile, write: def.write, logFile: log, timeoutMs: def.timeoutMs,
-                    prompt: buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none)', base, round: loops || 1, extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
-                });
-                end(rec, r.ok ? 'done' : 'failed', r.output, log);
-                if (!r.ok)
-                    throw new Park(`The ${def.label} step failed or timed out.`);
+                const r = await agent(def, rec, log, buildPrompt({ skill: def.prompt(), card, plan: plan ?? '(none)', base, round: loops || 1, extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }));
+                end(rec, 'done', r.output, log, !!def.command);
+                await handOff(def, rec, r.output);
             }
             findings.delete(i);
             i++;
@@ -330,21 +386,27 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         if (writeBack.comment !== false) {
             await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${!moved ? `\n\n(No "${state}" state on this team, so the card was not moved.)` : ''}`);
         }
-        say('verified');
-        return done('verified');
+        say(cronRun ? 'done' : 'verified');
+        done(cronRun ? 'done' : 'verified');
     }
     catch (err) {
         if (err instanceof Park)
-            return park(err.message);
-        return park(`Something went wrong: ${err.message}`);
+            return park(err.message, err.kind);
+        return park(`Something went wrong: ${err.message}`, 'failed');
     }
     finally {
         active = null;
+        // A scheduled run that opened no pull request leaves no worktree or branch behind.
+        if (cronRun && worktreeMade && !record.prUrl)
+            removeWorktree(project.path, worktreeMade, card.branchName);
         // Share whatever notes the agents wrote, whatever the outcome.
         const shared = syncMemory(rc.selfCommand, rc.configDir);
         if (shared)
             say(shared);
     }
+    // Outside the try, so a ping that throws can never park a verified run.
+    await ping(record.prUrl ? 'ready' : 'passed');
+    return cronRun ? 'done' : 'verified';
 }
 // The workspace whose queue a job waits in. A workflow whose project is
 // missing still queues somewhere, so its run can say what is wrong.
@@ -364,6 +426,8 @@ export function cronCard(workflow, task, at) {
         labels: [],
     };
 }
+// How long a handed card may wait for its run to start.
+const HANDOFF_MAX_MS = 24 * 60 * 60_000;
 const cronKey = (workflow, schedule) => `${workflow} ${schedule}`;
 // Jobs waiting on the workflows' triggers, in workflow order, at most one per
 // workspace and none in a busy one: a card carrying a trigger label, or a
@@ -400,7 +464,64 @@ export async function findJobs(rc, q = {}) {
         out.push({ ...job, workspace });
         return out.length >= limit;
     };
+    // Cards other workflows handed over, in the order they were queued. They
+    // need no label. Stale or unknown ones are dropped; one whose tracker cannot
+    // be read stays queued. True once the limit is reached.
+    const takeHandoffs = async () => {
+        const queue = readHandoffs(rc.configDir);
+        const keep = [];
+        let full = false;
+        for (const h of queue) {
+            if (q.workflow && h.workflow !== q.workflow) {
+                keep.push(h);
+                continue;
+            }
+            if (now.getTime() - new Date(h.at).getTime() > HANDOFF_MAX_MS) {
+                rc.log(`Dropped the handoff of ${h.card} to ${h.workflow}: it waited more than 24 hours.`);
+                continue;
+            }
+            const workflow = rc.config.workflows[h.workflow];
+            if (!workflow) {
+                rc.log(`Dropped the handoff of ${h.card} to ${h.workflow}: no such workflow.`);
+                continue;
+            }
+            const team = h.card.split('-')[0].toUpperCase();
+            const triggers = workflow.triggers.filter(isCardTrigger).filter((t) => t.team === team);
+            if (!triggers.length) {
+                rc.log(`Dropped the handoff of ${h.card} to ${h.workflow}: it has no trigger for team ${team}.`);
+                continue;
+            }
+            keep.push(h);
+            if (full)
+                continue;
+            let found = null;
+            let failure = '';
+            for (const trigger of triggers) {
+                try {
+                    found = { card: await rc.trackers(trigger.source).card(h.card), trigger };
+                    break;
+                }
+                catch (err) {
+                    failure = err.message;
+                }
+            }
+            if (!found) {
+                rc.log(`Could not read ${h.card} for its handoff (${failure}). Trying again next minute.`);
+                continue;
+            }
+            const workspace = jobWorkspace(rc.config, workflow, found.card);
+            if (taken.has(workspace) || q.skip?.has(h.card) || out.some((j) => j.card.identifier === h.card))
+                continue;
+            if (take({ card: found.card, trigger: found.trigger, workflow: h.workflow }, workspace))
+                full = true;
+        }
+        if (keep.length !== queue.length)
+            writeHandoffs(rc.configDir, keep);
+        return full;
+    };
     try {
+        if (!q.only && !q.schedule && (await takeHandoffs()))
+            return out;
         for (const [name, workflow] of workflows) {
             for (const trigger of workflow.triggers) {
                 if (!isCardTrigger(trigger)) {
@@ -523,6 +644,22 @@ function queueCancel(configDir, cardId, comment, source = 'linear') {
         // nothing more to do
     }
 }
+// The card runs that take a slot under the cap. A lock with no card is a
+// check, not a run.
+const cardRuns = (configDir) => liveRuns(configDir).filter((c) => c.card && c.pid !== process.pid);
+// Why no new run may start now: the 5 hour window is held, or the cap is
+// reached. Null when one may.
+export function gateReason(rc, now = new Date()) {
+    const w = readWindow(rc.configDir);
+    const until = windowHold(w, rc.config.pauseAt ?? DEFAULTS.pauseAt, now);
+    if (until)
+        return `The 5 hour window is at ${Math.round(w.utilization)}%, so no new run starts until ${clock(until)}. Running cards finish.`;
+    const max = rc.config.maxRuns ?? 0;
+    const running = max > 0 ? cardRuns(rc.configDir).length : 0;
+    if (max > 0 && running >= max)
+        return `${running} of ${max} runs are going, so no new one starts until one finishes.`;
+    return null;
+}
 // Runs one job in its workspace's queue: a pinned card, a workflow's schedule,
 // or the first job waiting in a free workspace. The workspace lock keeps two
 // runs from working in one workspace at once. `child` is a run the dispatcher
@@ -570,6 +707,12 @@ export async function tick(rc, only, opts = {}) {
             await flushPending(rc);
         if (!only && isPaused(rc.configDir))
             return 0;
+        // A named card goes ahead of the cap and the hold, as it does a pause.
+        const gate = !only && !opts.child ? gateReason(rc) : null;
+        if (gate) {
+            rc.log(gate);
+            return 0;
+        }
         let job;
         try {
             const busy = only ? undefined : new Set(liveRuns(rc.configDir).filter((c) => c.pid !== process.pid).map((c) => workspaceOf(c)));
@@ -600,8 +743,11 @@ export async function tick(rc, only, opts = {}) {
             return 1;
         }
         held = job.workspace;
+        // A handed card leaves the queue only once its run has started.
+        if (isCardTrigger(job.trigger))
+            takeHandoff(rc.configDir, job.card.identifier, job.workflow);
         const outcome = await runCard(job.card, job.trigger, job.workflow, workflow, resolved.project, rc, { from: opts.from });
-        return outcome === 'verified' ? 0 : 1;
+        return outcome === 'verified' || outcome === 'done' ? 0 : 1;
     }
     catch (err) {
         rc.log(`Error: ${err.message}`);
@@ -622,6 +768,7 @@ const realDeps = (rc) => ({
         return spawn(bin, [...rest, 'agents', 'tick', ...args], { stdio: 'inherit' });
     },
     waitMs: 60_000,
+    window: () => refreshWindow(rc.configDir),
 });
 // The background runner. The service starts a new pass only once the last one
 // ended, so this pass stays up while cards run: it starts one child process
@@ -655,15 +802,66 @@ export async function dispatch(rc, over = {}) {
     };
     process.on('SIGTERM', onSignal);
     process.on('SIGINT', onSignal);
+    // The window is read once at the start when the last reading is old, then
+    // every 5 minutes while runs go on, one read at a time.
+    let reading = false;
+    const readWindowNow = async () => {
+        if (reading)
+            return;
+        reading = true;
+        try {
+            await deps.window();
+        }
+        catch {
+            // window.json keeps the last reading
+        }
+        finally {
+            reading = false;
+        }
+    };
+    let timer;
+    let wasHeld = false;
     try {
+        if (windowStale(readWindow(rc.configDir)))
+            await readWindowNow();
+        timer = setInterval(() => void readWindowNow(), WINDOW_MS);
+        timer.unref();
         for (;;) {
+            // Runs whose process ended without an outcome are closed as failed.
+            try {
+                for (const card of closeStale(rc.configDir, liveRuns(rc.configDir)))
+                    rc.log(`${card} failed: the run stopped without finishing.`);
+            }
+            catch {
+                // looked at again next pass
+            }
             if (deps.reload)
                 rc = { ...rc, config: deps.reload() };
             await flushPending(rc);
-            if (!isPaused(rc.configDir)) {
+            const paused = isPaused(rc.configDir);
+            const w = readWindow(rc.configDir);
+            const heldUntil = windowHold(w, rc.config.pauseAt ?? DEFAULTS.pauseAt, new Date());
+            if (heldUntil && !wasHeld)
+                rc.log(`The 5 hour window is at ${Math.round(w.utilization)}%, so no new run starts until ${clock(heldUntil)}. Running cards finish.`);
+            if (!heldUntil && wasHeld)
+                rc.log('The 5 hour window reset, so new runs start again.');
+            wasHeld = !!heldUntil;
+            if (rc.summary) {
+                try {
+                    await rc.summary(paused);
+                }
+                catch (err) {
+                    rc.log(`discord: ${err.message}`);
+                }
+            }
+            // Only card runs take a slot under the cap.
+            const running = new Set([...children.keys(), ...cardRuns(rc.configDir).map((c) => workspaceOf(c))]);
+            const max = rc.config.maxRuns ?? 0;
+            const limit = max > 0 ? max - running.size : Infinity;
+            if (!paused && !heldUntil && limit > 0) {
                 const busy = new Set([...children.keys(), ...liveRuns(rc.configDir).map((c) => workspaceOf(c))]);
                 const skip = new Set([...started].filter(([, at]) => Date.now() - at < deps.waitMs).map(([id]) => id));
-                for (const job of await findJobs(rc, { busy, skip })) {
+                for (const job of await findJobs(rc, { busy, skip, limit })) {
                     started.set(job.card.identifier, Date.now());
                     rc.log(`${job.card.identifier} starts ${job.workflow} in workspace ${job.workspace}.`);
                     const child = deps.start(jobArgs(job));
@@ -698,6 +896,7 @@ export async function dispatch(rc, over = {}) {
         return 1;
     }
     finally {
+        clearInterval(timer);
         process.off('SIGTERM', onSignal);
         process.off('SIGINT', onSignal);
         clearCurrent(rc.configDir);

package/dist/secrets.d.ts

@@ -5,5 +5,6 @@ export declare function readSecretsFile(path: string): Record<string, string>;
 export declare function writeSecretsFile(path: string, values: Record<string, string>): void;
 export declare function readSecret(configDir: string, name: string, platform?: NodeJS.Platform): string | null;
 export declare function storeSecret(configDir: string, name: string, value: string, platform?: NodeJS.Platform): boolean;
+export declare function removeSecret(configDir: string, name: string, platform?: NodeJS.Platform): boolean;
 export declare const readLinearKey: (configDir: string) => string | null;
 export declare const storeLinearKey: (configDir: string, key: string) => boolean;

package/dist/secrets.js

@@ -40,7 +40,7 @@ export function readSecret(configDir, name, platform = process.platform) {
     return readSecretsFile(secretsPath(configDir))[name] || null;
 }
 export function storeSecret(configDir, name, value, platform = process.platform) {
-    if (!SAFE_VALUE.test(value) || !/^[a-z-]+$/.test(name))
+    if (!SAFE_VALUE.test(value) || !/^[a-z0-9-]+$/.test(name))
         return false;
     if (platform === 'darwin') {
         // On stdin through `security -i`, so the value never appears in a process list.
@@ -51,5 +51,16 @@ export function storeSecret(configDir, name, value, platform = process.platform)
     writeSecretsFile(path, { ...readSecretsFile(path), [name]: value });
     return true;
 }
+export function removeSecret(configDir, name, platform = process.platform) {
+    if (platform === 'darwin') {
+        // 44 is the Keychain's "not found": already gone counts as removed.
+        const status = spawnSync('/usr/bin/security', ['delete-generic-password', '-s', service(name)], { encoding: 'utf8' }).status;
+        return status === 0 || status === 44;
+    }
+    const path = secretsPath(configDir);
+    const { [name]: _gone, ...rest } = readSecretsFile(path);
+    writeSecretsFile(path, rest);
+    return true;
+}
 export const readLinearKey = (configDir) => readSecret(configDir, 'linear');
 export const storeLinearKey = (configDir, key) => looksLikeLinearKey(key) && storeSecret(configDir, 'linear', key);

package/dist/service.js

@@ -13,6 +13,6 @@ const linux = {
     start: (home, program, logPath) => systemd.startRunner(home, program, launchd.runnerEnv(), logPath),
     stop: systemd.stopRunner,
     programArgs: systemd.programArgs,
-    checks: () => [systemd.lingerCheck()],
+    checks: () => [systemd.lingerCheck(), systemd.sudoCheck()],
 };
 export const runnerService = (platform = process.platform) => (platform === 'darwin' ? mac : linux);

package/dist/state.d.ts

@@ -29,6 +29,14 @@ export declare const liveRuns: (configDir: string) => Current[];
 export declare const clearLock: (configDir: string, c: Current) => void;
 export declare const isPaused: (configDir: string) => boolean;
 export declare function setPaused(configDir: string, paused: boolean): void;
+export interface Window {
+    checkedAt: string;
+    utilization?: number;
+    resetsAt?: string;
+    error?: string;
+}
+export declare function readWindow(configDir: string): Window | null;
+export declare function writeWindow(configDir: string, w: Window): void;
 export interface Pending {
     card: string;
     comment: string;
@@ -39,7 +47,19 @@ export interface Pending {
 }
 export declare function readPending(configDir: string): Pending[];
 export declare function writePending(configDir: string, pending: Pending[]): void;
-export type Outcome = 'running' | 'verified' | 'changes' | 'parked' | 'cancelled';
+export type Outcome = 'running' | 'verified' | 'done' | 'changes' | 'parked' | 'failed' | 'cancelled';
+export interface Usage {
+    input?: number;
+    output?: number;
+    cached?: number;
+    costUsd?: number;
+    model?: string;
+}
+export type RunUsage = Omit<Usage, 'model'> & {
+    models?: string[];
+};
+export declare function addUsage(total: RunUsage | undefined, step: Usage): RunUsage;
+export declare function usageText(u: Usage | RunUsage | undefined): string;
 export interface StepRecord {
     step: string;
     label: string;
@@ -48,6 +68,8 @@ export interface StepRecord {
     result?: string;
     summary?: string;
     log?: string;
+    usage?: Usage;
+    handoffs?: string[];
 }
 export interface RunRecord {
     card: string;
@@ -63,6 +85,7 @@ export interface RunRecord {
     workspace?: string;
     startedAt: string;
     endedAt?: string;
+    usage?: RunUsage;
 }
 export declare const runsDir: (configDir: string) => string;
 export declare function writeRun(runDir: string, run: RunRecord): void;
@@ -76,3 +99,19 @@ export interface RunEntry {
 export declare function listRuns(configDir: string, card?: string): RunEntry[];
 export declare function readCronState(configDir: string): Record<string, string>;
 export declare function writeCronState(configDir: string, state: Record<string, string>): void;
+export interface Handoff {
+    card: string;
+    workflow: string;
+    from: string;
+    at: string;
+}
+export declare function readHandoffs(configDir: string): Handoff[];
+export declare function writeHandoffs(configDir: string, handoffs: Handoff[]): void;
+export declare function queueHandoffs(configDir: string, workflow: string, cards: string[], from: string, now?: Date): Handoff[];
+export declare function takeHandoff(configDir: string, card: string, workflow: string): void;
+export declare function lastSeen(run: RunRecord): string;
+export declare const STOPPED_REASON = "The run stopped without finishing: its process ended before it could record an outcome.";
+export declare function closeStale(configDir: string, live: {
+    runDir?: string;
+    card?: string;
+}[]): string[];