@voidlabs.gg/voidshift-agents 0.5.1 → 0.7.0

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) => {
@@ -109,7 +111,17 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         await linear.comment(card, `${PLAN_HEADING}\n\n${planToPost}`);
         planToPost = null;
     };
-    async function park(reason) {
+    const ping = async (kind, reason) => {
+        if (!rc.notify)
+            return;
+        try {
+            await rc.notify({ kind, card: card.identifier, title: card.title, workflow: workflowName, url: card.url || undefined, prUrl: record.prUrl, reason });
+        }
+        catch (err) {
+            say(`discord: ${err.message}`);
+        }
+    };
+    async function park(reason, kind = 'parked') {
         say(`parked: ${reason}`);
         const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${label}\` again to retry.`;
         const add = labelsOn ? [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])] : [];
@@ -121,13 +133,15 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             await endLabels(LABELS.parked, loops || undefined);
         }
         catch (err) {
-            if (!isCardTrigger(trigger))
-                return done('parked', reason);
-            say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
-            // An empty comment is skipped on retry, so it is not posted twice.
-            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
+            if (isCardTrigger(trigger)) {
+                say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
+                // An empty comment is skipped on retry, so it is not posted twice.
+                writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: labelsOn, source: trigger.source }]);
+            }
         }
-        return done('parked', reason);
+        const outcome = done('parked', reason);
+        await ping(kind, reason);
+        return outcome;
     }
     try {
         if (!existsSync(join(project.path, '.git')))
@@ -157,7 +171,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}`);
@@ -328,12 +343,12 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${!moved ? `\n\n(No "${state}" state on this team, so the card was not moved.)` : ''}`);
         }
         say('verified');
-        return done('verified');
+        done('verified');
     }
     catch (err) {
         if (err instanceof Park)
             return park(err.message);
-        return park(`Something went wrong: ${err.message}`);
+        return park(`Something went wrong: ${err.message}`, 'failed');
     }
     finally {
         active = null;
@@ -342,8 +357,13 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         if (shared)
             say(shared);
     }
+    // Outside the try, so a ping that throws can never park a verified run.
+    await ping(record.prUrl ? 'ready' : 'passed');
+    return 'verified';
 }
-// 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 +380,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 +406,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 +461,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 +538,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 +574,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 +600,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 +609,118 @@ 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);
+            const paused = isPaused(rc.configDir);
+            if (rc.summary) {
+                try {
+                    await rc.summary(paused);
+                }
+                catch (err) {
+                    rc.log(`discord: ${err.message}`);
+                }
+            }
+            if (!paused) {
+                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/secrets.d.ts

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

package/dist/secrets.js

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

package/dist/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.7.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": {