@voidlabs.gg/voidshift-agents 0.7.0 → 0.8.0

package/README.md

@@ -103,6 +103,15 @@ vsf agents project edit erp --workspace solvia --match DS06
 Atleurope ERP"). A card of that project runs in the matching project, in any
 workspace, before the workflow's own project is considered.
 
+Two settings keep runs inside your Claude subscription. `vsf config set
+agents.maxRuns 2` caps how many cards run at once over every workspace (0, the
+default, is no cap). Every 5 minutes the runner reads your 5 hour window with
+Claude Code's login, read only, and once it reaches `agents.pauseAt` percent
+(90 by default, 0 turns it off) no new run starts until the window resets;
+running cards finish. `vsf agents status` shows the window, and each run's
+`run.json` keeps the tokens and estimated cost of every step. Naming a card,
+`vsf agents run CARD`, starts it anyway.
+
 A workflow can also be a folder you write by hand,
 `~/.config/voidshift/agents/defs/NAME/agent.json`, with its prompt files next to
 it. Steps are the built-in ids above or your own:
@@ -127,6 +136,20 @@ verified card there (`null` never moves it), `labels: false` only takes the
 trigger label off, and `comment: false` skips the closing comment. Edit the file,
 then `vsf agents validate`.
 
+A step can run a shell command instead of an agent: `"run": "node sweep.mjs"`
+with `output: "none"`. Exit 0 is done, anything else fails the run, and the last
+line it prints is the step's summary. A run made only of command steps works in
+the project folder, with no worktree or branch. A step with `"handoff": "WORKFLOW"`
+hands cards on: every `HANDOFF: ENG-12` line in its output queues that card for
+the named workflow, which runs it as a run of its own, label or not. The card
+leaves the queue once its run has started.
+
+Scheduled runs are jobs: `vsf agents status` shows one line per job, the Runs
+list keeps to card runs (`vsf agents runs --jobs` lists the scheduled ones), and
+a scheduled run that opened no pull request removes its worktree and branch. A
+run whose process ends without an outcome is closed as failed on the runner's
+next pass.
+
 ### memory
 
 A folder of markdown notes, one topic per note, with an `INDEX.md` holding one
@@ -182,6 +205,14 @@ DCO. Only the new commits of that step are rewritten, never pushed ones.
 - **Your config** lives in `~/.config/voidshift`.
 - **Linux.** The runner is a systemd user timer. Run
   `sudo loginctl enable-linger $USER` so it keeps going after you log out.
