@voidlabs.gg/voidshift-agents 0.4.0 → 0.4.2

package/README.md

@@ -59,8 +59,10 @@ when ENG + vs-plan:  Dev → QA  in tether-relay
 ```
 
 The runner checks Linear every minute, works in its own copy of the repo so
-your checkout is never touched, and labels the card as it goes (`vs-dev-v1`,
-`vs-qa-v1`, then `vs-qa-verified` or `vs-parked` with a comment saying why).
+your checkout is never touched, and keeps two labels on the card as it goes: the
+stage (`vs-planning`, `vs-plan-review`, `vs-dev`, `vs-qa`, then `vs-qa-verified`
+or `vs-parked`) and the round (`vs-v1`, `vs-v2`). On Linear it posts the plan and
+one final comment, nothing in between.
 
 ```sh
 vsf agents status                  # runner, the card in progress, parked cards

package/dist/control.js

@@ -8,7 +8,7 @@ import { isPaused, listRuns, ours, clearCurrent, liveCurrent, readCurrent, setPa
 import { plistPath, runnerLoaded, startRunner, stopRunner } from "./launchd.js";
 import { createLinear } from "./linear.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
-import { LABELS, isRoundLabel } from "./workflow.js";
+import { isStatusLabel } from "./workflow.js";
 import { cancelCard, tick } from "./runner.js";
 const HOUR = 3_600_000;
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
@@ -429,8 +429,7 @@ const retry = guard(async (args, ctx) => {
         chosen = candidates[0];
     }
     const label = config.workflows[chosen].triggers.find((t) => t.team === card.teamKey).label;
-    const drop = new Set([LABELS.parked, LABELS.changes, LABELS.verified, LABELS.working]);
-    const next = card.labels.filter((n) => !drop.has(n) && !isRoundLabel(n));
+    const next = card.labels.filter((n) => !isStatusLabel(n));
     if (!next.includes(label))
         next.push(label);
     await l.setLabels(card, next);

package/dist/engine.js

@@ -8,7 +8,8 @@ const CLAUDE_WRITE = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
 const CLAUDE_READ = ['Read', 'Glob', 'Grep', 'Bash(git diff:*)', 'Bash(git log:*)', 'Bash(git show:*)', 'Bash(npm test:*)', 'Bash(npm run:*)', 'Bash(pnpm:*)', 'Bash(yarn:*)', 'Bash(npx:*)', 'Bash(node:*)', 'Bash(ls:*)', 'Bash(rg:*)'];
 export function engineArgs(o, outFile) {
     if (o.engine === 'claude') {
-        const vaultTools = o.vault ? [`Edit(/${o.vault}/**)`, `Write(/${o.vault}/**)`] : [];
+        // Edit rules cover every file-writing tool; a Write(path) rule is ignored.
+        const vaultTools = o.vault ? [`Edit(/${o.vault}/**)`] : [];
         const args = ['-p', '--output-format', 'text', '--allowedTools', [...(o.write ? CLAUDE_WRITE : CLAUDE_READ), ...vaultTools].join(',')];
         if (o.vault)
             args.push('--add-dir', o.vault);

package/dist/git.d.ts

@@ -8,6 +8,7 @@ export declare function sh(cmd: string, args: string[], cwd: string, timeoutMs?:
 export declare function defaultBranch(repo: string): string;
 export declare function ensureWorktree(repo: string, path: string, branch: string, base: string): void;
 export declare function commitsAhead(worktree: string, base: string): number;
+export declare function headSha(worktree: string): string;
 export declare function push(worktree: string, branch: string): void;
 export declare function ensureDraftPr(worktree: string, branch: string, base: string, title: string, body: string): string;
 export declare function markReady(worktree: string, branch: string): boolean;
@@ -21,8 +22,9 @@ export interface CheckSummary {
 }
 export declare function summarizeChecks(text: string): CheckSummary;
 export declare function ciReport(s: CheckSummary): string;
-export declare function waitForChecks(worktree: string, branch: string, timeoutMs?: number): Promise<{
-    verdict: 'SHIP' | 'FIX' | 'SKIP';
+export declare function waitForPrHead(worktree: string, branch: string, sha: string, timeoutMs?: number): Promise<boolean>;
+export declare function waitForChecks(worktree: string, branch: string, timeoutMs?: number, settleMs?: number): Promise<{
+    verdict: 'SHIP' | 'FIX' | 'SKIP' | 'PENDING';
     report: string;
 }>;
 export declare function resetWorktree(worktree: string): void;

package/dist/git.js

@@ -40,13 +40,21 @@ export function commitsAhead(worktree, base) {
     const out = sh('git', ['rev-list', '--count', `origin/${base}..HEAD`], worktree);
     return out.ok ? Number(out.stdout) : 0;
 }
+export function headSha(worktree) {
+    return sh('git', ['rev-parse', 'HEAD'], worktree).stdout;
+}
 export function push(worktree, branch) {
     must(sh('git', ['push', '-u', 'origin', branch], worktree), 'git push');
 }
+// The branch's open pull request. A closed one is reopened, since a closed PR
+// never runs CI on new commits; a merged one gets a fresh PR.
 export function ensureDraftPr(worktree, branch, base, title, body) {
-    const view = sh('gh', ['pr', 'view', branch, '--json', 'url', '-q', '.url'], worktree);
-    if (view.ok && view.stdout)
-        return view.stdout;
+    const view = sh('gh', ['pr', 'view', branch, '--json', 'url,state', '-q', '.state + " " + .url'], worktree);
+    const [state, url] = view.ok ? view.stdout.split(' ') : [];
+    if (state === 'OPEN' && url)
+        return url;
+    if (state === 'CLOSED' && url && sh('gh', ['pr', 'reopen', branch], worktree).ok)
+        return url;
     return must(sh('gh', ['pr', 'create', '--draft', '--base', base, '--head', branch, '--title', title, '--body', body], worktree), 'gh pr create');
 }
 export function markReady(worktree, branch) {
@@ -77,7 +85,30 @@ export function ciReport(s) {
 }
 // Waits for CI on the PR, then reads the final state once. Repos without CI
 // pass through as SKIP.
-export function waitForChecks(worktree, branch, timeoutMs = 30 * 60_000) {
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// True once GitHub shows `sha` as the head of the branch's pull request, so the
+// checks read next belong to that commit and not to an older push.
+export async function waitForPrHead(worktree, branch, sha, timeoutMs = 3 * 60_000) {
+    const until = Date.now() + timeoutMs;
+    for (;;) {
+        const head = sh('gh', ['pr', 'view', branch, '--json', 'headRefOid', '-q', '.headRefOid'], worktree);
+        if (head.ok && head.stdout === sha)
+            return true;
+        if (Date.now() > until)
+            return false;
+        await sleep(10_000);
+    }
+}
+// CI for the pull request's current head. Checks take a moment to register
+// after a push, so "no checks" only counts once they have had time to show up.
+export async function waitForChecks(worktree, branch, timeoutMs = 30 * 60_000, settleMs = 2 * 60_000) {
+    const settled = Date.now() + settleMs;
+    const noChecks = () => {
+        const out = sh('gh', ['pr', 'checks', branch], worktree);
+        return /no checks reported/i.test(`${out.stdout}\n${out.stderr}`);
+    };
+    while (Date.now() < settled && noChecks())
+        await sleep(15_000);
     return new Promise((resolve) => {
         const child = spawn('gh', ['pr', 'checks', branch, '--watch', '--interval', '30'], { cwd: worktree, stdio: ['ignore', 'pipe', 'pipe'] });
         track(child);
@@ -93,7 +124,7 @@ export function waitForChecks(worktree, branch, timeoutMs = 30 * 60_000) {
             if (!summary.failed.length && !summary.pending.length)
                 return resolve({ verdict: 'SHIP', report: `CI passed (${summary.passed} checks).` });
             if (!summary.failed.length)
-                return resolve({ verdict: 'FIX', report: `CI did not finish in time. Still running: ${summary.pending.join(', ')}.` });
+                return resolve({ verdict: 'PENDING', report: `CI did not finish in time. Still running: ${summary.pending.join(', ')}.` });
             resolve({ verdict: 'FIX', report: ciReport(summary) });
         });
     });

package/dist/runner.js

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isRoundLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, verdictBlock, } from "./workflow.js";
+import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
 import { STEPS, agentsDir, hasWork, isProducer } from "./config.js";
 import { runAgent, stopAgents } from "./engine.js";
-import { commitsAhead, defaultBranch, ensureDraftPr, ensureWorktree, markReady, push, resetWorktree, waitForChecks } from "./git.js";
+import { commitsAhead, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
 import { recall, vaultPath } from "./memory.js";
 import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun } from "./state.js";
 const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
@@ -15,7 +15,6 @@ class Park extends Error {
 function withLabels(card, drop, add) {
     return [...new Set([...card.labels.filter((l) => !drop(l)), ...add])];
 }
-const statusLabel = (l) => l === LABELS.working || l === LABELS.verified || l === LABELS.parked || l === LABELS.changes || isRoundLabel(l);
 const UNATTENDED = `# Running unattended
 
 You are one step in a workflow. Nobody can answer questions and the
@@ -81,19 +80,36 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         save();
         return outcome;
     };
+    // Shown on the card as the version label and in the lock as the round.
+    const setRound = (n) => {
+        loops = n;
+    };
+    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, trigger.label, name, round));
+    // Linear hears from the runner twice: the plan once it has passed review,
+    // and one final comment. Findings stay here until the final one.
+    let lastFindings = '';
+    let planToPost = null;
+    const postPlan = async () => {
+        if (planToPost === null)
+            return;
+        await linear.comment(card, `${PLAN_HEADING}\n\n${planToPost}`);
+        planToPost = null;
+    };
     async function park(reason) {
         say(`parked: ${reason}`);
-        const comment = `**Parked:** ${reason}\n\nFix the cause, then add \`${trigger.label}\` again to retry.`;
+        const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${trigger.label}\` again to retry.`;
+        const add = [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])];
         let commented = false;
         try {
+            await postPlan();
             await linear.comment(card, comment);
             commented = true;
-            await linear.setLabels(card, withLabels(card, (l) => l === trigger.label || l === LABELS.working, [LABELS.parked]));
+            await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.parked, loops || undefined));
         }
         catch (err) {
             say(`could not reach 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: [trigger.label, LABELS.working], add: [LABELS.parked] }]);
+            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [trigger.label], add, dropStatus: true }]);
         }
         return done('parked', reason);
     }
@@ -109,7 +125,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
             throw new Park('No plan comment (starting with "## Plan") was found. Publish a plan first, or start the workflow with Plan.');
         }
-        await linear.setLabels(card, withLabels(card, (l) => l === trigger.label || statusLabel(l), [LABELS.working]));
+        await stage(LABELS.stage[steps[from]]);
         const base = project.base || defaultBranch(project.path);
         const vault = vaultPath(rc.configDir);
         const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : ''].filter(Boolean).join('\n\n');
@@ -117,12 +133,13 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         ensureWorktree(project.path, worktree, card.branchName, base);
         say(`working in ${worktree} on ${card.branchName}`);
         const findings = new Map();
-        const runs = { plan: 0, dev: 0, qa: 0 };
+        const runs = { plan: 0, dev: 0 };
         let prUrl = '';
+        let logs = 0;
         const planText = () => plan ?? '(No plan was posted on this card. Check the work against the card itself.)';
         const timeoutMs = config.timeoutMinutes * 60_000;
-        const logFile = (name) => join(runDir, `${String(runs.plan + runs.dev + runs.qa).padStart(2, '0')}-${name}.log`);
-        async function check(step) {
+        const logFile = (name) => join(runDir, `${String(logs++).padStart(2, '0')}-${name}.log`);
+        async function check(step, round) {
             const label = STEPS[step].label;
             const rec = begin(step);
             let ciNote = '';
@@ -131,9 +148,22 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                     end(rec, 'SKIP', 'No changes on the branch yet.');
                     return { step: label, verdict: 'SKIP', report: 'No changes on the branch yet.' };
                 }
-                // CI first, without an agent: a red build goes straight back.
+                // CI first, without an agent: a red build goes straight back. Only
+                // checks for the commit just pushed count, never an older push's.
                 if (prUrl) {
-                    const ci = await waitForChecks(worktree, card.branchName);
+                    const sha = headSha(worktree);
+                    if (!(await waitForPrHead(worktree, card.branchName, sha))) {
+                        throw new Park(`GitHub never showed commit ${sha.slice(0, 9)} on the pull request, so its CI could not be read. PR: ${prUrl}`);
+                    }
+                    // A slow CI is not a failed one: wait a second window, then park
+                    // rather than send Dev a round it can only answer with no commit.
+                    let ci = await waitForChecks(worktree, card.branchName);
+                    if (ci.verdict === 'PENDING') {
+                        say('CI still running, waiting another window');
+                        ci = await waitForChecks(worktree, card.branchName);
+                    }
+                    if (ci.verdict === 'PENDING')
+                        throw new Park(`${ci.report} PR: ${prUrl}`);
                     if (ci.verdict === 'FIX') {
                         end(rec, 'FIX', ci.report);
                         return { step: label, verdict: 'FIX', report: ci.report };
@@ -144,7 +174,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             const log = logFile(step);
             const r = await runAgent({
                 engine: config.engine, model: config.models.review, cwd: worktree, vault, write: step === 'vs-qa', logFile: log, timeoutMs,
-                prompt: buildPrompt({ skill: skill(step), card, plan: planText(), base, round: runs.qa + 1, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
+                prompt: buildPrompt({ skill: skill(step), card, plan: planText(), base, round, extra: [known, ciNote, UNATTENDED].filter(Boolean).join('\n\n') }),
             });
             if (step === 'vs-qa')
                 resetWorktree(worktree);
@@ -158,30 +188,40 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             say(`${STEPS[step].label}`);
             if (isVerdict(step)) {
                 const [start, end] = verdictBlock(steps, i, isVerdict);
+                const target = fixTarget(steps, start, isProducer);
+                const producer = target >= 0 ? steps[target] : undefined;
+                // The round being checked: how many times its producer has run.
+                const round = Math.max(producer === 'vs-plan' ? runs.plan : runs.dev, 1);
+                setRound(round);
                 const results = [];
-                for (const s of steps.slice(start, end))
-                    results.push(await check(s));
-                runs.qa++;
-                await linear.setLabels(card, withLabels(card, () => false, [LABELS.qa(runs.qa)]));
+                for (const s of steps.slice(start, end)) {
+                    await stage(LABELS.stage[s], round);
+                    results.push(await check(s, round));
+                }
                 if (qaPassed(results)) {
                     i = end;
                     continue;
                 }
                 const notes = findingsFor(results);
-                await linear.comment(card, `**Changes needed (round ${runs.qa}).**\n\n${notes}`);
-                const target = fixTarget(steps, start, isProducer);
+                lastFindings = `**Latest findings (round ${round}).**\n\n${notes}`;
                 if (target < 0) {
-                    await linear.setLabels(card, withLabels(card, (l) => l === LABELS.working, [LABELS.changes]));
+                    await postPlan();
+                    await linear.comment(card, `**Changes needed.**\n\n${notes}`);
+                    await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.changes, round));
                     say('changes requested');
                     return done('changes');
                 }
-                if (++loops > workflow.maxRounds)
-                    throw new Park(`Checks still failed after sending the work back ${workflow.maxRounds} times. Latest findings are in the comment above.${prUrl ? ` PR: ${prUrl}` : ''}`);
+                // Rounds caps how many times Plan or Dev runs, counting the first.
+                if (round >= workflow.maxRounds) {
+                    throw new Park(`Checks still failed after ${round} ${producer === 'vs-plan' ? 'plan' : 'dev'} rounds.${prUrl ? ` PR: ${prUrl}` : ''}`);
+                }
                 findings.set(target, notes);
                 i = target;
                 continue;
             }
             if (step === 'vs-plan') {
+                setRound(runs.plan + 1);
+                await stage(LABELS.stage[step], runs.plan + 1);
                 const rec = begin(step);
                 const log = logFile('plan');
                 const r = await runAgent({
@@ -193,18 +233,22 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 if (result.status === 'blocked')
                     throw new Park(`The plan agent stopped: ${result.reason}`);
                 plan = planBody(r.output);
-                await linear.comment(card, `${PLAN_HEADING}\n\n${plan}`);
+                planToPost = plan;
                 runs.plan++;
-                await linear.setLabels(card, withLabels(card, () => false, [LABELS.plan(runs.plan)]));
             }
             else if (step === 'vs-publish') {
+                await postPlan();
                 const rec = begin(step);
                 push(worktree, card.branchName);
                 end(rec, 'pushed');
             }
             else if (step === 'vs-dev') {
+                await postPlan();
+                setRound(runs.dev + 1);
+                await stage(LABELS.stage[step], runs.dev + 1);
                 const rec = begin(step);
                 const log = logFile('dev');
+                const before = headSha(worktree);
                 const dev = await runAgent({
                     engine: config.engine, model: config.models.dev, cwd: worktree, vault, write: true, logFile: log, timeoutMs,
                     prompt: buildPrompt({ skill: skill('vs-dev'), card, plan: planText(), base, round: runs.dev + 1, findings: findings.get(i), extra: [known, UNATTENDED].filter(Boolean).join('\n\n') }),
@@ -215,22 +259,26 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                     throw new Park(`The dev agent stopped: ${result.reason}`);
                 if (commitsAhead(worktree, base) === 0)
                     throw new Park('The dev agent made no commits.');
+                // A round sent back with findings must change something, or QA would
+                // just check the same commit again.
+                if (runs.dev > 0 && headSha(worktree) === before)
+                    throw new Park('The dev agent made no new commits this round.');
                 push(worktree, card.branchName);
                 prUrl = ensureDraftPr(worktree, card.branchName, base, `${card.identifier}: ${card.title}`, card.url);
                 record.prUrl = prUrl;
                 save();
                 runs.dev++;
-                await linear.setLabels(card, withLabels(card, () => false, [LABELS.dev(runs.dev)]));
             }
             findings.delete(i);
             i++;
         }
+        await postPlan();
         let moved = false;
         if (hasWork(workflow)) {
             markReady(worktree, card.branchName);
             moved = await linear.moveTo(card, config.reviewState);
         }
-        await linear.setLabels(card, withLabels(card, (l) => l === LABELS.working, [LABELS.verified]));
+        await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.verified, loops || undefined));
         await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${hasWork(workflow) && !moved ? `\n\n(No "${config.reviewState}" state on this team, so the card was not moved.)` : ''}`);
         say('verified');
         return done('verified');
@@ -271,7 +319,7 @@ async function flushPending(rc) {
                 await rc.linear.comment(card, p.comment);
                 p.comment = '';
             }
-            await rc.linear.setLabels(card, withLabels(card, (l) => p.drop.includes(l), p.add));
+            await rc.linear.setLabels(card, withLabels(card, (l) => p.drop.includes(l) || (!!p.dropStatus && isStatusLabel(l)), p.add));
         }
         catch {
             left.push(p);
@@ -290,7 +338,7 @@ export async function cancelCard(linear, configDir, cardId, label) {
     const comment = `**Cancelled.** Add \`${label}\` again to restart.`;
     try {
         const card = await linear.card(cardId);
-        await linear.setLabels(card, withLabels(card, (l) => l === LABELS.working, []));
+        await linear.setLabels(card, withLabels(card, isStatusLabel, []));
         await linear.comment(card, comment);
         return true;
     }
@@ -304,7 +352,7 @@ function queueCancel(configDir, cardId, comment) {
     if (pending.some((p) => p.card === cardId && p.comment === comment))
         return;
     try {
-        writePending(configDir, [...pending, { card: cardId, comment, drop: [LABELS.working], add: [] }]);
+        writePending(configDir, [...pending, { card: cardId, comment, drop: [], add: [], dropStatus: true }]);
     }
     catch {
         // nothing more to do

package/dist/state.d.ts

@@ -24,6 +24,7 @@ export interface Pending {
     comment: string;
     drop: string[];
     add: string[];
+    dropStatus?: boolean;
 }
 export declare function readPending(configDir: string): Pending[];
 export declare function writePending(configDir: string, pending: Pending[]): void;

package/dist/workflow.d.ts

@@ -1,14 +1,16 @@
 export declare const PLAN_HEADING = "## Plan";
 export declare const LABELS: {
-    working: string;
+    stage: Record<string, string>;
     changes: string;
     verified: string;
     parked: string;
-    plan: (round: number) => string;
-    dev: (round: number) => string;
-    qa: (round: number) => string;
+    version: (round: number) => string;
+    working: string;
 };
+export declare const isVersionLabel: (name: string) => boolean;
 export declare const isRoundLabel: (name: string) => boolean;
+export declare const isStatusLabel: (name: string) => boolean;
+export declare function stageLabels(current: string[], trigger: string, stage: string, round?: number): string[];
 export type Verdict = 'SHIP' | 'FIX' | 'SKIP';
 export interface StepResult {
     step: string;

package/dist/workflow.js

@@ -3,16 +3,34 @@
 export const PLAN_HEADING = '## Plan';
 // Plans posted before 0.1.5 used this heading; still read them.
 const OLD_PLAN_HEADING = '## VoidShift plan';
+// A card carries at most two VoidShift labels: one stage label (which agent has
+// it, or how it ended) and one version label (which round it is on).
 export const LABELS = {
-    working: 'vs-working',
+    stage: {
+        'vs-plan': 'vs-planning',
+        'vs-plan-review': 'vs-plan-review',
+        'vs-publish': 'vs-publish',
+        'vs-dev': 'vs-dev',
+        'vs-qa': 'vs-qa',
+    },
     changes: 'vs-changes-requested',
     verified: 'vs-qa-verified',
     parked: 'vs-parked',
-    plan: (round) => `vs-plan-v${round}`,
-    dev: (round) => `vs-dev-v${round}`,
-    qa: (round) => `vs-qa-v${round}`,
+    version: (round) => `vs-v${round}`,
+    // Labels from earlier runners, still cleaned off cards.
+    working: 'vs-working',
 };
-export const isRoundLabel = (name) => /^vs-(plan|dev|qa)-v\d+$/.test(name);
+const STAGE_NAMES = new Set([...Object.values(LABELS.stage), LABELS.changes, LABELS.verified, LABELS.parked, LABELS.working]);
+export const isVersionLabel = (name) => /^vs-v\d+$/.test(name);
+// Round labels earlier runners stacked up, one per step and round.
+export const isRoundLabel = (name) => /^vs-(plan|review|dev|qa)-v\d+$/.test(name);
+export const isStatusLabel = (name) => STAGE_NAMES.has(name) || isVersionLabel(name) || isRoundLabel(name);
+// The card's labels with every VoidShift label (and the trigger) replaced by
+// one stage label and, when given, one version label.
+export function stageLabels(current, trigger, stage, round) {
+    const kept = current.filter((l) => l !== trigger && !isStatusLabel(l));
+    return [...new Set([...kept, stage, ...(round ? [LABELS.version(round)] : [])])];
+}
 // The last "VERDICT: X" line wins; anything unreadable counts as FIX so a
 // confused agent never waves a change through.
 export function parseVerdict(output) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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": {