@voidlabs.gg/voidshift-agents 0.4.3 → 0.4.5

package/dist/cron.js

@@ -0,0 +1,66 @@
+// Five field cron schedules: minute hour day-of-month month day-of-week, each
+// a list of *, numbers, ranges and steps (*/15, 1-5, 0,30). Sunday is 0 or 7.
+// When both day fields are restricted, either may match, as in classic cron.
+const FIELDS = [
+    [0, 59],
+    [0, 23],
+    [1, 31],
+    [1, 12],
+    [0, 7],
+];
+function field(text, [min, max]) {
+    const out = new Set();
+    for (const part of text.split(',')) {
+        const m = /^(\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/.exec(part);
+        if (!m)
+            return null;
+        const step = m[4] ? Number(m[4]) : 1;
+        const lo = m[1] === '*' ? min : Number(m[2]);
+        const hi = m[1] === '*' ? max : m[3] ? Number(m[3]) : m[4] ? max : lo;
+        if (step < 1 || lo < min || hi > max || lo > hi)
+            return null;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+export function parseCron(schedule) {
+    const parts = schedule.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const sets = [];
+    for (let i = 0; i < 5; i++) {
+        const s = field(parts[i], FIELDS[i]);
+        if (!s)
+            return null;
+        sets.push(s);
+    }
+    if (sets[4].has(7))
+        sets[4].add(0);
+    return { sets, anyDom: parts[2] === '*', anyDow: parts[4] === '*' };
+}
+export function matches(s, d) {
+    const [min, hour, dom, month, dow] = s.sets;
+    if (!min.has(d.getMinutes()) || !hour.has(d.getHours()) || !month.has(d.getMonth() + 1))
+        return false;
+    const domOk = dom.has(d.getDate());
+    const dowOk = dow.has(d.getDay());
+    if (s.anyDom || s.anyDow)
+        return domOk && dowOk;
+    return domOk || dowOk;
+}
+const MINUTE = 60_000;
+// How far back a missed schedule is still made up for, e.g. after the runner
+// was busy or the machine was off. Older misses are skipped, not queued.
+export const CATCH_UP_MS = 24 * 60 * MINUTE;
+// The latest minute after `since` and up to `now` that the schedule matches,
+// or null. Only the latest counts: several missed runs fire once.
+export function lastDue(s, since, now) {
+    const floor = Math.max(since.getTime(), now.getTime() - CATCH_UP_MS);
+    const t = new Date(now);
+    t.setSeconds(0, 0);
+    for (; t.getTime() > floor; t.setTime(t.getTime() - MINUTE))
+        if (matches(s, t))
+            return new Date(t);
+    return null;
+}

package/dist/engine.d.ts

@@ -9,6 +9,7 @@ export interface RunOptions {
     logFile: string;
     timeoutMs?: number;
     vault?: string;
+    settingsFile?: string;
 }
 export declare function engineArgs(o: RunOptions, outFile: string): {
     cmd: string;

package/dist/engine.js

@@ -17,6 +17,8 @@ export function engineArgs(o, outFile) {
             args.push('--permission-mode', 'acceptEdits');
         if (o.model)
             args.push('--model', o.model);
+        if (o.settingsFile)
+            args.push('--settings', o.settingsFile);
         return { cmd: 'claude', args };
     }
     const args = ['exec', '-C', o.cwd, '-s', o.write ? 'workspace-write' : 'read-only', '-o', outFile];

package/dist/git.d.ts

@@ -28,3 +28,9 @@ export declare function waitForChecks(worktree: string, branch: string, timeoutM
     report: string;
 }>;
 export declare function resetWorktree(worktree: string): void;
+export interface CommitPolicy {
+    signOff?: boolean;
+    dropAiTrailers?: boolean;
+}
+export declare function applyPolicy(message: string, policy: CommitPolicy, signer: string | null, cwd: string): string;
+export declare function enforceCommitPolicy(worktree: string, from: string, policy: CommitPolicy): number;

package/dist/git.js

@@ -134,3 +134,63 @@ export function resetWorktree(worktree) {
     sh('git', ['reset', '--hard', 'HEAD'], worktree);
     sh('git', ['clean', '-fd'], worktree);
 }
+const AI_LINE = /^(co-authored-by:.*(claude|anthropic|codex|openai|copilot|gemini|cursor)|.*generated with \[?(claude|codex)).*$/i;
+// The message with AI lines removed and a sign-off added, as the policy asks.
+export function applyPolicy(message, policy, signer, cwd) {
+    let msg = message.replace(/\r\n/g, '\n');
+    if (policy.dropAiTrailers)
+        msg = msg.split('\n').filter((l) => !AI_LINE.test(l.trim())).join('\n');
+    msg = msg.replace(/\s+$/, '') + '\n';
+    if (policy.signOff && signer) {
+        // git's own trailer rules decide the blank line and skip a duplicate.
+        const r = spawnSync('git', ['interpret-trailers', '--if-exists', 'addIfDifferent', '--trailer', `Signed-off-by: ${signer}`], { cwd, input: msg, encoding: 'utf8' });
+        if (r.status === 0)
+            msg = r.stdout;
+    }
+    return msg;
+}
+// Rewrites the commits after `from` up to HEAD so their messages follow the
+// policy. Trees, authors and dates stay as they were; only commits not yet
+// pushed may be passed. Returns how many changed.
+export function enforceCommitPolicy(worktree, from, policy) {
+    if (!policy.signOff && !policy.dropAiTrailers)
+        return 0;
+    const name = sh('git', ['config', 'user.name'], worktree).stdout;
+    const email = sh('git', ['config', 'user.email'], worktree).stdout;
+    const signer = name && email ? `${name} <${email}>` : null;
+    const list = sh('git', ['rev-list', '--reverse', '--parents', `${from}..HEAD`], worktree);
+    if (!list.ok || !list.stdout)
+        return 0;
+    const map = new Map();
+    let changed = 0;
+    let head = '';
+    for (const line of list.stdout.split('\n')) {
+        const [sha, ...parents] = line.split(' ');
+        const info = must(sh('git', ['log', '-1', '--format=%T%x00%an%x00%ae%x00%aD%x00%cn%x00%ce%x00%cD', sha], worktree), 'git log');
+        const [tree, an, ae, ad, cn, ce, cd] = info.split('\0');
+        const raw = spawnSync('git', ['log', '-1', '--format=%B', sha], { cwd: worktree, encoding: 'utf8' }).stdout ?? '';
+        const message = applyPolicy(raw, policy, signer, worktree);
+        const newParents = parents.map((p) => map.get(p) ?? p);
+        if (message === raw.replace(/\s+$/, '') + '\n' && newParents.every((p, i) => p === parents[i])) {
+            map.set(sha, sha);
+            head = sha;
+            continue;
+        }
+        const r = spawnSync('git', ['commit-tree', tree, ...newParents.flatMap((p) => ['-p', p]), '-F', '-'], {
+            cwd: worktree,
+            input: message,
+            encoding: 'utf8',
+            env: { ...process.env, GIT_AUTHOR_NAME: an, GIT_AUTHOR_EMAIL: ae, GIT_AUTHOR_DATE: ad, GIT_COMMITTER_NAME: cn, GIT_COMMITTER_EMAIL: ce, GIT_COMMITTER_DATE: cd },
+        });
+        if (r.status !== 0)
+            throw new Error(`git commit-tree failed: ${r.stderr}`);
+        const next = r.stdout.trim();
+        map.set(sha, next);
+        head = next;
+        changed++;
+    }
+    // Same tree at the tip, so moving the branch leaves the files untouched.
+    if (changed)
+        must(sh('git', ['reset', '-q', '--soft', head], worktree), 'git reset');
+    return changed;
+}

package/dist/index.js

@@ -4,12 +4,17 @@ 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, STEPS, TEMPLATES, isProducer, agentsDir, describeSteps, describeTriggers, describeWorkflow, stepEnabled, 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, DEFAULTS } from "./config.js";
 import { controlChecks, controlCommands, controlUsage } from "./control.js";
-import { keyStore, looksLikeLinearKey, readLinearKey, storeLinearKey } from "./secrets.js";
+import { keyStore, looksLikeLinearKey, readLinearKey, readSecret, storeLinearKey, storeSecret } from "./secrets.js";
+import { TRACKERS } from "./tracker.js";
+import { createVoidTrack } from "./voidtrack.js";
+import { parseCron } from "./cron.js";
+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 { duplicateTriggerWarnings, moveKey, parseTrigger, renameKey, sameTrigger, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
+import { TRIGGER_FORMS, duplicateTriggerWarnings, moveKey, parseTrigger, 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";
@@ -81,26 +86,28 @@ async function chooseHomes(ui, configDir, saved) {
     return homes;
 }
 // Checks the key against Linear, and only then stores it.
-async function verifyAndStore(configDir, key, info, warn) {
+async function verifyAndStore(configDir, key, info, warn, kind = 'linear') {
+    const name = TRACKERS[kind].name;
     try {
-        const me = await createLinear(key).viewer();
-        if (!storeLinearKey(configDir, key)) {
-            warn(`Linear accepted the key but it could not be stored in ${keyStore()}.`);
+        const me = await (kind === 'voidtrack' ? createVoidTrack(key) : createLinear(key)).viewer();
+        if (!(kind === 'voidtrack' ? storeSecret(configDir, 'voidtrack', key) : storeLinearKey(configDir, key))) {
+            warn(`${name} accepted the key but it could not be stored in ${keyStore()}.`);
             return null;
         }
-        info(`Linear connected as ${me.name}. Key stored in ${keyStore()}.`);
+        info(`${name} connected as ${me.name}. Key stored in ${keyStore()}.`);
         return me.name;
     }
     catch (err) {
-        warn(`Linear did not accept that key: ${err.message}. Nothing was stored.`);
+        warn(`${name} did not accept that key: ${err.message}. Nothing was stored.`);
         return null;
     }
 }
 // Asks for the key, checks it against Linear, and only then stores it.
-async function setupKey(ui, configDir) {
-    ui.info('Agents need a Linear personal API key (Linear > Settings > Security & access > API keys).');
-    const key = await ui.secret('Paste your Linear API key', (v) => (looksLikeLinearKey(v.trim()) ? undefined : 'Linear keys start with lin_api_'));
-    return verifyAndStore(configDir, key.trim(), ui.info, ui.warn);
+async function setupKey(ui, configDir, kind = 'linear') {
+    const { name, keyHint } = TRACKERS[kind];
+    ui.info(`Agents need a ${name} API key (${keyHint}).`);
+    const key = await ui.secret(`Paste your ${name} API key`, (v) => kind === 'linear' ? (looksLikeLinearKey(v.trim()) ? undefined : 'Linear keys start with lin_api_') : v.trim() ? undefined : 'Required');
+    return verifyAndStore(configDir, key.trim(), ui.info, ui.warn, kind);
 }
 async function currentLinearUser(configDir) {
     try {
@@ -277,11 +284,22 @@ async function promptWorkflow(ui, config, teams, current = {}, edit = false) {
     if (!triggers) {
         triggers = [];
         do {
-            const team = teams.length
-                ? await ui.select(triggers.length ? 'Also start for cards in which Linear team?' : 'Starts when a card in which Linear team...', teams.map((t) => ({ value: t.key, label: `${t.key}  ${t.name}`, hint: t.mine ? 'your team' : undefined })), myTeams.length === 1 ? myTeams[0].key : undefined)
-                : (await ui.text('Starts when a card in which Linear team key...', { validate: (v) => (v.trim() ? undefined : 'Required') })).trim().toUpperCase();
+            const source = await ui.select(triggers.length ? 'Also start it when...' : 'Starts when...', [
+                { value: 'linear', label: 'A Linear card gets a label' },
+                { value: 'voidtrack', label: 'A VoidTrack card gets a label' },
+                { value: 'cron', label: 'On a schedule', hint: 'runs on a standing task, no card' },
+            ], 'linear');
+            if (source === 'cron') {
+                const schedule = (await ui.text('Cron schedule (minute hour day month weekday)', { initial: '0 5 * * 1', validate: (v) => (parseCron(v) ? undefined : 'Five fields, like 0 5 * * 1') })).trim();
+                const task = (await ui.text('What should each run work on?', { placeholder: 'Update the dependencies and fix what breaks', validate: (v) => (v.trim() ? undefined : 'Required') })).trim();
+                triggers.push({ source: 'cron', schedule, task });
+                continue;
+            }
+            const team = source === 'linear' && teams.length
+                ? await ui.select('A card in which Linear team...', teams.map((t) => ({ value: t.key, label: `${t.key}  ${t.name}`, hint: t.mine ? 'your team' : undefined })), myTeams.length === 1 ? myTeams[0].key : undefined)
+                : (await ui.text(`A card in which ${TRACKERS[source].name} team key...`, { validate: (v) => (v.trim() ? undefined : 'Required') })).trim().toUpperCase();
             const label = (await ui.text('...gets which label?', { initial: 'vs-plan', validate: (v) => (v.trim() ? undefined : 'Required') })).trim();
-            triggers.push({ source: 'linear', team, label });
+            triggers.push({ source, team, label });
         } while (await ui.confirm('Add another way to start this workflow?', false));
     }
     let steps = w.steps?.length && (await keep('steps', describeSteps(w.steps))) ? w.steps : undefined;
@@ -341,7 +359,7 @@ async function setupWorkflows(ui, config, teams, log) {
 // One entry per command, in the order help lists them.
 const USAGE = [
     ['workflows [--json]', 'List workflows in the order they match'],
-    ['workflow add [NAME] [--trigger TEAM:LABEL]... [--steps dev,qa | --template build] [--project P] [--rounds N]', 'Create a workflow; prompts for what is missing'],
+    ['workflow add [NAME] [--trigger TEAM:LABEL]... [--steps dev,qa | --template build] [--project P] [--rounds N]', 'Create a workflow; prompts for what is missing. A trigger is TEAM:LABEL (Linear), voidtrack:TEAM:LABEL or "cron:SCHEDULE:TASK"'],
     ['workflow show NAME [--json]', 'Show one workflow'],
     ['workflow edit NAME [--trigger T:L]... [--add-trigger T:L] [--remove-trigger T:L] [--steps S | --template T] [--project P] [--rounds N]', 'Change a workflow; no flags asks'],
     ['workflow rename OLD NEW', 'Rename a workflow, keeping its place'],
@@ -356,7 +374,9 @@ const USAGE = [
     ['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'],
-    ['key', 'Store or replace the Linear API key (reads stdin without a terminal)'],
+    ['key [--voidtrack]', 'Store or replace the Linear or VoidTrack API key (reads stdin without a terminal)'],
+    ['profile [init]', `Your profile: rules (${RULES_FILE}) and Claude settings (${CLAUDE_SETTINGS}) every agent run carries; init creates it`],
+    ['validate [DIR]', `Check an agent folder (DIR/${AGENT_FILE} and its prompts), or the config and every folder under agents/defs`],
     ['help [COMMAND]', 'Show this list, or one command'],
 ];
 const usageOf = (name) => USAGE.filter(([c]) => c === name || c.startsWith(`${name} `))
@@ -441,7 +461,7 @@ function readWorkflowFlags(v, config) {
         for (const t of v.trigger) {
             const parsed = parseTrigger(t);
             if (!parsed)
-                return { error: `Bad trigger ${t}. Use TEAM:LABEL, like ENG:vs-plan.`, code: 2 };
+                return { error: `Bad trigger ${t}. Use ${TRIGGER_FORMS}.`, code: 2 };
             flags.triggers.push(parsed);
         }
     }
@@ -487,6 +507,14 @@ function pickWorkflow(config, input, ctx) {
     }
     return r.name;
 }
+// A workflow from an agent folder is changed by editing its file. True (and
+// says so) when `name` is one.
+function inFolder(config, name, ctx) {
+    const dir = config.folders?.[name];
+    if (dir)
+        ctx.log(`${name} is defined in ${tilde(join(dir, AGENT_FILE))}; edit that file.`);
+    return !!dir;
+}
 async function teamsOrNull(ctx) {
     try {
         return await linear(ctx.configDir).teams();
@@ -590,7 +618,7 @@ const workflowSubs = {
         else {
             ctx.log(`Workflow ${name}: ${describeWorkflow(w)}`);
             for (const t of w.triggers)
-                ctx.log(`Trigger: ${t.team} + ${t.label}`);
+                ctx.log(`Trigger: ${describeTrigger(t)}${t.source === 'cron' ? `, task: ${t.task}` : ''}`);
             ctx.log(`Steps: ${describeSteps(w.steps)}`);
             ctx.log(`Project: ${w.project}`);
             ctx.log(`Rounds: ${w.maxRounds}`);
@@ -611,6 +639,8 @@ const workflowSubs = {
         const name = pickWorkflow(config, p.positionals[0], ctx);
         if (!name)
             return 1;
+        if (inFolder(config, name, ctx))
+            return 1;
         const flags = readWorkflowFlags(p.values, config);
         if ('error' in flags) {
             ctx.log(flags.error);
@@ -637,7 +667,7 @@ const workflowSubs = {
         for (const t of (v['add-trigger'] ?? [])) {
             const parsed = parseTrigger(t);
             if (!parsed) {
-                ctx.log(`Bad trigger ${t}. Use TEAM:LABEL, like ENG:vs-plan.`);
+                ctx.log(`Bad trigger ${t}. Use ${TRIGGER_FORMS}.`);
                 return 2;
             }
             if (!next.triggers.some((x) => sameTrigger(x, parsed)))
@@ -671,6 +701,8 @@ const workflowSubs = {
         const old = pickWorkflow(config, p.positionals[0], ctx);
         if (!old)
             return 1;
+        if (inFolder(config, old, ctx))
+            return 1;
         const next = p.positionals[1].trim();
         if (!next) {
             ctx.log('The new name cannot be empty.');
@@ -695,6 +727,8 @@ const workflowSubs = {
         const name = pickWorkflow(config, p.positionals[0], ctx);
         if (!name)
             return 1;
+        if (inFolder(config, name, ctx))
+            return 1;
         const ok = await confirmed(`Delete workflow ${name}?`, !!p.values.yes, ctx);
         if (ok === 'refused')
             return 2;
@@ -723,6 +757,8 @@ const workflowSubs = {
         const name = pickWorkflow(config, p.positionals[0], ctx);
         if (!name)
             return 1;
+        if (inFolder(config, name, ctx))
+            return 1;
         let place;
         if (v.first)
             place = { first: true };
@@ -1045,6 +1081,11 @@ const agents = {
                 config.models = { ...DEFAULTS.models };
         }
         config.engine = engine;
+        // What the runner does to agent commits before pushing them.
+        const commits = config.commits ?? {};
+        commits.dropAiTrailers = await ui.confirm('Remove AI co-author lines from agent commits?', commits.dropAiTrailers ?? true);
+        commits.signOff = await ui.confirm('Sign off agent commits (Signed-off-by, for repos that ask for a DCO)?', commits.signOff ?? false);
+        config.commits = commits;
         const name = await currentLinearUser(ctx.configDir);
         if (!name || !(await ui.confirm(`Keep using Linear as ${name}?`))) {
             if (!(await setupKey(ui, ctx.configDir)))
@@ -1053,7 +1094,11 @@ const agents = {
         await setupProjects(ui, config, ctx.log);
         await setupWorkflows(ui, config, await linear(ctx.configDir).teams(), ctx.log);
         writeAgentsConfig(ctx.configDir, config);
-        if (Object.keys(config.workflows).length && (await ui.confirm('Start the background runner now? It checks Linear every minute for cards that start your workflows.'))) {
+        if (trackersInUse(config).includes('voidtrack') && !readSecret(ctx.configDir, 'voidtrack')) {
+            if (!(await setupKey(ui, ctx.configDir, 'voidtrack')))
+                ctx.log('VoidTrack is not connected yet. Run vsf agents key --voidtrack.');
+        }
+        if (Object.keys(config.workflows).length && (await ui.confirm('Start the background runner now? Every minute it checks for cards and schedules that start your workflows.'))) {
             const ok = runnerService().start(ctx.home, [...ctx.selfCommand, 'agents', 'tick'], join(agentsDir(ctx.configDir), 'runner.log'));
             ctx.log(ok ? 'Runner started.' : 'Could not start the runner. Try vsf agents start.');
         }
@@ -1077,12 +1122,19 @@ const agents = {
                 ? { name: `agents in ${homeLabel(h)}`, status: 'ok', detail: `${wanted.length} linked` }
                 : { name: `agents in ${homeLabel(h)}`, status: 'warn', detail: `missing ${missing.join(', ')}`, fix: `vsf agents link ${tilde(h.dir)}` });
         }
-        try {
-            const me = await linear(ctx.configDir).viewer();
-            checks.push({ name: 'Linear', status: 'ok', detail: `connected as ${me.name}` });
-        }
-        catch (err) {
-            checks.push({ name: 'Linear', status: 'fail', detail: err.message, fix: 'vsf agents key' });
+        const inUse = trackersInUse(saved);
+        for (const kind of inUse.length ? inUse : ['linear']) {
+            const { name } = TRACKERS[kind];
+            try {
+                const key = readSecret(ctx.configDir, kind);
+                if (!key)
+                    throw new Error(`No ${name} API key`);
+                const me = await (kind === 'voidtrack' ? createVoidTrack(key) : createLinear(key)).viewer();
+                checks.push({ name, status: 'ok', detail: `connected as ${me.name}` });
+            }
+            catch (err) {
+                checks.push({ name, status: 'fail', detail: err.message, fix: `vsf agents key${kind === 'linear' ? '' : ` --${kind}`}` });
+            }
         }
         const workflows = Object.entries(saved.workflows);
         const broken = workflows.filter(([, c]) => !saved.projects[c.project] || !isRepo(saved.projects[c.project].path)).map(([n]) => n);
@@ -1091,7 +1143,14 @@ const agents = {
             : broken.length
                 ? { name: 'agent workflows', status: 'fail', detail: `${broken.join(', ')} point at a missing project`, fix: 'vsf agents project edit' }
                 : { name: 'agent workflows', status: 'ok', detail: `${workflows.length} ready` });
-        return [...checks, ...(await controlChecks(ctx))];
+        const folders = agentFolders(ctx.configDir);
+        if (folders.length) {
+            const bad = folders.filter((d) => validateAgentFolder(d, saved).length).map((d) => basename(d));
+            checks.push(bad.length
+                ? { name: 'agent folders', status: 'fail', detail: `${bad.join(', ')} ${bad.length === 1 ? 'has' : 'have'} problems`, fix: 'vsf agents validate' }
+                : { name: 'agent folders', status: 'ok', detail: `${folders.length} valid` });
+        }
+        return [...checks, ...profileChecks(ctx.configDir), ...(await controlChecks(ctx))];
     },
     commands: {
         ...controlCommands,
@@ -1101,7 +1160,7 @@ const agents = {
                 return p;
             const config = readAgentsConfig(ctx.configDir);
             if (p.values.json)
-                out(ctx, Object.entries(config.workflows).map(([name, w]) => ({ name, ...w })));
+                out(ctx, Object.entries(config.workflows).map(([name, w]) => ({ name, ...w, steps: w.steps.map(stepId) })));
             else if (!Object.keys(config.workflows).length)
                 ctx.log('No workflows yet. vsf agents workflow add creates one.');
             else
@@ -1115,6 +1174,58 @@ const agents = {
             return 0;
         },
         workflow: (args, ctx) => group('workflow', workflowSubs, args, ctx),
+        async profile(args, ctx) {
+            const p = begin('profile', args, {}, ctx);
+            if (typeof p === 'number')
+                return p;
+            const dir = profileDir(ctx.configDir);
+            if (p.positionals[0] === 'init') {
+                const made = initProfile(ctx.configDir);
+                ctx.log(made.length ? `Created ${made.join(', ')} in ${tilde(dir)}.` : `${tilde(dir)} already exists; nothing changed.`);
+                return 0;
+            }
+            if (p.positionals.length) {
+                ctx.log(usageOf('profile'));
+                return 2;
+            }
+            ctx.log(`Profile: ${tilde(dir)}${existsSync(dir) ? '' : ' (not created yet: vsf agents profile init)'}`);
+            const rules = readRules(ctx.configDir).replace(/<!--[\s\S]*?-->/g, '').trim();
+            ctx.log(`Rules: ${rules ? `${rules.split('\n').length} lines in ${RULES_FILE}, added to every step's prompt` : 'none'}`);
+            let settings = 'none';
+            try {
+                settings = renderClaudeSettings(ctx.configDir) === null ? 'none' : `${CLAUDE_SETTINGS}, passed to every Claude run`;
+            }
+            catch (err) {
+                settings = `broken: ${err.message}`;
+            }
+            ctx.log(`Claude settings: ${settings}`);
+            const c = readAgentsConfig(ctx.configDir).commits ?? {};
+            ctx.log(`Commits: ${[c.dropAiTrailers ? 'AI co-author lines removed' : 'AI lines kept', c.signOff ? 'signed off' : 'not signed off'].join(', ')} (commits in the agents config)`);
+            return 0;
+        },
+        async validate(args, ctx) {
+            const p = begin('validate', args, {}, ctx);
+            if (typeof p === 'number')
+                return p;
+            if (p.positionals.length > 1) {
+                ctx.log('Give one folder at most.');
+                ctx.log(usageOf('validate'));
+                return 2;
+            }
+            const config = readAgentsConfig(ctx.configDir);
+            const problems = [];
+            const dirs = p.positionals.length ? [resolve(expandHome(p.positionals[0]))] : agentFolders(ctx.configDir);
+            if (!p.positionals.length)
+                problems.push(...validateConfig(config));
+            for (const dir of dirs)
+                for (const line of validateAgentFolder(dir, config))
+                    problems.push(`${basename(dir)}: ${line}`);
+            for (const line of problems)
+                ctx.log(line);
+            if (!problems.length)
+                ctx.log(p.positionals.length ? `${basename(dirs[0])} is valid.` : `Config and ${plural(dirs.length, 'agent folder')} are valid.`);
+            return problems.length ? 1 : 0;
+        },
         async projects(args, ctx) {
             const p = begin('projects', args, { json: { type: 'boolean' } }, ctx);
             if (typeof p === 'number')
@@ -1134,21 +1245,26 @@ const agents = {
         link: homeCommands.link,
         unlink: homeCommands.unlink,
         async key(args, ctx) {
-            const p = begin('key', args, {}, ctx);
+            const p = begin('key', args, { voidtrack: { type: 'boolean' } }, ctx);
             if (typeof p === 'number')
                 return p;
             if (p.positionals.length) {
                 ctx.log('Keys are not accepted on the command line. Pipe the key in instead.');
                 return 2;
             }
+            const kind = p.values.voidtrack ? 'voidtrack' : 'linear';
             if (interactive())
-                return (await setupKey(ctx.ui, ctx.configDir)) ? 0 : 1;
+                return (await setupKey(ctx.ui, ctx.configDir, kind)) ? 0 : 1;
             const key = readFileSync(0, 'utf8').trim();
-            if (!looksLikeLinearKey(key)) {
+            if (kind === 'linear' && !looksLikeLinearKey(key)) {
                 ctx.log('Linear keys start with lin_api_');
                 return 2;
             }
-            return (await verifyAndStore(ctx.configDir, key, ctx.log, ctx.log)) ? 0 : 1;
+            if (!key) {
+                ctx.log('No key on stdin.');
+                return 2;
+            }
+            return (await verifyAndStore(ctx.configDir, key, ctx.log, ctx.log, kind)) ? 0 : 1;
         },
         async help(args, ctx) {
             const want = args.join(' ').trim();

package/dist/linear.d.ts

@@ -20,7 +20,7 @@ export declare function createLinear(apiKey: string): {
         name: string;
         mine: boolean;
     }[]>;
-    myCardsWithLabel(label: string): Promise<Card[]>;
+    myCardsWithLabel(label: string, team: string): Promise<Card[]>;
     card(identifier: string): Promise<Card>;
     comments(identifier: string): Promise<{
         body: string;

package/dist/linear.js

@@ -79,14 +79,14 @@ export function createLinear(apiKey) {
             const all = d?.teams?.nodes ?? [];
             return all.map((t) => ({ ...t, mine: mine.has(t.key) })).sort((a, b) => Number(b.mine) - Number(a.mine));
         },
-        // My cards carrying the trigger label.
-        async myCardsWithLabel(label) {
+        // My cards in the team carrying the trigger label.
+        async myCardsWithLabel(label, team) {
             const d = await gql('myCards', `query MyCards($label: String!) {
           issues(first: 20, orderBy: createdAt, filter: { assignee: { isMe: { eq: true } }, labels: { name: { eq: $label } } }) {
             nodes { ${CARD_FIELDS} }
           }
         }`, { label });
-            return (d?.issues?.nodes ?? []).map(mapCard);
+            return (d?.issues?.nodes ?? []).map(mapCard).filter((c) => c.teamKey === team);
         },
         async card(identifier) {
             const d = await gql('card', `query Card($id: String!) { issue(id: $id) { ${CARD_FIELDS} } }`, { id: identifier });

package/dist/manage.d.ts

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