@voidlabs.gg/voidshift-agents 0.5.1 → 0.6.0

package/README.md

@@ -74,9 +74,9 @@ or `vs-parked`) and the round (`vs-v1`, `vs-v2`). On Linear it posts the plan an
 one final comment, nothing in between.
 
 ```sh
-vsf agents status                  # runner, the card in progress, parked cards
+vsf agents status                  # runner, the card each workspace is on, parked cards
 vsf agents run ENG-123 [--from qa] # run one card now, in this terminal
-vsf agents start | stop | restart  # the background runner (stop cancels the card)
+vsf agents start | stop | restart  # the background runner (stop cancels its cards)
 vsf agents pause | resume          # pick up no new cards for a while
 vsf agents cancel | retry ENG-123  # stop a card, or queue a parked one again
 vsf agents runs | show ENG-123     # what happened, step by step
@@ -84,11 +84,25 @@ vsf agents logs [ENG-123] [-f]     # the runner log, or a card's step logs
 vsf agents workflows               # workflows in the order they match
 vsf agents workflow add|edit|show|rename|move|rm
 vsf agents projects | project add|edit|show|rename|rm
+vsf agents workspace add|list|rm   # folders of repos, each with its own queue
 vsf agents homes | link DIR        # where the agents are installed
 vsf agents clean                   # old worktrees and run logs
 vsf agents validate [DIR]          # check the config and agent folders
 ```
 