+  Agents there run with permissions skipped (`--dangerously-skip-permissions`
+  for Claude, `--dangerously-bypass-approvals-and-sandbox` for Codex), so no
+  step ever waits on a prompt and the runner's user account is the boundary.
+  Run it as a dedicated user with no sudo that holds only the keys it needs,
+  never as root, and enable lingering for it from an admin account
+  (`sudo loginctl enable-linger <user>`). `vsf doctor` warns when the runner
+  user has sudo. A step that fails shows its error in the run log, on the card
+  and in Discord.
 
 ```sh
 vsf doctor                     # check everything is set up, and whether an update is out

package/dist/config.d.ts

@@ -14,6 +14,8 @@ export interface StepDef {
     label?: string;
     skill?: string;
     prompt?: string;
+    run?: string;
+    handoff?: string;
     output: Output;
     engine?: Engine;
     model?: string;
@@ -94,6 +96,8 @@ export interface AgentsConfig {
         signOff?: boolean;
         dropAiTrailers?: boolean;
     };
+    maxRuns?: number;
+    pauseAt?: number;
     folders?: Record<string, string>;
 }
 export declare const TEMPLATES: Record<string, {
@@ -133,6 +137,8 @@ export interface ResolvedStep {
     write: boolean;
     prompt: () => string;
     builtin?: StepId;
+    command?: string;
+    handoff?: string;
 }
 export declare function stepFile(step: StepDef, dir?: string): string | null;
 export declare function resolveStep(step: Step, config: Pick<AgentsConfig, 'engine' | 'models' | 'timeoutMinutes'>, dir?: string): ResolvedStep;

package/dist/config.js

@@ -62,6 +62,8 @@ export const DEFAULTS = {
     timeoutMinutes: 45,
     homes: [],
     enabled: [],
+    maxRuns: 0,
+    pauseAt: 90,
 };
 export const agentsDir = (configDir) => join(configDir, 'agents');
 const configPath = (configDir) => join(agentsDir(configDir), 'config.json');
@@ -221,6 +223,14 @@ export function resolveStep(step, config, dir) {
             timeoutMs: config.timeoutMinutes * 60_000, write: s.write, prompt: () => readFileSync(packSkill(step), 'utf8'), builtin: step,
         };
     }
+    // A command step runs a shell command, so it has no prompt.
+    if (step.run) {
+        return {
+            id: step.id, label: step.label ?? step.id, output: step.output, engine: step.engine ?? config.engine,
+            model: step.model ?? config.models.dev, timeoutMs: (step.timeoutMinutes ?? config.timeoutMinutes) * 60_000,
+            write: step.write ?? false, command: step.run, prompt: () => '', handoff: step.handoff,
+        };
+    }
     return {
         id: step.id,
         label: step.label ?? step.id,
@@ -235,5 +245,6 @@ export function resolveStep(step, config, dir) {
                 throw new Error(`Step ${step.id} has no prompt or skill.`);
             return readFileSync(file, 'utf8');
         },
+        handoff: step.handoff,
     };
 }

package/dist/control.d.ts

@@ -11,6 +11,7 @@ export declare function countRounds(steps: {
     result?: string;
 }[]): number;
 export declare const isInterrupted: (e: RunEntry, live: Current[]) => boolean;
+export declare const shownOutcome: (e: RunEntry, live: Current[]) => string;
 export declare function formatRunLine(e: RunEntry, now?: number, live?: Current[]): string;
 export declare function scanRunnerErrors(text: string, now: number): {
     count: number;
@@ -35,6 +36,24 @@ export declare function workingLine(current: (Current & {
 export declare function workspaceLines(workspaces: string[], running: (Current & {
     elapsedMinutes: number;
 })[]): string[];
+interface JobSummary {
+    workflow: string;
+    schedule: string;
+    task: string;
+    last: {
+        at: string;
+        outcome: string;
+        reason?: string;
+        summary?: string;
+    } | null;
+    lastOkAt: string | null;
+    today: {
+        runs: number;
+        failed: number;
+        handed: number;
+    };
+}
+export declare function jobSummaries(config: Pick<AgentsConfig, 'workflows'>, all: RunEntry[], live: Current[], now?: number): JobSummary[];
 export declare function pickCancel(locks: Current[], dispatcher: Current | null, card?: string): Current | string;
 export declare const controlCommands: Record<string, ToolCommand>;
 export declare function controlChecks(ctx: ToolContext): Promise<Check[]>;

package/dist/control.js

@@ -2,13 +2,14 @@ import { spawnSync } from 'node:child_process';
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
-import { agentsDir, isCardTrigger, readAgentsConfig, workspaceOf, workspacesInUse } from "./config.js";
-import { isPaused, listRuns, ours, clearLock, liveCurrent, liveRuns, readCurrent, setPaused, workspaceLocks, writeRun } from "./state.js";
+import { DEFAULTS, agentsDir, isCardTrigger, readAgentsConfig, workspaceOf, workspacesInUse } from "./config.js";
+import { STOPPED_REASON, isPaused, lastSeen, listRuns, ours, clearLock, liveCurrent, liveRuns, readCurrent, readWindow, setPaused, usageText, workspaceLocks, writeRun } from "./state.js";
+import { windowHold, windowLine } from "./usage.js";
 import { runnerService } from "./service.js";
 import { TRACKERS, trackersFor } from "./tracker.js";
 import { parseFrom, resolveName, stepNames } from "./names.js";
 import { isStatusLabel } from "./workflow.js";
-import { cancelCard, dispatch, tick } from "./runner.js";
+import { cancelCard, dispatch, gateReason, tick } from "./runner.js";
 import { notifyRun, notifyRunner, sendSummary } from "./notify.js";
 const HOUR = 3_600_000;
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
@@ -81,13 +82,15 @@ export function countRounds(steps) {
 }
 // A run that says 'running' but is none of the live runs was cut off.
 export const isInterrupted = (e, live) => e.record?.outcome === 'running' && !live.some((l) => (l.runDir ? l.runDir === e.dir : l.card === e.card));
+// The record's outcome, except a run cut off without a live process, which failed.
+export const shownOutcome = (e, live) => (isInterrupted(e, live) ? 'failed' : e.record.outcome);
 export function formatRunLine(e, now = Date.now(), live = []) {
     const r = e.record;
     if (!r)
         return `${e.card}  ${when(stampDate(e.stamp))}  older run, logs only (${plural(e.logs.length, 'log')})`;
     const rounds = countRounds(r.steps);
-    const end = r.endedAt ? Date.parse(r.endedAt) : now;
-    const parts = [e.card, when(new Date(r.startedAt)), r.workflow, r.steps.map((s) => s.label).join(' → '), isInterrupted(e, live) ? 'interrupted' : r.outcome];
+    const end = r.endedAt ? Date.parse(r.endedAt) : isInterrupted(e, live) ? Date.parse(lastSeen(r)) : now;
+    const parts = [e.card, when(new Date(r.startedAt)), r.workflow, r.steps.map((s) => s.label).join(' → '), shownOutcome(e, live)];
     if (rounds)
         parts.push(plural(rounds, 'round'));
     parts.push(formatDuration(end - Date.parse(r.startedAt)));
@@ -122,16 +125,16 @@ const readLog = (configDir) => {
     }
 };
 const USAGE = {
-    status: 'status [--json]   Runner, the card each workspace is on, parked cards and workflows',
+    status: 'status [--json]   Runner, the card each workspace is on, failed and parked cards, scheduled jobs and workflows',
     start: 'start   Start the background runner',
     stop: 'stop   Stop the runner and cancel the cards it is working on',
     restart: 'restart   Stop and start the runner',
     pause: 'pause   Pick up no new cards; a card in progress carries on',
     resume: 'resume   Pick up new cards again',
-    run: 'run [CARD] [--workflow W] [--from STEP]   Run now instead of waiting for the next minute',
+    run: 'run [CARD] [--workflow W] [--from STEP]   Run now instead of waiting for the next minute; a named card skips the pause, the cap and the window hold',
     cancel: 'cancel [CARD]   Stop a card being worked on and clear its labels',
     retry: 'retry CARD [--workflow W]   Queue a parked or cancelled card again',
-    runs: 'runs [CARD] [--limit N] [--json]   Past runs, newest first',
+    runs: 'runs [CARD] [--limit N] [--jobs] [--json]   Past runs, newest first; --jobs lists scheduled runs only',
     show: 'show CARD [--json]   Steps, outcome and labels of the latest run',
     logs: 'logs [CARD] [--step N] [-f] [--lines N]   Runner log, or a card\'s step logs',
     clean: 'clean [--older 14d] [--yes]   Remove old worktrees and run folders',
@@ -294,6 +297,43 @@ export function workspaceLines(workspaces, running) {
     const names = [...new Set([...workspaces, ...running.map((r) => workspaceOf(r))])];
     return names.map((ws) => `  ${ws}:${workingLine(running.find((r) => workspaceOf(r) === ws) ?? null) || ' idle.'}`);
 }
+// One entry per cron trigger: its newest run, last success and today's counts.
+export function jobSummaries(config, all, live, now = Date.now()) {
+    const day = new Date(now).toDateString();
+    const jobs = [];
+    for (const [workflow, w] of Object.entries(config.workflows)) {
+        for (const t of w.triggers) {
+            if (t.source !== 'cron')
+                continue;
+            const mine = all.filter((e) => e.record?.source === 'cron' && e.record.workflow === workflow && e.record.trigger === t.schedule);
+            const newest = mine[0];
+            const r = newest?.record;
+            const ok = mine.find((e) => e.record.outcome === 'done' || e.record.outcome === 'verified');
+            const todays = mine.filter((e) => new Date(e.record.startedAt).toDateString() === day);
+            jobs.push({
+                workflow,
+                schedule: t.schedule,
+                task: t.task,
+                last: r ? { at: r.endedAt ?? r.startedAt, outcome: shownOutcome(newest, live), reason: r.reason, summary: r.steps.at(-1)?.summary } : null,
+                lastOkAt: ok?.record.startedAt ?? null,
+                today: {
+                    runs: todays.length,
+                    failed: todays.filter((e) => ['failed', 'parked'].includes(shownOutcome(e, live))).length,
+                    handed: todays.reduce((n, e) => n + e.record.steps.reduce((m, s) => m + (s.handoffs?.length ?? 0), 0), 0),
+                },
+            });
+        }
+    }
+    return jobs;
+}
+// The status line for one job.
+function jobLine(j) {
+    const bad = j.last?.outcome === 'failed' || j.last?.outcome === 'parked';
+    const head = bad
+        ? `last failed ${clock(new Date(j.last.at))}${j.last.reason ? ` (${j.last.reason.replace(/\.$/, '')})` : ''}`
+        : `last ok ${j.lastOkAt ? clock(new Date(j.lastOkAt)) : 'never'}`;
+    return `Job ${j.workflow} (cron ${j.schedule}): ${head}, ${plural(j.today.runs, 'run')} today, ${j.today.failed} failed, ${j.today.handed} handed.`;
+}
 const status = guard(async (args, ctx) => {
     const p = parse('status', args, { json: { type: 'boolean' } }, ctx);
     if (typeof p === 'number')
@@ -309,20 +349,29 @@ const status = guard(async (args, ctx) => {
     const current = running.length ? { ...running[0], checking: false } : dispatcher ? { ...dispatcher, checking: true, elapsedMinutes: elapsed(dispatcher) } : null;
     const seen = new Set();
     const parked = [];
+    const failed = [];
     const interrupted = [];
-    for (const e of listRuns(ctx.configDir)) {
-        if (e.record?.outcome === 'running' && isInterrupted(e, live))
-            interrupted.push(e.card);
-        if (seen.has(e.card))
+    const all = listRuns(ctx.configDir);
+    for (const e of all) {
+        if (e.record?.source === 'cron' || seen.has(e.card))
             continue;
         seen.add(e.card);
         if (e.record?.outcome === 'parked')
             parked.push({ card: e.card, reason: e.record.reason });
+        else if (e.record?.outcome === 'failed')
+            failed.push({ card: e.card, reason: e.record.reason });
+        else if (isInterrupted(e, live))
+            failed.push({ card: e.card, reason: e.record?.reason ?? STOPPED_REASON });
     }
+    const jobs = jobSummaries(config, all, live);
     const workflows = Object.keys(config.workflows).length;
     const projects = Object.keys(config.projects).length;
+    const pauseAt = config.pauseAt ?? DEFAULTS.pauseAt;
+    const maxRuns = config.maxRuns ?? 0;
+    const w = readWindow(ctx.configDir);
     if (p.values.json) {
-        ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, running, parked, interrupted, workflows, projects }, null, 2));
+        const window = w && { ...w, heldUntil: windowHold(w, pauseAt) };
+        ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, running, parked, failed, interrupted, jobs, workflows, projects, window, maxRuns }, null, 2));
         return 0;
     }
     // One workspace keeps the single line; several get a line each.
@@ -338,12 +387,19 @@ const status = guard(async (args, ctx) => {
     if (perWorkspace)
         for (const line of workspaceLines(workspaces, running))
             ctx.log(line);
+    const windowText = windowLine(w, pauseAt);
+    if (windowText)
+        ctx.log(windowText);
+    if (maxRuns)
+        ctx.log(`Cap: at most ${plural(maxRuns, 'run')} at once.`);
     if (lastTick)
         ctx.log(`Last check: ${clock(new Date(lastTick.at))}, ${lastTick.line.replace(/\.$/, '') || 'no details'}.`);
-    for (const card of interrupted)
-        ctx.log(`Interrupted: ${card}. vsf agents retry ${card} to run it again.`);
+    for (const k of failed)
+        ctx.log(`Failed: ${k.card}${k.reason ? ` (${k.reason.replace(/\.$/, '')})` : ''}. vsf agents retry ${k.card} after fixing the cause.`);
     for (const k of parked)
         ctx.log(`Parked: ${k.card}${k.reason ? ` (${k.reason.replace(/\.$/, '')})` : ''}. vsf agents retry ${k.card} after fixing the cause.`);
+    for (const j of jobs)
+        ctx.log(jobLine(j));
     ctx.log(`${plural(workflows, 'workflow')}, ${plural(projects, 'project')}. vsf agents workflows lists them.`);
     return 0;
 });
@@ -419,6 +475,8 @@ const run = guard(async (args, ctx) => {
     if (!card && code === 0) {
         if (isPaused(ctx.configDir))
             ctx.log('The runner is paused, so nothing was picked up. vsf agents resume, or name a card.');
+        else if (gateReason({ configDir: ctx.configDir, config }))
+            ctx.log('Name a card to run it anyway.');
         else
             ctx.log('Nothing to do, or the card was verified.');
     }
@@ -464,6 +522,11 @@ const retry = guard(async (args, ctx) => {
         ctx.log(`${id} is running now. vsf agents cancel ${id} first.`);
         return 1;
     }
+    const latest = listRuns(ctx.configDir, id)[0]?.record;
+    if (latest?.source === 'cron') {
+        ctx.log(`${id} is a scheduled run. vsf agents run --workflow ${latest.workflow} fires it now.`);
+        return 1;
+    }
     const config = readAgentsConfig(ctx.configDir);
     const names = Object.keys(config.workflows);
     let found;
@@ -514,7 +577,7 @@ const retry = guard(async (args, ctx) => {
     return 0;
 });
 const runs = guard(async (args, ctx) => {
-    const p = parse('runs', args, { limit: { type: 'string' }, json: { type: 'boolean' } }, ctx);
+    const p = parse('runs', args, { limit: { type: 'string' }, jobs: { type: 'boolean' }, json: { type: 'boolean' } }, ctx);
     if (typeof p === 'number')
         return p;
     const card = p.positionals[0]?.toUpperCase();
@@ -523,7 +586,8 @@ const runs = guard(async (args, ctx) => {
     const limit = p.values.limit === undefined ? 20 : Number(p.values.limit);
     if (!Number.isInteger(limit) || limit < 1)
         return usageError('runs', ctx, '--limit needs a whole number above 0.');
-    const entries = listRuns(ctx.configDir, card).slice(0, limit);
+    // A named card lists all its runs; otherwise card runs, or with --jobs scheduled ones.
+    const entries = listRuns(ctx.configDir, card).filter((e) => !!card || (e.record?.source === 'cron') === !!p.values.jobs).slice(0, limit);
     if (p.values.json) {
         ctx.log(JSON.stringify(entries.map((e) => ({ card: e.card, stamp: e.stamp, dir: e.dir, logs: e.logs, record: e.record })), null, 2));
         return 0;
@@ -564,13 +628,17 @@ const show = guard(async (args, ctx) => {
         return 0;
     }
     ctx.log(`${latest.card}  ${latest.title}`);
-    ctx.log(`Workflow ${latest.workflow}, ${isInterrupted(all[0], liveRuns(ctx.configDir)) ? 'interrupted' : latest.outcome}${latest.prUrl ? `, PR ${latest.prUrl}` : ''}`);
+    ctx.log(`Workflow ${latest.workflow}, ${shownOutcome(all[0], liveRuns(ctx.configDir))}${latest.prUrl ? `, PR ${latest.prUrl}` : ''}`);
     if (labels)
         ctx.log(`Labels: ${labels.join(', ') || 'none'}`);
     for (const s of latest.steps) {
         const took = s.endedAt ? formatDuration(Date.parse(s.endedAt) - Date.parse(s.startedAt)) : 'running';
-        ctx.log(`  ${s.label.padEnd(12)} ${(s.result ?? 'running').toLowerCase().padEnd(8)} ${took.padEnd(6)} ${oneLine(s.summary ?? '')}`.trimEnd());
+        const used = usageText(s.usage);
+        ctx.log(`  ${s.label.padEnd(12)} ${(s.result ?? 'running').toLowerCase().padEnd(8)} ${took.padEnd(6)} ${used ? `${used}  ` : ''}${oneLine(s.summary ?? '')}`.trimEnd());
     }
+    const total = usageText(latest.usage);
+    if (total || latest.usage?.models?.length)
+        ctx.log(`Usage: ${[total, latest.usage?.models?.join(', ')].filter(Boolean).join(', ')}`);
     if (latest.outcome === 'parked' && latest.reason)
         ctx.log(`Parked: ${oneLine(latest.reason, 300)}`);
     if (all.length > 1)

package/dist/engine.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from 'node:child_process';
+import { type Usage } from './state.ts';
 export type Engine = 'claude' | 'codex';
 export interface RunOptions {
     engine: Engine;
@@ -10,6 +11,7 @@ export interface RunOptions {
     timeoutMs?: number;
     vault?: string;
     settingsFile?: string;
+    platform?: NodeJS.Platform;
 }
 export declare function engineArgs(o: RunOptions, outFile: string): {
     cmd: string;
@@ -17,7 +19,27 @@ export declare function engineArgs(o: RunOptions, outFile: string): {
 };
 export declare function track(child: ChildProcess): void;
 export declare function stopAgents(): Promise<void>;
+export declare function errorTail(stderr: string): string;
+export interface ClaudeResult {
+    text: string;
+    isError: boolean;
+    usage: Usage;
+}
+export declare function parseClaudeJson(stdout: string): ClaudeResult | null;
 export declare function runAgent(o: RunOptions): Promise<{
     ok: boolean;
     output: string;
+    error?: string;
+    usage?: Usage;
+}>;
+export declare function runCommand(o: {
+    command: string;
+    cwd: string;
+    logFile: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}): Promise<{
+    ok: boolean;
+    output: string;
+    error?: string;
 }>;

package/dist/engine.js

@@ -2,15 +2,29 @@ import { spawn } from 'node:child_process';
 import { createWriteStream, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { usageText } from "./state.js";
 // Tools a write step may use under `claude -p`. Anything else is denied,
 // since nobody is there to approve it.
 const CLAUDE_WRITE = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
 const CLAUDE_READ = ['Read', 'Glob', 'Grep', 'Bash(git diff:*)', 'Bash(git log:*)', 'Bash(git show:*)', 'Bash(npm test:*)', 'Bash(npm run:*)', 'Bash(pnpm:*)', 'Bash(yarn:*)', 'Bash(npx:*)', 'Bash(node:*)', 'Bash(ls:*)', 'Bash(rg:*)'];
 export function engineArgs(o, outFile) {
+    // Nobody is there to approve a prompt, and an allowlist that misses a tool
+    // breaks the run, so on Linux every step runs with permissions skipped.
+    const skip = (o.platform ?? process.platform) === 'linux';
+    if (o.engine === 'claude' && skip) {
+        const args = ['-p', '--output-format', 'json', '--dangerously-skip-permissions'];
+        if (o.vault)
+            args.push('--add-dir', o.vault);
+        if (o.model)
+            args.push('--model', o.model);
+        if (o.settingsFile)
+            args.push('--settings', o.settingsFile);
+        return { cmd: 'claude', args };
+    }
     if (o.engine === 'claude') {
         // Edit rules cover every file-writing tool; a Write(path) rule is ignored.
         const vaultTools = o.vault ? [`Edit(/${o.vault}/**)`] : [];
-        const args = ['-p', '--output-format', 'text', '--allowedTools', [...(o.write ? CLAUDE_WRITE : CLAUDE_READ), ...vaultTools].join(',')];
+        const args = ['-p', '--output-format', 'json', '--allowedTools', [...(o.write ? CLAUDE_WRITE : CLAUDE_READ), ...vaultTools].join(',')];
         if (o.vault)
             args.push('--add-dir', o.vault);
         if (o.write)
@@ -21,6 +35,13 @@ export function engineArgs(o, outFile) {
             args.push('--settings', o.settingsFile);
         return { cmd: 'claude', args };
     }
+    if (skip) {
+        const args = ['exec', '-C', o.cwd, '--dangerously-bypass-approvals-and-sandbox', '-o', outFile];
+        if (o.model)
+            args.push('-m', o.model);
+        args.push('-');
+        return { cmd: 'codex', args };
+    }
     const args = ['exec', '-C', o.cwd, '-s', o.write ? 'workspace-write' : 'read-only', '-o', outFile];
     // A read-only sandbox cannot write anywhere, so only write steps get the vault.
     if (o.vault && o.write)
@@ -49,8 +70,52 @@ export async function stopAgents() {
         if (c.exitCode === null && c.signalCode === null)
             c.kill('SIGKILL');
 }
+// Why a failed agent process failed: the last lines it wrote to stderr.
+export function errorTail(stderr) {
+    const lines = stderr.split('\n').map((l) => l.trim()).filter(Boolean);
+    let out = '';
+    for (const line of lines.reverse()) {
+        const next = out ? `${line} ${out}` : line;
+        if (next.length > 300)
+            break;
+        out = next;
+    }
+    return out || lines[0]?.slice(-300) || '';
+}
+// Claude's JSON answer: its final text, and the tokens and cost it spent.
+// Null when the output is not that JSON, so it is taken as plain text.
+export function parseClaudeJson(stdout) {
+    let j;
+    try {
+        j = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!j || typeof j !== 'object' || typeof j.result !== 'string')
+        return null;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    const usage = {};
+    const models = j.modelUsage && typeof j.modelUsage === 'object' ? Object.entries(j.modelUsage) : [];
+    if (models.length) {
+        // Every model the step used, side models included.
+        usage.input = models.reduce((t, [, m]) => t + num(m?.inputTokens), 0);
+        usage.output = models.reduce((t, [, m]) => t + num(m?.outputTokens), 0);
+        usage.cached = models.reduce((t, [, m]) => t + num(m?.cacheReadInputTokens) + num(m?.cacheCreationInputTokens), 0);
+        usage.model = models.reduce((best, cur) => (num(cur[1]?.costUSD) > num(best[1]?.costUSD) ? cur : best))[0];
+    }
+    else if (j.usage && typeof j.usage === 'object') {
+        usage.input = num(j.usage.input_tokens);
+        usage.output = num(j.usage.output_tokens);
+        usage.cached = num(j.usage.cache_read_input_tokens) + num(j.usage.cache_creation_input_tokens);
+    }
+    if (typeof j.total_cost_usd === 'number')
+        usage.costUsd = j.total_cost_usd;
+    return { text: j.result, isError: j.is_error === true, usage };
+}
 // Runs one agent step with the prompt on stdin. Resolves with the agent's
-// final text; everything it prints also goes to the log file.
+// final text; what it prints also goes to the log file, Claude's answer as
+// its text and a usage line. A process that fails also says why in `error`.
 export function runAgent(o) {
     const dir = mkdtempSync(join(tmpdir(), 'voidshift-run-'));
     const outFile = join(dir, 'last.txt');
@@ -63,24 +128,52 @@ export function runAgent(o) {
         const env = { ...process.env, VOIDSHIFT_RECALL: 'off' };
         const child = spawn(cmd, args, { cwd: o.cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
         track(child);
+        // Claude's JSON comes at exit, so it is held and logged as text then.
         let stdout = '';
         child.stdout.on('data', (d) => {
             stdout += d;
+            if (o.engine !== 'claude')
+                log.write(d);
+        });
+        // Only the tail is kept; the log has all of it.
+        let stderr = '';
+        child.stderr.on('data', (d) => {
+            stderr = (stderr + d).split('\n').slice(-20).join('\n');
             log.write(d);
         });
-        child.stderr.on('data', (d) => log.write(d));
-        const timer = setTimeout(() => child.kill('SIGTERM'), o.timeoutMs ?? 45 * 60_000);
+        const timeoutMs = o.timeoutMs ?? 45 * 60_000;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
         child.on('error', (err) => {
             clearTimeout(timer);
             children.delete(child);
             log.end(`\n${err.message}\n`);
-            resolve({ ok: false, output: err.message });
+            resolve({ ok: false, output: err.message, error: err.message });
         });
         child.on('close', (code) => {
             clearTimeout(timer);
             children.delete(child);
-            log.end(`\nexit ${code}\n`);
             let output = stdout;
+            let usage;
+            let failure = '';
+            if (o.engine === 'claude') {
+                const parsed = parseClaudeJson(stdout);
+                if (parsed) {
+                    output = parsed.text;
+                    if (Object.keys(parsed.usage).length)
+                        usage = parsed.usage;
+                    if (parsed.isError)
+                        failure = parsed.text;
+                    log.write(`${output}\n\nusage: ${[usageText(usage), usage?.model].filter(Boolean).join(', ') || 'none reported'}\n`);
+                }
+                else
+                    log.write(stdout);
+            }
+            else if (o.model)
+                usage = { model: o.model };
             if (o.engine === 'codex') {
                 try {
                     output = readFileSync(outFile, 'utf8');
@@ -90,8 +183,52 @@ export function runAgent(o) {
                 }
             }
             rmSync(dir, { recursive: true, force: true });
-            resolve({ ok: code === 0, output });
+            const minutes = Math.round(timeoutMs / 60_000);
+            const error = code === 0 ? undefined : timedOut ? `timed out after ${minutes} minute${minutes === 1 ? '' : 's'}` : errorTail(stderr) || errorTail(failure) || `exit ${code}`;
+            // Settled once the log is written, so the step's log is whole when read.
+            log.end(`\nexit ${code}\n`, () => resolve({ ok: code === 0, output, ...(error ? { error } : {}), ...(usage ? { usage } : {}) }));
         });
         child.stdin.end(o.prompt);
     });
 }
+// Runs one command step in a shell in place of an agent. Resolves with what it
+// printed on stdout, which is also logged along with stderr; a command that
+// fails also says why in `error`.
+export function runCommand(o) {
+    const log = createWriteStream(o.logFile, { flags: 'a' });
+    log.write(`$ ${o.command}\n\n`);
+    return new Promise((resolve) => {
+        const child = spawn('sh', ['-c', o.command], { cwd: o.cwd, env: { ...process.env, ...o.env }, stdio: ['ignore', 'pipe', 'pipe'] });
+        track(child);
+        let stdout = '';
+        child.stdout.on('data', (d) => {
+            stdout += d;
+            log.write(d);
+        });
+        // Only the tail is kept; the log has all of it.
+        let stderr = '';
+        child.stderr.on('data', (d) => {
+            stderr = (stderr + d).split('\n').slice(-20).join('\n');
+            log.write(d);
+        });
+        const timeoutMs = o.timeoutMs ?? 45 * 60_000;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            children.delete(child);
+            log.end(`\n${err.message}\n`);
+            resolve({ ok: false, output: err.message, error: err.message });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            children.delete(child);
+            const minutes = Math.round(timeoutMs / 60_000);
+            const error = code === 0 ? undefined : timedOut ? `timed out after ${minutes} minute${minutes === 1 ? '' : 's'}` : errorTail(stderr) || `exit ${code}`;
+            log.end(`\nexit ${code}\n`, () => resolve({ ok: code === 0, output: stdout, ...(error ? { error } : {}) }));
+        });
+    });
+}

package/dist/git.d.ts

@@ -34,3 +34,4 @@ export interface CommitPolicy {
 }
 export declare function applyPolicy(message: string, policy: CommitPolicy, signer: string | null, cwd: string): string;
 export declare function enforceCommitPolicy(worktree: string, from: string, policy: CommitPolicy): number;
+export declare function removeWorktree(repo: string, worktree: string, branch: string): void;

package/dist/git.js

@@ -194,3 +194,8 @@ export function enforceCommitPolicy(worktree, from, policy) {
         must(sh('git', ['reset', '-q', '--soft', head], worktree), 'git reset');
     return changed;
 }
+// Removes a worktree and its branch. Errors are ignored: either may be gone already.
+export function removeWorktree(repo, worktree, branch) {
+    sh('git', ['worktree', 'remove', '--force', worktree], repo);
+    sh('git', ['branch', '-D', branch], repo);
+}

package/dist/manage.d.ts

@@ -1,6 +1,6 @@
 import { type AgentsConfig, type Step, type Trigger, type Workflow } from './config.ts';
-export declare function validateStep(step: Step, config: Pick<AgentsConfig, 'enabled'>, dir?: string): string[];
-export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'>, workflow: Workflow, dir?: string): string[];
+export declare function validateStep(step: Step, config: Pick<AgentsConfig, 'enabled'> & Partial<Pick<AgentsConfig, 'workflows'>>, dir?: string): string[];
+export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'> & Partial<Pick<AgentsConfig, 'workflows'>>, workflow: Workflow, dir?: string): string[];
 export declare function validateAgentFolder(dir: string, config: Pick<AgentsConfig, 'enabled' | 'projects' | 'workflows' | 'folders'>): string[];
 export declare const TRIGGER_FORMS = "TEAM:LABEL (Linear), voidtrack:TEAM:LABEL, or cron:SCHEDULE:TASK";
 export declare function parseTrigger(input: string): Trigger | null;