@voidlabs.gg/voidshift-agents 0.5.0 → 0.6.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, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
-import { agentsDir, hasWork, isCardTrigger, resolveStep, stepId, stepIdLabel } from "./config.js";
+import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, needsPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
+import { agentsDir, hasWork, isCardTrigger, resolveProject, resolveStep, stepId, stepIdLabel, workspaceContext, workspaceOf } from "./config.js";
 import { 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) => {
@@ -138,10 +140,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             throw new Park(`Workflow ${workflowName} has no ${stepIdLabel(opts.from)} step.`);
         // A scheduled run has no card to plan on, so its task is the plan unless a Plan step writes one.
         let plan = isCardTrigger(trigger) ? latestPlan(await linear.comments(card.identifier)) : card.description ?? null;
-        const firstPlan = steps.findIndex((d, n) => n >= from && d.output === 'plan');
-        // A check before any commits is a check on the plan, like Plan review.
-        const needsPlan = steps.findIndex((d, n) => n >= from && (d.output === 'commits' || (d.output === 'verdict' && d.builtin !== 'vs-qa')));
-        if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
+        if (!plan && needsPlan(steps, from)) {
             throw new Park('No plan comment (starting with "## Plan") was found. Publish a plan first, or start the workflow with Plan.');
         }
         await stage(stageOf(steps[from]));
@@ -160,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}`);
@@ -346,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';
@@ -363,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) {
@@ -386,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;
@@ -423,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 = [];
@@ -485,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) {
@@ -522,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}).`);
@@ -545,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;
         }
@@ -554,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/dist/workflow.d.ts

@@ -49,4 +49,8 @@ export interface PromptInput {
 export declare function buildPrompt(p: PromptInput): string;
 export declare function verdictBlock<T>(steps: T[], i: number, isVerdict: (s: T) => boolean): [number, number];
 export declare function fixTarget<T>(steps: T[], blockStart: number, isProducer: (s: T) => boolean): number;
+export declare function needsPlan(steps: {
+    output: string;
+    builtin?: string;
+}[], from: number): boolean;
 export declare function planBody(output: string): string;

package/dist/workflow.js

@@ -105,6 +105,21 @@ export function fixTarget(steps, blockStart, isProducer) {
             return j;
     return -1;
 }
+// Whether a run starting at `from` needs a plan comment: some step before any
+// Plan step writes commits or checks the plan. A check counts as a plan check
+// only when a Plan step comes before it, so a review-only workflow runs bare.
+export function needsPlan(steps, from) {
+    for (let n = from; n < steps.length; n++) {
+        const s = steps[n];
+        if (s.output === 'plan')
+            return false;
+        if (s.output === 'commits')
+            return true;
+        if (s.output === 'verdict' && s.builtin !== 'vs-qa' && (s.builtin === 'vs-plan-review' || steps.slice(0, n).some((d) => d.output === 'plan')))
+            return true;
+    }
+    return false;
+}
 // Plan output minus the trailing RESULT line, ready to post.
 export function planBody(output) {
     return output.replace(/^\s*RESULT:.*$/gim, '').trim();

package/pack/vs-plan/SKILL.md

@@ -94,7 +94,9 @@ The plan file holds the detail. In the chat, keep it short and plain:
 Start straight at Understanding. Do not repeat the card id or title; the card
 already shows them.
 
-Length follows the change: under 350 words for a small one, never padded.
+Outcome first. Under 350 words for a small change, never over 700 for any
+change. File and line detail only in Surfaces; no code blocks over 5 lines;
+Six angles lists only angles that apply.
 
 **Understanding.** Two to four sentences: what the card asks, what it got
 wrong, which reading you chose.
@@ -123,6 +125,7 @@ anything a human must click.
 - No ticket ids in code comments.
 - No em dashes or en dashes.
 - No narration of process. State findings.
+- Do not quote code the dev agent can read.
 
 ## When you run inside a workflow
 

package/pack/vs-plan-review/SKILL.md

@@ -41,7 +41,8 @@ main points.
 2. The findings that change what gets built, most important first, at most 5,
    one short plain line each: what is wrong and what to do about it.
 3. Everything smaller in one line: `Minor: ...`.
-4. A short `Details` section: for each finding, the file and line that proves it.
+4. A short `Details` section: one line per finding, the file and line that
+   proves it.
 5. Last line, exactly one of:
 
 ```
@@ -56,6 +57,7 @@ fixes to the plan file.
 
 - No em dashes or en dashes.
 - No narration of process. State findings.
+- Whole review under 300 words.
 
 ## When you run inside a workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.5.0",
+  "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": {
@@ -40,7 +40,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test test/*.test.ts",
+    "test": "node --test --test-force-exit --test-timeout=60000 test/*.test.ts",
     "prepublishOnly": "rm -rf dist && tsc -p tsconfig.json"
   },
   "devDependencies": {