+Each workspace has one queue: cards in different workspaces run side by side,
+two cards in one workspace one after the other. Projects are in the `default`
+workspace until you move them:
+
+```sh
+vsf agents workspace add solvia --root ~/work/solvia   # steps carry ~/work/solvia/CONTEXT.md
+vsf agents project edit erp --workspace solvia --match DS06
+```
+
+`--match` names a tracker project (or its first word, so `DS06` matches "DS06
+Atleurope ERP"). A card of that project runs in the matching project, in any
+workspace, before the workflow's own project is considered.
+
 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:

package/dist/config.d.ts

@@ -52,7 +52,16 @@ export declare function describeTrigger(t: Trigger): string;
 export interface Project {
     path: string;
     base?: string;
+    workspace?: string;
+    match?: string[];
 }
+export interface Workspace {
+    root: string;
+    context?: string;
+}
+export declare const DEFAULT_WORKSPACE = "default";
+export declare const WORKSPACE_NAME: RegExp;
+export declare const workspaceOf: (project: Pick<Project, "workspace"> | undefined) => string;
 export interface WriteBack {
     labels?: boolean;
     state?: string | null;
@@ -72,6 +81,7 @@ export interface AgentsConfig {
         review?: string;
     };
     projects: Record<string, Project>;
+    workspaces: Record<string, Workspace>;
     workflows: Record<string, Workflow>;
     reviewState: string;
     timeoutMinutes: number;
@@ -104,6 +114,15 @@ export declare function agentFolders(configDir: string): string[];
 export declare function readAgentFolder(dir: string): Workflow;
 export declare function readAgentsConfig(configDir: string): AgentsConfig;
 export declare function writeAgentsConfig(configDir: string, config: AgentsConfig): void;
+export declare const workspacesInUse: (config: Pick<AgentsConfig, "projects" | "workspaces">) => string[];
+export declare function matchesProject(entry: string, projectName: string): boolean;
+export declare function resolveProject(config: Pick<AgentsConfig, 'projects'>, workflow: Pick<Workflow, 'project'>, card: {
+    projectName?: string;
+}): {
+    name: string;
+    project: Project;
+} | null;
+export declare function workspaceContext(config: Pick<AgentsConfig, 'workspaces'>, name: string): string;
 export interface ResolvedStep {
     id: string;
     label: string;

package/dist/config.js

@@ -43,6 +43,9 @@ export function describeTrigger(t) {
         return `cron ${t.schedule}`;
     return `${t.source === 'voidtrack' ? 'VoidTrack ' : ''}${t.team} + ${t.label}`;
 }
+export const DEFAULT_WORKSPACE = 'default';
+export const WORKSPACE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export const workspaceOf = (project) => project?.workspace || DEFAULT_WORKSPACE;
 // Step lists to start a workflow from.
 export const TEMPLATES = {
     build: { steps: ['vs-dev', 'vs-qa'], maxRounds: 3 },
@@ -53,6 +56,7 @@ export const DEFAULTS = {
     engine: 'claude',
     models: { dev: 'opus', review: 'sonnet' },
     projects: {},
+    workspaces: {},
     workflows: {},
     reviewState: 'In Review',
     timeoutMinutes: 45,
@@ -157,6 +161,45 @@ export function writeAgentsConfig(configDir, config) {
     const workflows = Object.fromEntries(Object.entries(config.workflows).filter(([name]) => !folders?.[name]));
     writeFileSync(configPath(configDir), JSON.stringify({ ...rest, workflows }, null, 2) + '\n');
 }
+// Every workspace a config uses: the named ones, then any a project names,
+// the default one included.
+export const workspacesInUse = (config) => [
+    ...new Set([...Object.keys(config.workspaces ?? {}), ...Object.values(config.projects).map(workspaceOf)]),
+];
+// Whether a match entry names a tracker project: the whole name, or its first
+// word, so "DS06" matches "DS06 Atleurope ERP". Case does not matter.
+export function matchesProject(entry, projectName) {
+    const want = entry.trim().toLowerCase();
+    const name = projectName.trim().toLowerCase();
+    return !!want && (want === name || want === name.split(/\s+/)[0]);
+}
+// The project a card runs in. Explicit matches on the card's tracker project
+// come first, in every workspace, and only then the workflow's own project.
+// A scheduled run has no tracker project, so it always takes the workflow's.
+export function resolveProject(config, workflow, card) {
+    if (card.projectName) {
+        for (const [name, project] of Object.entries(config.projects)) {
+            if (project.match?.some((m) => matchesProject(m, card.projectName)))
+                return { name, project };
+        }
+    }
+    const project = config.projects[workflow.project];
+    return project ? { name: workflow.project, project } : null;
+}
+// The workspace's context text for the step prompts: its context file, or
+// CONTEXT.md in its root. Empty when there is none.
+export function workspaceContext(config, name) {
+    const ws = config.workspaces?.[name];
+    if (!ws)
+        return '';
+    const file = ws.context ? resolve(ws.root, ws.context) : join(ws.root, 'CONTEXT.md');
+    try {
+        return readFileSync(file, 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
+}
 const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
 const packSkill = (name) => join(packDir, name, 'SKILL.md');
 // The file a custom step's prompt comes from: its prompt file, a pack skill,

package/dist/control.d.ts

@@ -10,8 +10,8 @@ export declare function stampDate(stamp: string): Date;
 export declare function countRounds(steps: {
     result?: string;
 }[]): number;
-export declare const isInterrupted: (e: RunEntry, live: Current | null) => boolean;
-export declare function formatRunLine(e: RunEntry, now?: number, live?: Current | null): string;
+export declare const isInterrupted: (e: RunEntry, live: Current[]) => boolean;
+export declare function formatRunLine(e: RunEntry, now?: number, live?: Current[]): string;
 export declare function scanRunnerErrors(text: string, now: number): {
     count: number;
     last: string;
@@ -31,5 +31,9 @@ export declare function trackerWarnings(kinds: Kind[], trackers: Trackers): Prom
 export declare function workingLine(current: (Current & {
     elapsedMinutes: number;
 }) | null): string;
+export declare function workspaceLines(workspaces: string[], running: (Current & {
+    elapsedMinutes: number;
+})[]): string[];
+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,13 @@ 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 } from "./config.js";
-import { isPaused, listRuns, ours, clearCurrent, liveCurrent, readCurrent, setPaused, writeRun } from "./state.js";
+import { agentsDir, isCardTrigger, readAgentsConfig, workspaceOf, workspacesInUse } from "./config.js";
+import { isPaused, listRuns, ours, clearLock, liveCurrent, liveRuns, readCurrent, setPaused, workspaceLocks, writeRun } from "./state.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, tick } from "./runner.js";
+import { cancelCard, dispatch, tick } from "./runner.js";
 const HOUR = 3_600_000;
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const CARD_ID = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
@@ -78,9 +78,9 @@ export function countRounds(steps) {
     }
     return rounds;
 }
-// A run that says 'running' but is not the live card was cut off.
-export const isInterrupted = (e, live) => e.record?.outcome === 'running' && !(live && (live.runDir ? live.runDir === e.dir : live.card === e.card));
-export function formatRunLine(e, now = Date.now(), live = null) {
+// 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));
+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')})`;
@@ -121,14 +121,14 @@ const readLog = (configDir) => {
     }
 };
 const USAGE = {
-    status: 'status [--json]   Runner, current card, parked cards and workflows',
+    status: 'status [--json]   Runner, the card each workspace is on, parked cards and workflows',
     start: 'start   Start the background runner',
-    stop: 'stop   Stop the runner and cancel the card it is working on',
+    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',
-    cancel: 'cancel [CARD]   Stop the card being worked on and clear its labels',
+    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',
     show: 'show CARD [--json]   Steps, outcome and labels of the latest run',
@@ -215,7 +215,7 @@ export async function cancelCurrent(ctx, c, deps) {
     }
     else
         ctx.log('Cleared a stale lock.');
-    clearCurrent(ctx.configDir);
+    clearLock(ctx.configDir, c);
 }
 const realDeps = (ctx) => ({
     ours,
@@ -263,7 +263,9 @@ async function startCmd(ctx) {
 }
 async function stopCmd(ctx) {
     runnerService().stop(ctx.home);
-    // Stopping the runner may have stopped the pass; finish or tidy up whatever the lock still names.
+    // Stopping the runner may have stopped its runs; finish or tidy up whatever the locks still name.
+    for (const c of workspaceLocks(ctx.configDir))
+        await cancelCurrent(ctx, c, realDeps(ctx));
     const c = readCurrent(ctx.configDir);
     if (c)
         await cancelCurrent(ctx, c, realDeps(ctx));
@@ -278,6 +280,12 @@ export function workingLine(current) {
         return ' Checking now.';
     return ` Working on ${current.card}${current.title ? ` "${current.title}"` : ''} (${[current.workflow, current.step, current.round ? `round ${current.round}` : '', `${current.elapsedMinutes}m`].filter(Boolean).join(', ')}).`;
 }
+const elapsed = (c) => (c.startedAt ? Math.max(0, Math.round((Date.now() - Date.parse(c.startedAt)) / 60_000)) : 0);
+// One line per workspace: the card it is on, or idle.
+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.'}`);
+}
 const status = guard(async (args, ctx) => {
     const p = parse('status', args, { json: { type: 'boolean' } }, ctx);
     if (typeof p === 'number')
@@ -286,8 +294,11 @@ const status = guard(async (args, ctx) => {
     const runner = runnerState(ctx);
     const text = readLog(ctx.configDir);
     const lastTick = lastTickOf(text);
-    const live = liveCurrent(ctx.configDir);
-    const current = live ? { ...live, checking: !live.card, elapsedMinutes: live.startedAt ? Math.max(0, Math.round((Date.now() - Date.parse(live.startedAt)) / 60_000)) : 0 } : null;
+    const live = liveRuns(ctx.configDir);
+    const running = live.map((c) => ({ ...c, workspace: workspaceOf(c), elapsedMinutes: elapsed(c) }));
+    const dispatcher = liveCurrent(ctx.configDir);
+    // The first run, or the dispatcher checking for work, for dashboards that know one run only.
+    const current = running.length ? { ...running[0], checking: false } : dispatcher ? { ...dispatcher, checking: true, elapsedMinutes: elapsed(dispatcher) } : null;
     const seen = new Set();
     const parked = [];
     const interrupted = [];
@@ -303,16 +314,22 @@ const status = guard(async (args, ctx) => {
     const workflows = Object.keys(config.workflows).length;
     const projects = Object.keys(config.projects).length;
     if (p.values.json) {
-        ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, parked, interrupted, workflows, projects }, null, 2));
+        ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, running, parked, interrupted, workflows, projects }, null, 2));
         return 0;
     }
-    const working = workingLine(current);
+    // One workspace keeps the single line; several get a line each.
+    const workspaces = workspacesInUse(config);
+    const perWorkspace = runner !== 'stopped' && (workspaces.length > 1 || running.some((r) => !workspaces.includes(r.workspace)));
+    const working = perWorkspace ? '' : workingLine(current);
     if (runner === 'running')
         ctx.log(`Runner: running.${working}`);
     else if (runner === 'paused')
         ctx.log(`Runner: paused, picks up no new cards. vsf agents resume to continue.${working}`);
     else
         ctx.log('Runner: stopped. vsf agents start to begin.');
+    if (perWorkspace)
+        for (const line of workspaceLines(workspaces, running))
+            ctx.log(line);
     if (lastTick)
         ctx.log(`Last check: ${clock(new Date(lastTick.at))}, ${lastTick.line.replace(/\.$/, '') || 'no details'}.`);
     for (const card of interrupted)
@@ -399,6 +416,20 @@ const run = guard(async (args, ctx) => {
     }
     return code;
 });
+// The lock a cancel ends, or why there is none. Every run's lock counts, stale
+// ones included, so a dead run can be tidied up; with none, the dispatcher's
+// own lock, a check in progress. Without a card it must be the only one.
+export function pickCancel(locks, dispatcher, card) {
+    const all = locks.length ? locks : dispatcher ? [dispatcher] : [];
+    if (!all.length)
+        return card ? `${card} is not running.` : 'Nothing is running.';
+    const name = (l) => `${l.card ?? 'a check'}${l.workspace ? ` in ${l.workspace}` : ''}`;
+    if (card)
+        return all.find((l) => l.card === card) ?? `${card} is not running. Running: ${all.map(name).join(', ')}.`;
+    if (all.length > 1)
+        return `More than one card is running: ${all.map(name).join(', ')}. Name one: vsf agents cancel CARD.`;
+    return all[0];
+}
 const cancel = guard(async (args, ctx) => {
     const p = parse('cancel', args, {}, ctx);
     if (typeof p === 'number')
@@ -406,16 +437,12 @@ const cancel = guard(async (args, ctx) => {
     const card = p.positionals[0]?.toUpperCase();
     if (p.positionals.length > 1 || (card && !CARD_ID.test(card)))
         return usageError('cancel', ctx, 'Give one card id like ENG-12.');
-    const c = readCurrent(ctx.configDir);
-    if (!c) {
-        ctx.log(card ? `${card} is not running.` : 'Nothing is running.');
-        return card ? 1 : 0;
-    }
-    if (card && c.card !== card) {
-        ctx.log(`${c.card ?? 'Another card'} is running, not ${card}.`);
-        return 1;
+    const found = pickCancel(workspaceLocks(ctx.configDir), readCurrent(ctx.configDir), card);
+    if (typeof found === 'string') {
+        ctx.log(found);
+        return found.startsWith('More than one') ? 2 : card ? 1 : 0;
     }
-    await cancelCurrent(ctx, c, realDeps(ctx));
+    await cancelCurrent(ctx, found, realDeps(ctx));
     return 0;
 });
 const retry = guard(async (args, ctx) => {
@@ -425,7 +452,7 @@ const retry = guard(async (args, ctx) => {
     const id = p.positionals[0]?.toUpperCase();
     if (p.positionals.length !== 1 || !CARD_ID.test(id))
         return usageError('retry', ctx, 'Give one card id like ENG-12.');
-    if (liveCurrent(ctx.configDir)?.card === id) {
+    if (liveRuns(ctx.configDir).some((c) => c.card === id)) {
         ctx.log(`${id} is running now. vsf agents cancel ${id} first.`);
         return 1;
     }
@@ -495,7 +522,7 @@ const runs = guard(async (args, ctx) => {
     }
     if (!entries.length)
         ctx.log('No runs yet.');
-    const live = liveCurrent(ctx.configDir);
+    const live = liveRuns(ctx.configDir);
     for (const e of entries)
         ctx.log(formatRunLine(e, Date.now(), live));
     return 0;
@@ -529,7 +556,7 @@ const show = guard(async (args, ctx) => {
         return 0;
     }
     ctx.log(`${latest.card}  ${latest.title}`);
-    ctx.log(`Workflow ${latest.workflow}, ${isInterrupted(all[0], liveCurrent(ctx.configDir)) ? 'interrupted' : latest.outcome}${latest.prUrl ? `, PR ${latest.prUrl}` : ''}`);
+    ctx.log(`Workflow ${latest.workflow}, ${isInterrupted(all[0], liveRuns(ctx.configDir)) ? 'interrupted' : latest.outcome}${latest.prUrl ? `, PR ${latest.prUrl}` : ''}`);
     if (labels)
         ctx.log(`Labels: ${labels.join(', ') || 'none'}`);
     for (const s of latest.steps) {
@@ -645,10 +672,10 @@ const clean = guard(async (args, ctx) => {
     if (ms === null)
         return usageError('clean', ctx, `${age} is not an age. Use a number of days or hours, like 14d or 36h.`);
     const cutoff = Date.now() - ms;
-    const live = liveCurrent(ctx.configDir);
+    const live = new Set(liveRuns(ctx.configDir).map((c) => c.card));
     const wtRoot = join(agentsDir(ctx.configDir), 'worktrees');
     const worktrees = (existsSync(wtRoot) ? readdirSync(wtRoot) : [])
-        .filter((card) => card !== live?.card)
+        .filter((card) => !live.has(card))
         .filter((card) => {
         const record = listRuns(ctx.configDir, card)[0]?.record;
         const ended = record?.endedAt ? Date.parse(record.endedAt) : mtime(join(wtRoot, card));
@@ -656,7 +683,7 @@ const clean = guard(async (args, ctx) => {
     })
         .map((card) => join(wtRoot, card));
     const old = listRuns(ctx.configDir).filter((e) => {
-        if (e.record?.outcome === 'running' && e.card === live?.card)
+        if (e.record?.outcome === 'running' && live.has(e.card))
             return false;
         return (e.record?.endedAt ? Date.parse(e.record.endedAt) : mtime(e.dir)) < cutoff;
     });
@@ -686,12 +713,17 @@ const clean = guard(async (args, ctx) => {
     ctx.log(`Removed ${plural(worktrees.length, 'worktree')} and ${plural(old.length, 'run')}.`);
     return 0;
 });
-// Internal: the runner (launchd or systemd) runs this every minute.
-const tickCmd = async (_args, ctx) => {
+// Internal: the runner (launchd or systemd) runs this every minute, and it
+// starts itself with --card or --schedule for each run, one per workspace.
+const tickCmd = async (args, ctx) => {
     const stamped = (l) => ctx.log(`${new Date().toISOString()} ${l}`);
     try {
+        const { values } = parseArgs({ args, options: { card: { type: 'string' }, workflow: { type: 'string' }, schedule: { type: 'string' } }, strict: true });
         const config = readAgentsConfig(ctx.configDir);
-        return await tick({ configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand });
+        const rc = { configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand };
+        if (values.card || values.workflow)
+            return await tick(rc, values.card?.toUpperCase(), { workflow: values.workflow, schedule: values.schedule, child: true });
+        return await dispatch(rc, { reload: () => readAgentsConfig(ctx.configDir) });
     }
     catch (err) {
         stamped(`Could not run the check: ${err.message}`);
@@ -734,8 +766,8 @@ export async function controlChecks(ctx) {
             ? { name: 'runner program', status: 'fail', detail: `runner points at a missing ${missing[0]}`, fix: 'vsf agents restart' }
             : { name: 'runner program', status: 'ok', detail: 'found' });
     }
-    const c = readCurrent(ctx.configDir);
-    if (c && !ours(c.pid))
+    const locks = [readCurrent(ctx.configDir), ...workspaceLocks(ctx.configDir)];
+    if (locks.some((c) => c && !ours(c.pid)))
         checks.push({ name: 'stale lock', status: 'warn', detail: 'a stale lock from a run that died', fix: 'vsf agents cancel' });
     if (existsSync(logPath(ctx.configDir))) {
         const { count, last } = scanRunnerErrors(readLog(ctx.configDir), Date.now());

package/dist/index.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { AGENTS, AGENT_FILE, STEPS, TEMPLATES, isProducer, agentFolders, agentsDir, describeSteps, describeTrigger, describeTriggers, describeWorkflow, stepEnabled, stepId, visibleAgents, readAgentsConfig, writeAgentsConfig, DEFAULTS } from "./config.js";
+import { AGENTS, AGENT_FILE, STEPS, TEMPLATES, isProducer, agentFolders, agentsDir, describeSteps, describeTrigger, describeTriggers, describeWorkflow, stepEnabled, stepId, visibleAgents, readAgentsConfig, writeAgentsConfig, workspaceOf, DEFAULTS, DEFAULT_WORKSPACE, WORKSPACE_NAME } from "./config.js";
 import { controlChecks, controlCommands, controlUsage } from "./control.js";
 import { keyStore, looksLikeLinearKey, readLinearKey, readSecret, storeLinearKey, storeSecret } from "./secrets.js";
 import { TRACKERS } from "./tracker.js";
@@ -14,7 +14,7 @@ import { trackersInUse } from "./control.js";
 import { runnerService } from "./service.js";
 import { initProfile, profileChecks, profileDir, readRules, renderClaudeSettings, CLAUDE_SETTINGS, RULES_FILE } from "./profile.js";
 import { createLinear } from "./linear.js";
-import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, renameKey, sameTrigger, validateAgentFolder, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
+import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, projectProblems, renameKey, sameTrigger, validateAgentFolder, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
 import { findRepos } from "./repos.js";
 import { defaultBranch, sh } from "./git.js";
@@ -239,7 +239,8 @@ async function promptProject(ui, config, current = {}, edit = false, allowExisti
 const describeProject = (config, name) => {
     const p = config.projects[name];
     const used = workflowsUsing(config, name);
-    return `${name}  ${tilde(p.path)}, PRs into ${p.base ?? 'the default branch'}, ${used.length ? `used by ${used.join(', ')}` : 'not used by any workflow'}`;
+    const where = [p.workspace ? `workspace ${p.workspace}` : '', p.match?.length ? `matches ${p.match.join(', ')}` : ''].filter(Boolean);
+    return `${name}  ${tilde(p.path)}, PRs into ${p.base ?? 'the default branch'}, ${where.map((w) => `${w}, `).join('')}${used.length ? `used by ${used.join(', ')}` : 'not used by any workflow'}`;
 };
 // Named local repos the workflows run in. Triggers point at them by name.
 async function setupProjects(ui, config, log) {
@@ -366,11 +367,14 @@ const USAGE = [
     ['workflow rm NAME [--yes]', 'Delete a workflow'],
     ['workflow move NAME (--first | --last | --before OTHER | --after OTHER)', 'Change the match order'],
     ['projects [--json]', 'List projects'],
-    ['project add [NAME] [--path P] [--base B]', 'Add a project; prompts for what is missing'],
+    ['project add [NAME] [--path P] [--base B] [--workspace W] [--match NAME]...', 'Add a project; prompts for what is missing. --match routes cards of that tracker project here, whatever the workflow says'],
     ['project show NAME [--json]', 'Show one project'],
-    ['project edit NAME [--path P] [--base B]', 'Change a project; no flags asks'],
+    ['project edit NAME [--path P] [--base B] [--workspace W] [--match NAME]...', 'Change a project; no flags asks. An empty --workspace or --match clears it'],
     ['project rename OLD NEW', 'Rename a project and the workflows that use it'],
     ['project rm NAME [--yes]', 'Delete a project nothing uses'],
+    ['workspace add NAME --root DIR [--context FILE]', 'Add a workspace: a folder of repos with its own run queue. Steps carry FILE, or DIR/CONTEXT.md'],
+    ['workspace list [--json]', 'List workspaces and their projects'],
+    ['workspace rm NAME', 'Delete a workspace no project uses'],
     ['homes [--json]', 'Show where the agents are linked'],
     ['link DIR [--claude | --codex]', 'Link the agents into a config folder'],
     ['unlink DIR', 'Remove the agents from a config folder'],
@@ -789,9 +793,31 @@ function pickProject(config, input, ctx) {
     }
     return r.name;
 }
+const PROJECT_FLAGS = { path: { type: 'string' }, base: { type: 'string' }, workspace: { type: 'string' }, match: { type: 'string', multiple: true } };
+// Applies --workspace and --match to a project. An empty value clears either.
+// Returns a complaint when the workspace or a match does not fit.
+function applyWorkspaceFlags(config, name, project, v) {
+    if (v.workspace !== undefined) {
+        const ws = String(v.workspace).trim();
+        if (ws && ws !== DEFAULT_WORKSPACE && !config.workspaces[ws])
+            return `No workspace named ${ws}. vsf agents workspace add creates it.`;
+        if (ws && ws !== DEFAULT_WORKSPACE)
+            project.workspace = ws;
+        else
+            delete project.workspace;
+    }
+    if (v.match !== undefined) {
+        const match = v.match.map((m) => m.trim()).filter(Boolean);
+        if (match.length)
+            project.match = match;
+        else
+            delete project.match;
+    }
+    return projectProblems({ ...config.projects, [name]: project }, config.workspaces)[0] ?? null;
+}
 const projectSubs = {
     async add(args, ctx) {
-        const p = begin('project add', args, { path: { type: 'string' }, base: { type: 'string' } }, ctx);
+        const p = begin('project add', args, PROJECT_FLAGS, ctx);
         if (typeof p === 'number')
             return p;
         if (p.positionals.length > 1) {
@@ -838,6 +864,11 @@ const projectSubs = {
             name = r.name;
             project = r.project;
         }
+        const bad = applyWorkspaceFlags(config, name, project, p.values);
+        if (bad) {
+            ctx.log(bad);
+            return 1;
+        }
         config.projects[name] = project;
         save(ctx, config);
         ctx.log(`Project ${name}: ${tilde(project.path)}${project.base ? `, PRs into ${project.base}` : ''}`);
@@ -861,12 +892,15 @@ const projectSubs = {
             ctx.log(`Project ${name}`);
             ctx.log(`Path: ${tilde(proj.path)}`);
             ctx.log(`PRs into: ${proj.base ?? 'the default branch'}`);
+            ctx.log(`Workspace: ${workspaceOf(proj)}`);
+            if (proj.match?.length)
+                ctx.log(`Matches: ${proj.match.join(', ')}`);
             ctx.log(`Used by: ${used.length ? used.join(', ') : 'no workflows'}`);
         }
         return 0;
     },
     async edit(args, ctx) {
-        const p = begin('project edit', args, { path: { type: 'string' }, base: { type: 'string' } }, ctx);
+        const p = begin('project edit', args, PROJECT_FLAGS, ctx);
         if (typeof p === 'number')
             return p;
         if (!needArgs(p, 1, 'project edit', ctx))
@@ -877,9 +911,9 @@ const projectSubs = {
             return 1;
         const current = config.projects[name];
         const v = p.values;
-        if (v.path === undefined && v.base === undefined) {
+        if (v.path === undefined && v.base === undefined && v.workspace === undefined && v.match === undefined) {
             if (!interactive()) {
-                ctx.log('Nothing to change. Give --path or --base, or run this in a terminal to be asked.');
+                ctx.log('Nothing to change. Give --path, --base, --workspace or --match, or run this in a terminal to be asked.');
                 ctx.log(usageOf('project edit'));
                 return 2;
             }
@@ -887,7 +921,8 @@ const projectSubs = {
         }
         else {
             const path = v.path !== undefined ? resolve(expandHome(v.path)) : current.path;
-            if (!isRepo(path)) {
+            // Only a new path needs checking; a workspace or match change keeps the repo.
+            if (v.path !== undefined && !isRepo(path)) {
                 ctx.log(`${tilde(path)} is not a git repository.`);
                 return 1;
             }
@@ -899,6 +934,11 @@ const projectSubs = {
                 else
                     delete next.base;
             }
+            const bad = applyWorkspaceFlags(config, name, next, v);
+            if (bad) {
+                ctx.log(bad);
+                return 1;
+            }
             config.projects[name] = next;
         }
         save(ctx, config);
@@ -960,6 +1000,87 @@ const projectSubs = {
         return 0;
     },
 };
+// ---- workspaces ----
+const projectsIn = (config, ws) => Object.entries(config.projects).filter(([, p]) => workspaceOf(p) === ws).map(([n]) => n);
+const workspaceSubs = {
+    async add(args, ctx) {
+        const p = begin('workspace add', args, { root: { type: 'string' }, context: { type: 'string' } }, ctx);
+        if (typeof p === 'number')
+            return p;
+        if (!needArgs(p, 1, 'workspace add', ctx))
+            return 2;
+        const name = p.positionals[0].trim();
+        if (!WORKSPACE_NAME.test(name)) {
+            ctx.log('A workspace name is letters, digits, dashes and underscores.');
+            return 2;
+        }
+        if (!p.values.root) {
+            ctx.log('Missing --root.');
+            ctx.log(usageOf('workspace add'));
+            return 2;
+        }
+        const config = readAgentsConfig(ctx.configDir);
+        if (config.workspaces[name]) {
+            ctx.log(`A workspace named ${name} already exists.`);
+            return 1;
+        }
+        const root = resolve(expandHome(p.values.root));
+        if (!existsSync(root)) {
+            ctx.log(`${tilde(root)} does not exist.`);
+            return 1;
+        }
+        const context = p.values.context ? resolve(root, expandHome(p.values.context)) : undefined;
+        if (context && !existsSync(context)) {
+            ctx.log(`${tilde(context)} does not exist.`);
+            return 1;
+        }
+        config.workspaces[name] = { root, ...(context ? { context } : {}) };
+        save(ctx, config);
+        ctx.log(`Workspace ${name}: ${tilde(root)}. vsf agents project edit P --workspace ${name} puts a project in it.`);
+        return 0;
+    },
+    async list(args, ctx) {
+        const p = begin('workspace list', args, { json: { type: 'boolean' } }, ctx);
+        if (typeof p === 'number')
+            return p;
+        const config = readAgentsConfig(ctx.configDir);
+        const names = [...new Set([...Object.keys(config.workspaces), ...Object.values(config.projects).map(workspaceOf)])];
+        if (p.values.json) {
+            out(ctx, names.map((name) => ({ name, ...config.workspaces[name], projects: projectsIn(config, name) })));
+            return 0;
+        }
+        if (!names.length)
+            ctx.log('No workspaces yet. Every project runs in the default one; vsf agents workspace add creates another.');
+        for (const name of names) {
+            const w = config.workspaces[name];
+            const projects = projectsIn(config, name);
+            ctx.log(`${name}  ${w ? tilde(w.root) : 'no root'}${w?.context ? `, context ${tilde(w.context)}` : ''}, ${projects.length ? projects.join(', ') : 'no projects'}`);
+        }
+        return 0;
+    },
+    async rm(args, ctx) {
+        const p = begin('workspace rm', args, {}, ctx);
+        if (typeof p === 'number')
+            return p;
+        if (!needArgs(p, 1, 'workspace rm', ctx))
+            return 2;
+        const config = readAgentsConfig(ctx.configDir);
+        const name = p.positionals[0].trim();
+        if (!config.workspaces[name]) {
+            ctx.log(`No workspace named ${name}.`);
+            return 1;
+        }
+        const used = projectsIn(config, name);
+        if (used.length) {
+            ctx.log(`Used by ${used.join(', ')}. Move those projects first: vsf agents project edit P --workspace OTHER.`);
+            return 1;
+        }
+        delete config.workspaces[name];
+        save(ctx, config);
+        ctx.log(`Deleted workspace ${name}.`);
+        return 0;
+    },
+};
 // ---- homes ----
 // Per enabled agent: ours, taken by something else, or missing.
 function homeReport(config, h) {
@@ -1242,6 +1363,7 @@ const agents = {
             return 0;
         },
         project: (args, ctx) => group('project', projectSubs, args, ctx),
+        workspace: (args, ctx) => group('workspace', workspaceSubs, args, ctx),
         homes: homeCommands.homes,
         link: homeCommands.link,
         unlink: homeCommands.unlink,

package/dist/manage.d.ts

@@ -18,4 +18,5 @@ export type Place = {
 };
 export declare function moveKey<T>(record: Record<string, T>, name: string, place: Place): Record<string, T>;
 export declare const workflowsUsing: (config: Pick<AgentsConfig, "workflows">, project: string) => string[];
-export declare function validateConfig(value: unknown, saved?: Pick<AgentsConfig, 'projects' | 'workflows'>): string[];
+export declare function projectProblems(projects: AgentsConfig['projects'], workspaces: AgentsConfig['workspaces']): string[];
+export declare function validateConfig(value: unknown, saved?: Pick<AgentsConfig, 'projects' | 'workflows'> & Partial<Pick<AgentsConfig, 'workspaces'>>): string[];

package/dist/manage.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { AGENTS, AGENT_FILE, OUTPUTS, STEP_ID, isBuiltin, readAgentFolder, stepFile, describeTrigger, triggerSpec } from "./config.js";
+import { AGENTS, AGENT_FILE, DEFAULT_WORKSPACE, OUTPUTS, STEP_ID, WORKSPACE_NAME, isBuiltin, readAgentFolder, stepFile, describeTrigger, triggerSpec } from "./config.js";
 import { parseCron } from "./cron.js";
 const isInt = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
 // The line a step's prompt must ask for, so the runner can read the result.
@@ -185,6 +185,34 @@ export function moveKey(record, name, place) {
 }
 export const workflowsUsing = (config, project) => Object.entries(config.workflows).filter(([, w]) => w.project === project).map(([n]) => n);
 const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// What is wrong with the projects' workspaces and matches: a workspace that
+// does not exist, or a tracker project name two projects both claim.
+export function projectProblems(projects, workspaces) {
+    const problems = [];
+    const claimed = new Map();
+    for (const [name, p] of Object.entries(projects)) {
+        if (!isObj(p))
+            continue;
+        if (p.workspace !== undefined && (typeof p.workspace !== 'string' || (p.workspace !== DEFAULT_WORKSPACE && !Object.hasOwn(workspaces, p.workspace)))) {
+            problems.push(`Project ${name}: workspace ${String(p.workspace)} does not exist. vsf agents workspace add creates it.`);
+        }
+        if (p.match === undefined)
+            continue;
+        if (!Array.isArray(p.match) || p.match.some((m) => typeof m !== 'string' || !m.trim())) {
+            problems.push(`Project ${name}: match must list tracker project names.`);
+            continue;
+        }
+        for (const m of p.match) {
+            const key = m.trim().toLowerCase();
+            const other = claimed.get(key);
+            if (other && other !== name)
+                problems.push(`Projects ${other} and ${name} both match ${m}.`);
+            else
+                claimed.set(key, name);
+        }
+    }
+    return problems;
+}
 // Everything wrong with a whole agents config, e.g. one edited by hand.
 // `saved` is the config on disk: only what the write changes is checked, so a
 // moved folder or a retired agent elsewhere does not block an unrelated edit.
@@ -209,6 +237,23 @@ export function validateConfig(value, saved) {
         else if (saved?.projects?.[name]?.path !== p.path && !existsSync(join(p.path, '.git')))
             problems.push(`Project ${name}: ${p.path} is not a git repository.`);
     }
+    // Older configs have no workspaces: every project is in the default one.
+    const workspaces = value.workspaces === undefined ? {} : isObj(value.workspaces) ? value.workspaces : null;
+    if (!workspaces)
+        problems.push('workspaces must be an object.');
+    for (const [name, w] of Object.entries(workspaces ?? {})) {
+        if (!WORKSPACE_NAME.test(name))
+            problems.push(`Workspace ${name} must be letters, digits, dashes and underscores.`);
+        if (!isObj(w) || typeof w.root !== 'string' || !w.root)
+            problems.push(`Workspace ${name} needs a root folder.`);
+        else {
+            if (saved?.workspaces?.[name]?.root !== w.root && !existsSync(w.root))
+                problems.push(`Workspace ${name}: ${w.root} does not exist.`);
+            if (w.context !== undefined && typeof w.context !== 'string')
+                problems.push(`Workspace ${name} context must be a file name.`);
+        }
+    }
+    problems.push(...projectProblems((projects ?? {}), (workspaces ?? {})));
     if (!Array.isArray(value.enabled) || value.enabled.some((a) => typeof a !== 'string' || !(a in AGENTS)))
         problems.push(`enabled must list agents from: ${Object.keys(AGENTS).join(', ')}.`);
     if (value.commits !== undefined && (!isObj(value.commits) || Object.entries(value.commits).some(([k, v]) => !['signOff', 'dropAiTrailers'].includes(k) || typeof v !== 'boolean')))

package/dist/runner.d.ts

@@ -16,15 +16,38 @@ type Job = {
     card: Card;
     trigger: Trigger;
     workflow: string;
+    workspace: string;
 };
 export declare function cronCard(workflow: string, task: string, at: Date): Card;
-export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: {
+export interface JobQuery {
+    only?: string;
+    workflow?: string;
+    schedule?: string;
     force?: boolean;
+    busy?: Set<string>;
+    skip?: Set<string>;
+    limit?: number;
     now?: Date;
-}): Promise<Job | null>;
+}
+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 tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
     from?: string;
+    schedule?: string;
+    child?: boolean;
 }): Promise<number>;
+export interface ChildRun {
+    kill(signal: NodeJS.Signals): unknown;
+    once(event: 'exit' | 'error', listener: (err?: Error) => void): unknown;
+    exitCode: number | null;
+}
+export interface DispatchDeps {
+    start: (args: string[]) => ChildRun;
+    waitMs: number;
+    reload?: () => AgentsConfig;
+}
+export declare const jobArgs: (job: Job) => string[];
+export declare function dispatch(rc: RunContext, over?: Partial<DispatchDeps>): Promise<number>;
 export {};

package/dist/runner.js

@@ -1,14 +1,15 @@
+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, resolveStep, stepId, stepIdLabel } from "./config.js";
+import { 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 { noTracker } from "./tracker.js";
 import { recall, syncMemory, vaultPath } from "./memory.js";
 import { claudeSettingsFile, readRules, rulesSection } from "./profile.js";
-import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun, readCronState, writeCronState } from "./state.js";
+import { acquireWorkspace, clearCurrent, heldByOther, isPaused, liveRuns, readCurrent, readPending, releaseWorkspace, writeCurrent, writePending, writeRun, writeWorkspace, readCronState, writeCronState } from "./state.js";
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
 class Park extends Error {
 }
@@ -55,13 +56,14 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const writeBack = isCardTrigger(trigger) ? (workflow.writeBack ?? {}) : {};
     const labelsOn = writeBack.labels !== false;
     const startedAt = new Date().toISOString();
-    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', startedAt };
+    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 };
     active = { record, runDir };
     const save = () => writeRun(runDir, record);
     save();
     let loops = 0;
-    // The lock tells status and cancel what is running.
-    const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir, source: trigger.source });
+    // The workspace lock tells status and cancel what is running.
+    const mark = (step) => writeWorkspace(rc.configDir, workspace, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir, source: trigger.source });
     // Written before the first tracker call, so a cancel always knows the card.
     mark('Starting');
     const begin = (def) => {
@@ -157,7 +159,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         const pulled = syncMemory(rc.selfCommand, rc.configDir);
         if (pulled)
             say(pulled);
-        const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : '', rules].filter(Boolean).join('\n\n');
+        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}`);
@@ -343,7 +346,9 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             say(shared);
     }
 }
-// A scheduled run's stand-in for a card: the task, on a branch of its own.
+// 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.
+const jobWorkspace = (config, workflow, card) => workspaceOf(resolveProject(config, workflow, card)?.project);
 export function cronCard(workflow, task, at) {
     const stamp = at.toISOString().slice(0, 16).replace(/[-:T]/g, '');
     const slug = workflow.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'cron';
@@ -360,21 +365,24 @@ export function cronCard(workflow, task, at) {
     };
 }
 const cronKey = (workflow, schedule) => `${workflow} ${schedule}`;
-// The first job waiting on any workflow's triggers, in workflow order: a card
-// carrying a trigger label, or a schedule that came due since it last fired.
-// A schedule seen for the first time starts counting from now. With a card,
-// only that card is considered; with a workflow name, only that workflow, and
-// `force` fires its schedule now.
-export async function nextJob(rc, only, workflowName, opts = {}) {
-    const now = opts.now ?? new Date();
-    const workflows = Object.entries(rc.config.workflows).filter(([name]) => !workflowName || name === workflowName);
+// 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
+// schedule that came due since it last fired. A schedule seen for the first
+// time starts counting from now, and one whose workspace is busy keeps waiting
+// without being marked as fired.
+export async function findJobs(rc, q = {}) {
+    const now = q.now ?? new Date();
+    const limit = q.limit ?? Infinity;
+    const taken = new Set(q.busy ?? []);
+    const out = [];
+    const workflows = Object.entries(rc.config.workflows).filter(([name]) => !q.workflow || name === q.workflow);
     let pinned = null;
-    if (only) {
-        const team = only.split('-')[0].toUpperCase();
+    if (q.only) {
+        const team = q.only.split('-')[0].toUpperCase();
         const sources = [...new Set(workflows.flatMap(([, w]) => w.triggers.filter(isCardTrigger).filter((t) => t.team === team).map((t) => t.source)))];
         for (const source of sources) {
             try {
-                pinned = { card: await rc.trackers(source).card(only), source };
+                pinned = { card: await rc.trackers(source).card(q.only), source };
                 break;
             }
             catch (err) {
@@ -383,32 +391,50 @@ export async function nextJob(rc, only, workflowName, opts = {}) {
             }
         }
         if (!pinned)
-            return null;
+            return [];
     }
     const cron = readCronState(rc.configDir);
     let cronChanged = false;
+    const take = (job, workspace) => {
+        taken.add(workspace);
+        out.push({ ...job, workspace });
+        return out.length >= limit;
+    };
     try {
         for (const [name, workflow] of workflows) {
             for (const trigger of workflow.triggers) {
                 if (!isCardTrigger(trigger)) {
-                    const schedule = only ? null : parseCron(trigger.schedule);
+                    const schedule = q.only || (q.schedule && q.schedule !== trigger.schedule) ? null : parseCron(trigger.schedule);
                     if (!schedule)
                         continue;
                     const key = cronKey(name, trigger.schedule);
                     const last = cron[key];
-                    const due = opts.force ? now : last ? lastDue(schedule, new Date(last), now) : null;
-                    if (!last || due) {
+                    if (!last) {
                         cron[key] = now.toISOString();
                         cronChanged = true;
                     }
-                    if (due)
-                        return { card: cronCard(name, trigger.task, due), trigger, workflow: name };
+                    const due = q.force ? now : last ? lastDue(schedule, new Date(last), now) : null;
+                    if (!due)
+                        continue;
+                    const card = cronCard(name, trigger.task, due);
+                    const workspace = jobWorkspace(rc.config, workflow, card);
+                    if (taken.has(workspace))
+                        continue;
+                    cron[key] = now.toISOString();
+                    cronChanged = true;
+                    if (take({ card, trigger, workflow: name }, workspace))
+                        return out;
                     continue;
                 }
+                // A run for one schedule takes no labelled cards.
+                if (q.schedule)
+                    continue;
                 // A pinned card may have lost its label (a parked card re-run by hand), so match by team.
                 if (pinned) {
-                    if (pinned.source === trigger.source && pinned.card.teamKey === trigger.team)
-                        return { card: pinned.card, trigger, workflow: name };
+                    if (pinned.source === trigger.source && pinned.card.teamKey === trigger.team) {
+                        take({ card: pinned.card, trigger, workflow: name }, jobWorkspace(rc.config, workflow, pinned.card));
+                        return out;
+                    }
                     continue;
                 }
                 let cards;
@@ -420,18 +446,33 @@ export async function nextJob(rc, only, workflowName, opts = {}) {
                     rc.log(`Could not check ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} for ${trigger.team} + ${trigger.label} (${err.message}). Trying again next minute.`);
                     continue;
                 }
-                const card = cards.find((c) => c.teamKey === trigger.team && c.labels.includes(trigger.label));
-                if (card)
-                    return { card, trigger, workflow: name };
+                for (const card of cards) {
+                    if (card.teamKey !== trigger.team || !card.labels.includes(trigger.label))
+                        continue;
+                    // A card already taken this pass, by an earlier trigger, is not run twice.
+                    if (q.skip?.has(card.identifier) || out.some((j) => j.card.identifier === card.identifier))
+                        continue;
+                    const workspace = jobWorkspace(rc.config, workflow, card);
+                    if (taken.has(workspace))
+                        continue;
+                    if (take({ card, trigger, workflow: name }, workspace))
+                        return out;
+                }
             }
         }
-        return null;
+        return out;
     }
     finally {
         if (cronChanged)
             writeCronState(rc.configDir, cron);
     }
 }
+// The first job waiting, as findJobs finds it. With a card, only that card is
+// considered; with a workflow name, only that workflow, and `force` fires its
+// schedule now.
+export async function nextJob(rc, only, workflowName, opts = {}) {
+    return (await findJobs(rc, { ...opts, only, workflow: workflowName, limit: 1 }))[0] ?? null;
+}
 // Retries tracker writes that failed while parking. Never throws.
 async function flushPending(rc) {
     const left = [];
@@ -482,21 +523,20 @@ function queueCancel(configDir, cardId, comment, source = 'linear') {
         // nothing more to do
     }
 }
-// One pass for the background runner. A lock keeps two passes from working at once.
+// 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
+// started, which leaves the pending writes to it.
 export async function tick(rc, only, opts = {}) {
-    const held = readCurrent(rc.configDir);
-    const booted = bootTime();
-    // A lock from before the last boot cannot be a live run, whatever its pid is now.
-    const fromBeforeBoot = !!(held?.startedAt && booted && new Date(held.startedAt) < booted);
-    if (held && held.pid !== process.pid && !fromBeforeBoot && ours(held.pid)) {
-        if (only)
-            rc.log(`The runner is busy with ${held.card ?? 'a check'}. Try again when it finishes.`);
-        return only ? 1 : 0;
-    }
-    writeCurrent(rc.configDir, { pid: process.pid, startedAt: new Date().toISOString() });
-    // A stop (Ctrl+C, launchd, shutdown) ends the agents, marks the run, and
-    // takes the working label off the card so it is never left stuck.
+    let held = null;
+    // A stop (Ctrl+C, the dispatcher, launchd, shutdown) ends the agents, marks
+    // the run, and takes the working label off the card so it is never left stuck.
+    // The dispatcher and the service can both signal, so a second one is ignored.
+    let stopping = false;
     const onSignal = async () => {
+        if (stopping)
+            return;
+        stopping = true;
         await stopAgents();
         const running = active && active.record.outcome === 'running' ? active : null;
         if (active) {
@@ -519,18 +559,21 @@ export async function tick(rc, only, opts = {}) {
             if (!finished)
                 queueCancel(rc.configDir, card, `**Cancelled.** Add \`${trigger}\` again to restart.`, source);
         }
-        clearCurrent(rc.configDir);
+        if (held)
+            releaseWorkspace(rc.configDir, held);
         process.exit(143);
     };
-    process.once('SIGTERM', onSignal);
-    process.once('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
     try {
-        await flushPending(rc);
+        if (!opts.child)
+            await flushPending(rc);
         if (!only && isPaused(rc.configDir))
             return 0;
         let job;
         try {
-            job = await nextJob(rc, only, opts.workflow, { force: !!opts.workflow && !only });
+            const busy = only ? undefined : new Set(liveRuns(rc.configDir).filter((c) => c.pid !== process.pid).map((c) => workspaceOf(c)));
+            job = await nextJob(rc, only, opts.workflow, { force: !!opts.workflow && !only, schedule: opts.schedule, busy });
         }
         catch (err) {
             rc.log(`Could not read ${only} (${err.message}).`);
@@ -542,8 +585,8 @@ export async function tick(rc, only, opts = {}) {
             return only ? 1 : 0;
         }
         const workflow = rc.config.workflows[job.workflow];
-        const project = rc.config.projects[workflow.project];
-        if (!project) {
+        const resolved = resolveProject(rc.config, workflow, job.card);
+        if (!resolved) {
             rc.log(`Workflow ${job.workflow} points at a missing project ${workflow.project}. Run vsf agents workflow edit to fix it.`);
             return 1;
         }
@@ -551,13 +594,109 @@ export async function tick(rc, only, opts = {}) {
             rc.log(`Workflow ${job.workflow} has no ${stepIdLabel(opts.from)} step.`);
             return 2;
         }
-        const outcome = await runCard(job.card, job.trigger, job.workflow, workflow, project, rc, { from: opts.from });
+        const busy = acquireWorkspace(rc.configDir, job.workspace, { pid: process.pid, card: job.card.identifier, startedAt: new Date().toISOString() });
+        if (busy) {
+            rc.log(`Workspace ${job.workspace} is busy with ${busy.card ?? 'a check'}. Try again when it finishes.`);
+            return 1;
+        }
+        held = job.workspace;
+        const outcome = await runCard(job.card, job.trigger, job.workflow, workflow, resolved.project, rc, { from: opts.from });
         return outcome === 'verified' ? 0 : 1;
     }
     catch (err) {
         rc.log(`Error: ${err.message}`);
         return 1;
     }
+    finally {
+        process.off('SIGTERM', onSignal);
+        process.off('SIGINT', onSignal);
+        if (held)
+            releaseWorkspace(rc.configDir, held);
+    }
+}
+// The arguments that make a child tick run exactly this job.
+export const jobArgs = (job) => isCardTrigger(job.trigger) ? ['--card', job.card.identifier, '--workflow', job.workflow] : ['--workflow', job.workflow, '--schedule', job.trigger.schedule];
+const realDeps = (rc) => ({
+    start: (args) => {
+        const [bin, ...rest] = rc.selfCommand;
+        return spawn(bin, [...rest, 'agents', 'tick', ...args], { stdio: 'inherit' });
+    },
+    waitMs: 60_000,
+});
+// 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
+// per workspace with work waiting, looks again whenever one ends or a minute
+// passes, and returns once nothing runs and nothing waits. runner.lock keeps
+// two dispatchers from working at once.
+export async function dispatch(rc, over = {}) {
+    const deps = { ...realDeps(rc), ...over };
+    const held = readCurrent(rc.configDir);
+    if (held && heldByOther(held))
+        return 0;
+    writeCurrent(rc.configDir, { pid: process.pid, startedAt: new Date().toISOString() });
+    const children = new Map();
+    // When each card was started, so one whose run failed before it took the
+    // trigger label off waits for the next pass instead of starting again at once.
+    const started = new Map();
+    // Ends the wait early when a child exits.
+    let wake = () => { };
+    // A stop ends every run: each child cancels its own card.
+    let stopping = false;
+    const onSignal = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        const exits = [...children.values()].filter((c) => c.exitCode === null).map((c) => new Promise((resolve) => c.once('exit', () => resolve())));
+        for (const c of children.values())
+            c.kill('SIGTERM');
+        await Promise.race([Promise.all(exits), new Promise((resolve) => setTimeout(resolve, 10_000).unref())]);
+        clearCurrent(rc.configDir);
+        process.exit(143);
+    };
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
+    try {
+        for (;;) {
+            if (deps.reload)
+                rc = { ...rc, config: deps.reload() };
+            await flushPending(rc);
+            if (!isPaused(rc.configDir)) {
+                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 })) {
+                    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));
+                    children.set(job.workspace, child);
+                    const ended = () => {
+                        if (children.get(job.workspace) === child)
+                            children.delete(job.workspace);
+                        wake();
+                    };
+                    child.once('exit', ended);
+                    // A program that could not start never exits.
+                    child.once('error', (err) => {
+                        rc.log(`Could not start the run for ${job.card.identifier} (${err?.message ?? 'unknown error'}).`);
+                        ended();
+                    });
+                }
+            }
+            if (!children.size)
+                return 0;
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, deps.waitMs);
+                wake = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            wake = () => { };
+        }
+    }
+    catch (err) {
+        rc.log(`Error: ${err.message}`);
+        return 1;
+    }
     finally {
         process.off('SIGTERM', onSignal);
         process.off('SIGINT', onSignal);

package/dist/state.d.ts

@@ -9,15 +9,24 @@ export interface Current {
     startedAt?: string;
     runDir?: string;
     source?: Trigger['source'];
+    workspace?: string;
 }
 export declare const lockPath: (configDir: string) => string;
-export declare function readCurrent(configDir: string): Current | null;
+export declare const readCurrent: (configDir: string) => Current | null;
 export declare function writeCurrent(configDir: string, current: Current): void;
 export declare const clearCurrent: (configDir: string) => void;
 export declare function alive(pid: number): boolean;
 export declare function ours(pid: number): boolean;
 export declare function bootTime(): Date | null;
 export declare function liveCurrent(configDir: string): Current | null;
+export declare function heldByOther(c: Current): boolean;
+export declare const workspaceLockPath: (configDir: string, workspace: string) => string;
+export declare function acquireWorkspace(configDir: string, workspace: string, current: Omit<Current, 'workspace'>): Current | null;
+export declare function writeWorkspace(configDir: string, workspace: string, current: Omit<Current, 'workspace'>): void;
+export declare const releaseWorkspace: (configDir: string, workspace: string) => void;
+export declare function workspaceLocks(configDir: string): Current[];
+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 Pending {
@@ -51,6 +60,7 @@ export interface RunRecord {
     outcome: Outcome;
     reason?: string;
     prUrl?: string;
+    workspace?: string;
     startedAt: string;
     endedAt?: string;
 }

package/dist/state.js

@@ -3,8 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join } from 'node:path';
 import { agentsDir } from "./config.js";
 export const lockPath = (configDir) => join(agentsDir(configDir), 'runner.lock');
-export function readCurrent(configDir) {
-    const path = lockPath(configDir);
+function readLock(path) {
     if (!existsSync(path))
         return null;
     const text = readFileSync(path, 'utf8').trim();
@@ -16,6 +15,7 @@ export function readCurrent(configDir) {
         return null;
     }
 }
+export const readCurrent = (configDir) => readLock(lockPath(configDir));
 export function writeCurrent(configDir, current) {
     mkdirSync(agentsDir(configDir), { recursive: true });
     writeFileSync(lockPath(configDir), JSON.stringify(current) + '\n');
@@ -44,11 +44,65 @@ export function bootTime() {
     const sec = /sec = (\d+)/.exec(r.stdout ?? '')?.[1];
     return sec ? new Date(Number(sec) * 1000) : null;
 }
-// The live run, or null when nothing runs or the lock is stale.
+// The live dispatcher, or null when none runs or the lock is stale.
 export function liveCurrent(configDir) {
     const c = readCurrent(configDir);
     return c && ours(c.pid) ? c : null;
 }
+// Whether a lock belongs to a live runner other than this process. A lock from
+// before the last boot cannot be a live run, whatever its pid is now.
+export function heldByOther(c) {
+    const booted = bootTime();
+    const fromBeforeBoot = !!(c.startedAt && booted && new Date(c.startedAt) < booted);
+    return c.pid !== process.pid && !fromBeforeBoot && ours(c.pid);
+}
+// One lock per workspace: the run holding its queue.
+const locksDir = (configDir) => join(agentsDir(configDir), 'locks');
+export const workspaceLockPath = (configDir, workspace) => join(locksDir(configDir), `${encodeURIComponent(workspace)}.json`);
+// Takes a workspace's queue for this process. Returns null once taken, or the
+// live run that holds it. A stale lock is removed and the take tried again.
+// The file is created exclusively, so two runners never both take it.
+export function acquireWorkspace(configDir, workspace, current) {
+    mkdirSync(locksDir(configDir), { recursive: true });
+    const path = workspaceLockPath(configDir, workspace);
+    for (let attempt = 0;; attempt++) {
+        try {
+            writeFileSync(path, JSON.stringify({ ...current, workspace }) + '\n', { flag: 'wx' });
+            return null;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        const held = readLock(path);
+        if (held && heldByOther(held))
+            return held;
+        if (attempt)
+            return held ?? { pid: 0, workspace };
+        rmSync(path, { force: true });
+    }
+}
+// Updates the lock of a queue this process holds.
+export function writeWorkspace(configDir, workspace, current) {
+    mkdirSync(locksDir(configDir), { recursive: true });
+    writeFileSync(workspaceLockPath(configDir, workspace), JSON.stringify({ ...current, workspace }) + '\n');
+}
+export const releaseWorkspace = (configDir, workspace) => rmSync(workspaceLockPath(configDir, workspace), { force: true });
+// Every workspace lock on disk, stale ones included.
+export function workspaceLocks(configDir) {
+    let names;
+    try {
+        names = readdirSync(locksDir(configDir)).filter((n) => n.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+    return names.map((n) => readLock(join(locksDir(configDir), n))).filter((c) => !!c);
+}
+// The card runs going on now, one per busy workspace.
+export const liveRuns = (configDir) => workspaceLocks(configDir).filter((c) => ours(c.pid));
+// Releases the lock a run left behind, wherever it lives.
+export const clearLock = (configDir, c) => (c.workspace ? releaseWorkspace(configDir, c.workspace) : clearCurrent(configDir));
 // Paused: the runner stays loaded but picks up no new cards.
 const pausePath = (configDir) => join(agentsDir(configDir), 'paused');
 export const isPaused = (configDir) => existsSync(pausePath(configDir));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Agents for Claude Code and Codex that plan, build and QA Linear cards, chained and run in the background.",
   "license": "Apache-2.0",
   "repository": {