@voidlabs.gg/voidshift-agents 0.7.0 → 0.8.0

package/dist/manage.js

@@ -29,13 +29,25 @@ export function validateStep(step, config, dir) {
         problems.push(`${name} prompt must be a file name.`);
     if (step.skill !== undefined && typeof step.skill !== 'string')
         problems.push(`${name} skill must be a name or a folder.`);
-    const sources = [step.skill, step.prompt].filter((v) => v !== undefined).length;
+    if (step.run !== undefined && (typeof step.run !== 'string' || !step.run.trim()))
+        problems.push(`${name} run must be a command.`);
+    if (step.handoff !== undefined) {
+        if (typeof step.handoff !== 'string' || !step.handoff.trim())
+            problems.push(`${name} handoff must be a workflow name.`);
+        else if (config.workflows && !Object.hasOwn(config.workflows, step.handoff))
+            problems.push(`${name} hands cards to ${step.handoff}, which is not a workflow.`);
+    }
+    const sources = [step.skill, step.prompt, step.run].filter((v) => v !== undefined).length;
     if (step.output === 'publish') {
         if (sources)
-            problems.push(`${name} only pushes the branch, so it takes no skill or prompt.`);
+            problems.push(`${name} only pushes the branch, so it takes no skill, prompt or run.`);
     }
     else if (sources !== 1)
-        problems.push(`${name} needs exactly one of skill or prompt.`);
+        problems.push(`${name} needs exactly one of skill, prompt or run.`);
+    else if (step.run !== undefined) {
+        if (step.output !== 'none')
+            problems.push(`${name} runs a command, so its output must be none.`);
+    }
     else if (typeof (step.prompt ?? step.skill) === 'string') {
         const file = stepFile(step, dir);
         if (!file || !existsSync(file))
@@ -121,8 +133,8 @@ export function validateAgentFolder(dir, config) {
     catch (err) {
         return [`${AGENT_FILE}: ${err.message}`];
     }
-    const problems = validateWorkflow(config, workflow, dir);
     const name = basename(dir);
+    const problems = validateWorkflow({ ...config, workflows: { ...config.workflows, [name]: workflow } }, workflow, dir);
     const from = config.folders?.[name];
     if (config.workflows[name] && (!from || resolve(from) !== resolve(dir)))
         problems.push(`config.json already has a workflow named ${name}, and it wins. Rename the folder.`);
@@ -228,6 +240,10 @@ export function validateConfig(value, saved) {
         problems.push('reviewState must be a non-empty string.');
     if (!isInt(value.timeoutMinutes, 1, 480))
         problems.push('timeoutMinutes must be a whole number from 1 to 480.');
+    if (value.maxRuns !== undefined && !isInt(value.maxRuns, 0, 32))
+        problems.push('maxRuns must be a whole number from 0 to 32, 0 for no cap.');
+    if (value.pauseAt !== undefined && !isInt(value.pauseAt, 0, 100))
+        problems.push('pauseAt must be a whole number from 0 to 100, 0 to never hold.');
     const projects = isObj(value.projects) ? value.projects : null;
     if (!projects)
         problems.push('projects must be an object.');
@@ -263,7 +279,7 @@ export function validateConfig(value, saved) {
     if (!isObj(value.workflows))
         problems.push('workflows must be an object.');
     else {
-        const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}) };
+        const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}), workflows: value.workflows };
         for (const [name, w] of Object.entries(value.workflows)) {
             // Folder workflows are checked with their folder, by vsf agents validate.
             if (isObj(value.folders) && value.folders[name])

package/dist/notify.js

@@ -96,7 +96,7 @@ const SUMMARY_HOUR = 9;
 const DAY = 86_400_000;
 const localDay = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
 // Runs ended since the last summary (or the last day), counted by outcome,
-// with the pull requests and parked cards.
+// with the pull requests and the parked or failed cards.
 export function summaryMessage(configDir, since, paused) {
     const runs = listRuns(configDir)
         .map((e) => e.record)
@@ -107,14 +107,14 @@ export function summaryMessage(configDir, since, paused) {
     for (const r of runs)
         counts.set(r.outcome, (counts.get(r.outcome) ?? 0) + 1);
     const prs = runs.filter((r) => r.outcome === 'verified' && r.prUrl).slice(0, 10);
-    const parked = runs.filter((r) => r.outcome === 'parked').slice(0, 10);
+    const parked = runs.filter((r) => r.outcome === 'parked' || r.outcome === 'failed').slice(0, 10);
     const lines = [`**Daily summary** ${[...counts].map(([o, n]) => `${n} ${o}`).join(', ')}`];
     if (paused)
         lines.push('Runner paused');
     if (prs.length)
         lines.push('PRs:', ...prs.map((r) => `${r.card} ${r.prUrl}`));
     if (parked.length)
-        lines.push('Parked:', ...parked.map((r) => `${r.card} ${r.title}${r.reason ? `: ${r.reason.slice(0, 120)}` : ''}`));
+        lines.push('Parked or failed:', ...parked.map((r) => `${r.card} ${r.title}${r.reason ? `: ${r.reason.slice(0, 120)}` : ''}`));
     return lines.join('\n');
 }
 // Sends the summary once a day, on the first call at or after 09:00 local.

package/dist/runner.d.ts

@@ -10,11 +10,13 @@ export interface RunContext {
     selfCommand: string[];
     notify?: (event: RunEvent) => Promise<void>;
     summary?: (paused: boolean) => Promise<void>;
+    platform?: NodeJS.Platform;
 }
 export declare function summarize(output: string): string;
+export declare function lastLine(output: string): string;
 export declare function runCard(card: Card, trigger: Trigger, workflowName: string, workflow: Workflow, project: Project, rc: RunContext, opts?: {
     from?: string;
-}): Promise<'verified' | 'changes' | 'parked'>;
+}): Promise<'verified' | 'done' | 'changes' | 'parked' | 'failed'>;
 type Job = {
     card: Card;
     trigger: Trigger;
@@ -35,6 +37,7 @@ export interface JobQuery {
 export declare function findJobs(rc: RunContext, q?: JobQuery): Promise<Job[]>;
 export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: Omit<JobQuery, 'only' | 'workflow' | 'limit'>): Promise<Job | null>;
 export declare function cancelCard(tracker: Tracker, configDir: string, cardId: string, label: string, source?: 'linear' | 'voidtrack'): Promise<boolean>;
+export declare function gateReason(rc: Pick<RunContext, 'configDir' | 'config'>, now?: Date): string | null;
 export declare function tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
     from?: string;
@@ -50,6 +53,7 @@ export interface DispatchDeps {
     start: (args: string[]) => ChildRun;
     waitMs: number;
     reload?: () => AgentsConfig;
+    window: () => Promise<unknown>;
 }
 export declare const jobArgs: (job: Job) => string[];
 export declare function dispatch(rc: RunContext, over?: Partial<DispatchDeps>): Promise<number>;

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();
@@ -122,7 +135,9 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         }
     };
     async function park(reason, kind = 'parked') {
-        say(`parked: ${reason}`);
+        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;
@@ -139,10 +154,11 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
             }
         }
-        const outcome = 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.`);
@@ -150,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)) {
@@ -173,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);
@@ -215,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;
@@ -267,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++;
@@ -292,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
@@ -321,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++;
@@ -342,16 +386,19 @@ 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');
-        done('verified');
+        say(cronRun ? 'done' : 'verified');
+        done(cronRun ? 'done' : 'verified');
     }
     catch (err) {
         if (err instanceof Park)
-            return park(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)
@@ -359,7 +406,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     }
     // Outside the try, so a ping that throws can never park a verified run.
     await ping(record.prUrl ? 'ready' : 'passed');
-    return 'verified';
+    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.
@@ -379,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
@@ -415,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)) {
@@ -538,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
@@ -585,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)));
@@ -615,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}`);
@@ -637,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
@@ -670,12 +802,50 @@ 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);
             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);
@@ -684,10 +854,14 @@ export async function dispatch(rc, over = {}) {
                     rc.log(`discord: ${err.message}`);
                 }
             }
-            if (!paused) {
+            // 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));
@@ -722,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/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[];