@voidlabs.gg/voidshift-agents 0.6.0 → 0.7.0

package/dist/control.d.ts

@@ -28,6 +28,7 @@ export declare function trackerWarnings(kinds: Kind[], trackers: Trackers): Prom
     kind: Kind;
     message: string;
 }[]>;
+export declare function changePaused(ctx: Pick<ToolContext, 'configDir' | 'log'>, paused: boolean, reason: string, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
 export declare function workingLine(current: (Current & {
     elapsedMinutes: number;
 }) | null): string;

package/dist/control.js

@@ -9,6 +9,7 @@ import { TRACKERS, trackersFor } from "./tracker.js";
 import { parseFrom, resolveName, stepNames } from "./names.js";
 import { isStatusLabel } from "./workflow.js";
 import { cancelCard, dispatch, tick } from "./runner.js";
+import { notifyRun, notifyRunner, sendSummary } from "./notify.js";
 const HOUR = 3_600_000;
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const CARD_ID = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
@@ -246,6 +247,13 @@ export async function trackerWarnings(kinds, trackers) {
     }
     return out;
 }
+// Pauses or resumes the runner, and pings Discord only when that changed something.
+export async function changePaused(ctx, paused, reason, fetcher = fetch, platform = process.platform) {
+    const was = isPaused(ctx.configDir);
+    setPaused(ctx.configDir, paused);
+    if (was !== paused)
+        await notifyRunner(ctx.configDir, paused, reason, ctx.log, fetcher, platform);
+}
 async function startCmd(ctx) {
     if (!Object.keys(readAgentsConfig(ctx.configDir).workflows).length) {
         ctx.log('No workflows yet. Create one first: vsf agents workflow add.');
@@ -254,7 +262,7 @@ async function startCmd(ctx) {
     for (const w of await trackerWarnings(trackersInUse(readAgentsConfig(ctx.configDir)), trackersFor(ctx.configDir))) {
         ctx.log(`Warning: ${w.message.replace(/\.?$/, '.')} Workflows on ${TRACKERS[w.kind].name} are skipped until then.`);
     }
-    setPaused(ctx.configDir, false);
+    await changePaused(ctx, false, 'by vsf agents start');
     if (!runnerService().start(ctx.home, program(ctx), logPath(ctx.configDir))) {
         ctx.log('Could not start the runner. Check vsf agents logs.');
         return 1;
@@ -366,7 +374,7 @@ const pause = guard(async (args, ctx) => {
     const p = parse('pause', args, {}, ctx);
     if (typeof p === 'number')
         return p;
-    setPaused(ctx.configDir, true);
+    await changePaused(ctx, true, 'by vsf agents pause');
     ctx.log('Paused. The runner picks up no new cards; a card in progress carries on. vsf agents resume to continue.');
     return 0;
 });
@@ -374,7 +382,7 @@ const resume = guard(async (args, ctx) => {
     const p = parse('resume', args, {}, ctx);
     if (typeof p === 'number')
         return p;
-    setPaused(ctx.configDir, false);
+    await changePaused(ctx, false, 'by vsf agents resume');
     ctx.log('Resumed.');
     return 0;
 });
@@ -720,7 +728,11 @@ const tickCmd = async (args, ctx) => {
     try {
         const { values } = parseArgs({ args, options: { card: { type: 'string' }, workflow: { type: 'string' }, schedule: { type: 'string' } }, strict: true });
         const config = readAgentsConfig(ctx.configDir);
-        const rc = { configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand };
+        const rc = {
+            configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand,
+            notify: (e) => notifyRun(ctx.configDir, e, stamped),
+            summary: (paused) => sendSummary(ctx.configDir, paused, stamped),
+        };
         if (values.card || values.workflow)
             return await tick(rc, values.card?.toUpperCase(), { workflow: values.workflow, schedule: values.schedule, child: true });
         return await dispatch(rc, { reload: () => readAgentsConfig(ctx.configDir) });

package/dist/index.js

@@ -9,6 +9,7 @@ import { controlChecks, controlCommands, controlUsage } from "./control.js";
 import { keyStore, looksLikeLinearKey, readLinearKey, readSecret, storeLinearKey, storeSecret } from "./secrets.js";
 import { TRACKERS } from "./tracker.js";
 import { createVoidTrack } from "./voidtrack.js";
+import { addWebhook, dropWebhook, looksLikeWebhook, moveWebhook, removeWebhook, testWebhook, webhookFor } from "./notify.js";
 import { parseCron } from "./cron.js";
 import { trackersInUse } from "./control.js";
 import { runnerService } from "./service.js";
@@ -379,6 +380,7 @@ const USAGE = [
     ['link DIR [--claude | --codex]', 'Link the agents into a config folder'],
     ['unlink DIR', 'Remove the agents from a config folder'],
     ['key [--voidtrack]', 'Store or replace the Linear or VoidTrack API key (reads stdin without a terminal)'],
+    ['discord [--workflow W] [--test] [--rm]', 'Store, test or remove the Discord webhook for run pings, global or for one workflow; it is stored only after a test message goes through (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'],
@@ -662,8 +664,14 @@ const workflowSubs = {
             if (!teams)
                 return 1;
             const r = await promptWorkflow(ctx.ui, config, teams, { name, workflow: current }, true);
-            if (r.name !== name)
+            if (r.name !== name) {
+                const refused = moveWebhook(ctx.configDir, name, r.name);
+                if (refused) {
+                    ctx.log(refused);
+                    return 1;
+                }
                 config.workflows = renameKey(config.workflows, name, r.name);
+            }
             config.workflows[r.name] = r.workflow;
             return saveWorkflow(config, r.name, r.workflow, ctx);
         }
@@ -716,6 +724,11 @@ const workflowSubs = {
             ctx.log(`A workflow named ${next} already exists.`);
             return 1;
         }
+        const refused = moveWebhook(ctx.configDir, old, next);
+        if (refused) {
+            ctx.log(refused);
+            return 1;
+        }
         config.workflows = renameKey(config.workflows, old, next);
         save(ctx, config);
         ctx.log(`Workflow ${old} is now ${next}.`);
@@ -742,6 +755,7 @@ const workflowSubs = {
         }
         delete config.workflows[name];
         save(ctx, config);
+        dropWebhook(ctx.configDir, name);
         ctx.log(`Deleted workflow ${name}.`);
         return 0;
     },
@@ -1220,6 +1234,11 @@ const agents = {
             if (!(await setupKey(ui, ctx.configDir, 'voidtrack')))
                 ctx.log('VoidTrack is not connected yet. Run vsf agents key --voidtrack.');
         }
+        if (!webhookFor(ctx.configDir) && (await ui.confirm('Send run pings to Discord?', false))) {
+            const url = await ui.secret('Paste the Discord webhook URL', (v) => (looksLikeWebhook(v.trim()) ? undefined : 'Not a Discord webhook URL'));
+            if (!(await addWebhook(ctx.configDir, url.trim(), undefined, ui.info)))
+                ctx.log('Discord is not connected. Run vsf agents discord to retry.');
+        }
         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.');
@@ -1258,6 +1277,8 @@ const agents = {
                 checks.push({ name, status: 'fail', detail: err.message, fix: `vsf agents key${kind === 'linear' ? '' : ` --${kind}`}` });
             }
         }
+        if (webhookFor(ctx.configDir))
+            checks.push({ name: 'discord', status: 'ok', detail: 'webhook set' });
         const workflows = Object.entries(saved.workflows);
         const broken = workflows.filter(([, c]) => !saved.projects[c.project] || !isRepo(saved.projects[c.project].path)).map(([n]) => n);
         checks.push(!workflows.length
@@ -1389,6 +1410,38 @@ const agents = {
             }
             return (await verifyAndStore(ctx.configDir, key, ctx.log, ctx.log, kind)) ? 0 : 1;
         },
+        async discord(args, ctx) {
+            const p = begin('discord', args, { workflow: { type: 'string' }, test: { type: 'boolean' }, rm: { type: 'boolean' } }, ctx);
+            if (typeof p === 'number')
+                return p;
+            if (p.positionals.length) {
+                ctx.log('Webhooks are not accepted on the command line. Pipe the URL in instead.');
+                return 2;
+            }
+            if (p.values.test && p.values.rm) {
+                ctx.log('Give --test or --rm, not both.');
+                return 2;
+            }
+            let workflow;
+            if (p.values.workflow) {
+                const name = pickWorkflow(readAgentsConfig(ctx.configDir), p.values.workflow, ctx);
+                if (!name)
+                    return 1;
+                workflow = name;
+            }
+            if (p.values.test)
+                return (await testWebhook(ctx.configDir, workflow, ctx.log)) ? 0 : 1;
+            if (p.values.rm)
+                return removeWebhook(ctx.configDir, workflow, ctx.log) ? 0 : 1;
+            const url = interactive()
+                ? await ctx.ui.secret('Paste the Discord webhook URL', (v) => (looksLikeWebhook(v.trim()) ? undefined : 'Not a Discord webhook URL'))
+                : readFileSync(0, 'utf8');
+            if (!url.trim()) {
+                ctx.log('No webhook on stdin.');
+                return 2;
+            }
+            return (await addWebhook(ctx.configDir, url.trim(), workflow, ctx.log)) ? 0 : 1;
+        },
         async help(args, ctx) {
             const want = args.join(' ').trim();
             if (!want) {

package/dist/notify.d.ts

@@ -0,0 +1,30 @@
+export declare const looksLikeWebhook: (url: string) => boolean;
+export declare const slug: (name: string) => string;
+export declare const webhookFor: (configDir: string, workflow?: string, platform?: NodeJS.Platform) => string | null;
+export declare function postDiscord(url: string, content: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<string | null>;
+export type RunKind = 'ready' | 'passed' | 'parked' | 'failed';
+export interface RunEvent {
+    kind: RunKind;
+    card: string;
+    title: string;
+    workflow: string;
+    url?: string;
+    prUrl?: string;
+    reason?: string;
+}
+export declare function runMessage(e: RunEvent): string;
+export declare function notifyRun(configDir: string, e: RunEvent, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
+export declare function notifyRunner(configDir: string, paused: boolean, reason: string, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
+export interface NotifyState {
+    summaryDay?: string;
+    summaryAt?: string;
+}
+export declare function readNotifyState(configDir: string): NotifyState;
+export declare function writeNotifyState(configDir: string, state: NotifyState): void;
+export declare function summaryMessage(configDir: string, since: Date, paused: boolean): string | null;
+export declare function sendSummary(configDir: string, paused: boolean, log: (line: string) => void, now?: Date, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
+export declare function addWebhook(configDir: string, url: string, workflow: string | undefined, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<boolean>;
+export declare function testWebhook(configDir: string, workflow: string | undefined, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<boolean>;
+export declare function removeWebhook(configDir: string, workflow: string | undefined, log: (line: string) => void, platform?: NodeJS.Platform): boolean;
+export declare function moveWebhook(configDir: string, from: string, to: string, platform?: NodeJS.Platform): string | null;
+export declare function dropWebhook(configDir: string, workflow: string, platform?: NodeJS.Platform): void;

package/dist/notify.js

@@ -0,0 +1,233 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentsDir, readAgentsConfig } from "./config.js";
+import { keyStore, readSecret, removeSecret, storeSecret } from "./secrets.js";
+import { listRuns } from "./state.js";
+// Run pings go to a Discord webhook: one global, and optionally one per
+// workflow that wins over it. Both are kept as secrets.
+const WEBHOOK = /^https:\/\/(discord\.com|discordapp\.com|ptb\.discord\.com|canary\.discord\.com)\/api\/webhooks\/\d+\/[A-Za-z0-9_-]+$/;
+const LIMIT = 2000;
+const TIMEOUT_MS = 5000;
+export const looksLikeWebhook = (url) => WEBHOOK.test(url);
+// A workflow name as it can appear in a secret name.
+export const slug = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const secretName = (workflow) => (workflow ? `discord-${slug(workflow)}` : 'discord');
+// Never throws: a secrets file that cannot be read means no ping.
+function readWebhook(configDir, workflow, platform) {
+    if (workflow !== undefined && !slug(workflow))
+        return null;
+    try {
+        return readSecret(configDir, secretName(workflow), platform);
+    }
+    catch {
+        return null;
+    }
+}
+// The workflow's own webhook, else the global one.
+export const webhookFor = (configDir, workflow, platform = process.platform) => (workflow ? readWebhook(configDir, workflow, platform) : null) ?? readWebhook(configDir, undefined, platform);
+// Posts one message. Never throws: returns why it failed, or null. A slow
+// network gives up after the timeout, even when the fetch ignores its signal.
+export async function postDiscord(url, content, fetcher = fetch, timeoutMs = TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(`no answer from Discord in ${timeoutMs / 1000}s`), timeoutMs);
+    });
+    const send = (async () => {
+        try {
+            const res = await fetcher(url, {
+                method: 'POST',
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { 'Content-Type': 'application/json' },
+                // No mentions are parsed, so card text can never ping anyone.
+                body: JSON.stringify({ content: content.slice(0, LIMIT), username: 'VoidShift', allowed_mentions: { parse: [] } }),
+            });
+            return res.ok ? null : `Discord answered ${res.status}`;
+        }
+        catch (err) {
+            const cause = err.cause;
+            return `could not reach Discord (${cause?.code ?? cause?.message ?? err.message})`;
+        }
+    })();
+    try {
+        return await Promise.race([send, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const HEADINGS = { ready: 'PR ready', passed: 'Checks passed', parked: 'Parked', failed: 'Failed' };
+export function runMessage(e) {
+    const link = e.prUrl || e.url;
+    const reason = (e.kind === 'parked' || e.kind === 'failed') && e.reason ? e.reason.slice(0, 300) : '';
+    return [`**${HEADINGS[e.kind]}** ${e.card} ${e.title}, workflow ${e.workflow}`, link ?? '', reason].filter(Boolean).join('\n');
+}
+// Pings the run's webhook, if one is set. Logs a failure and never throws.
+export async function notifyRun(configDir, e, log, fetcher = fetch, platform = process.platform) {
+    const url = webhookFor(configDir, e.workflow, platform);
+    if (!url)
+        return;
+    const err = await postDiscord(url, runMessage(e), fetcher);
+    if (err)
+        log(`discord: ${err}`);
+}
+// The runner paused or resumed, with why; a budget pause can use it too.
+export async function notifyRunner(configDir, paused, reason, log, fetcher = fetch, platform = process.platform) {
+    const url = webhookFor(configDir, undefined, platform);
+    if (!url)
+        return;
+    const err = await postDiscord(url, `**Runner ${paused ? 'paused' : 'resumed'}** ${reason}`, fetcher);
+    if (err)
+        log(`discord: ${err}`);
+}
+const notifyPath = (configDir) => join(agentsDir(configDir), 'notify.json');
+export function readNotifyState(configDir) {
+    try {
+        return JSON.parse(readFileSync(notifyPath(configDir), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeNotifyState(configDir, state) {
+    mkdirSync(agentsDir(configDir), { recursive: true });
+    writeFileSync(notifyPath(configDir), JSON.stringify(state, null, 2) + '\n');
+}
+const SUMMARY_HOUR = 9;
+const DAY = 86_400_000;
+const localDay = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+// Runs ended since the last summary (or the last day), counted by outcome,
+// with the pull requests and parked cards.
+export function summaryMessage(configDir, since, paused) {
+    const runs = listRuns(configDir)
+        .map((e) => e.record)
+        .filter((r) => r && r.outcome !== 'running' && r.endedAt && Date.parse(r.endedAt) > since.getTime());
+    if (!runs.length)
+        return null;
+    const counts = new Map();
+    for (const r of runs)
+        counts.set(r.outcome, (counts.get(r.outcome) ?? 0) + 1);
+    const prs = runs.filter((r) => r.outcome === 'verified' && r.prUrl).slice(0, 10);
+    const parked = runs.filter((r) => r.outcome === 'parked').slice(0, 10);
+    const lines = [`**Daily summary** ${[...counts].map(([o, n]) => `${n} ${o}`).join(', ')}`];
+    if (paused)
+        lines.push('Runner paused');
+    if (prs.length)
+        lines.push('PRs:', ...prs.map((r) => `${r.card} ${r.prUrl}`));
+    if (parked.length)
+        lines.push('Parked:', ...parked.map((r) => `${r.card} ${r.title}${r.reason ? `: ${r.reason.slice(0, 120)}` : ''}`));
+    return lines.join('\n');
+}
+// Sends the summary once a day, on the first call at or after 09:00 local.
+// The day is recorded before posting, so overlapping calls send it once.
+export async function sendSummary(configDir, paused, log, now = new Date(), fetcher = fetch, platform = process.platform) {
+    try {
+        if (now.getHours() < SUMMARY_HOUR)
+            return;
+        const state = readNotifyState(configDir);
+        const today = localDay(now);
+        if (state.summaryDay === today)
+            return;
+        const url = webhookFor(configDir, undefined, platform);
+        if (!url)
+            return;
+        const since = state.summaryAt ? new Date(state.summaryAt) : new Date(now.getTime() - DAY);
+        writeNotifyState(configDir, { summaryDay: today, summaryAt: now.toISOString() });
+        const message = summaryMessage(configDir, since, paused);
+        if (!message)
+            return;
+        const err = await postDiscord(url, message, fetcher);
+        if (err)
+            log(`discord: ${err}`);
+    }
+    catch (err) {
+        log(`discord: ${err.message}`);
+    }
+}
+// Why an override cannot be kept for this workflow, or null.
+function overrideProblem(configDir, workflow) {
+    const s = slug(workflow);
+    if (!s)
+        return `Workflow ${workflow} has no letters or digits, so it cannot have its own webhook.`;
+    const other = Object.keys(readAgentsConfig(configDir).workflows).find((n) => n !== workflow && slug(n) === s);
+    return other ? `Workflows ${workflow} and ${other} would share a webhook. Rename one first.` : null;
+}
+// Tests the webhook with one message and stores it only when that worked.
+export async function addWebhook(configDir, url, workflow, log, fetcher = fetch, platform = process.platform) {
+    if (!looksLikeWebhook(url)) {
+        log('That is not a Discord webhook URL. It looks like https://discord.com/api/webhooks/123/abc.');
+        return false;
+    }
+    const problem = workflow ? overrideProblem(configDir, workflow) : null;
+    if (problem) {
+        log(problem);
+        return false;
+    }
+    const err = await postDiscord(url, `VoidShift is connected. Run pings${workflow ? ` for workflow ${workflow}` : ''} come here.`, fetcher);
+    if (err) {
+        log(`Discord did not take the test message: ${err}. Nothing was stored.`);
+        return false;
+    }
+    if (!storeSecret(configDir, secretName(workflow), url, platform)) {
+        log(`Discord took the test message but the webhook could not be stored in ${keyStore(platform)}.`);
+        return false;
+    }
+    log(`Webhook${workflow ? ` for workflow ${workflow}` : ''} stored in ${keyStore(platform)}. A test message was sent.`);
+    return true;
+}
+// Sends a test message to the webhook a workflow's runs would use.
+export async function testWebhook(configDir, workflow, log, fetcher = fetch, platform = process.platform) {
+    const url = webhookFor(configDir, workflow, platform);
+    if (!url) {
+        log('No webhook set. Run vsf agents discord to add one.');
+        return false;
+    }
+    const err = await postDiscord(url, `Test message from VoidShift${workflow ? ` for workflow ${workflow}` : ''}.`, fetcher);
+    log(err ? `discord: ${err}` : 'Test message sent.');
+    return !err;
+}
+export function removeWebhook(configDir, workflow, log, platform = process.platform) {
+    if (!readWebhook(configDir, workflow, platform)) {
+        log('No webhook set.');
+        return true;
+    }
+    if (!removeSecret(configDir, secretName(workflow), platform)) {
+        log(`Could not remove the webhook from ${keyStore(platform)}.`);
+        return false;
+    }
+    log(`Webhook${workflow ? ` for workflow ${workflow}` : ''} removed.`);
+    return true;
+}
+// Carries a workflow's webhook across a rename. Returns why the rename must
+// not go ahead, or null; nothing is changed when it refuses.
+export function moveWebhook(configDir, from, to, platform = process.platform) {
+    if (slug(from) === slug(to))
+        return null;
+    const mine = readWebhook(configDir, from, platform);
+    const theirs = slug(to) ? readWebhook(configDir, to, platform) : null;
+    if (!mine && !theirs)
+        return null;
+    if (!slug(to))
+        return `${to} has no letters or digits, so workflow ${from} would lose its webhook. Pick another name.`;
+    const other = Object.keys(readAgentsConfig(configDir).workflows).find((n) => n !== from && slug(n) === slug(to));
+    if (other)
+        return `Workflow ${other} would share a webhook with ${to}. Pick another name.`;
+    // A webhook left behind by a deleted workflow is not inherited.
+    if (theirs)
+        removeSecret(configDir, secretName(to), platform);
+    if (mine) {
+        if (!storeSecret(configDir, secretName(to), mine, platform))
+            return `Could not move the webhook of workflow ${from}.`;
+        removeSecret(configDir, secretName(from), platform);
+    }
+    return null;
+}
+// Drops a deleted workflow's webhook. Never throws.
+export function dropWebhook(configDir, workflow, platform = process.platform) {
+    try {
+        if (readWebhook(configDir, workflow, platform))
+            removeSecret(configDir, secretName(workflow), platform);
+    }
+    catch {
+        // nothing more to do
+    }
+}

package/dist/runner.d.ts

@@ -1,12 +1,15 @@
 import { type AgentsConfig, type Workflow, type Project, type Trigger } from './config.ts';
 import type { Card } from './linear.ts';
 import { type Tracker, type Trackers } from './tracker.ts';
+import type { RunEvent } from './notify.ts';
 export interface RunContext {
     configDir: string;
     config: AgentsConfig;
     trackers: Trackers;
     log: (line: string) => void;
     selfCommand: string[];
+    notify?: (event: RunEvent) => Promise<void>;
+    summary?: (paused: boolean) => Promise<void>;
 }
 export declare function summarize(output: string): string;
 export declare function runCard(card: Card, trigger: Trigger, workflowName: string, workflow: Workflow, project: Project, rc: RunContext, opts?: {

package/dist/runner.js

@@ -111,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)] : [])] : [];
@@ -123,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')))
@@ -331,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;
@@ -345,6 +357,9 @@ 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';
 }
 // 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.
@@ -660,7 +675,16 @@ export async function dispatch(rc, over = {}) {
             if (deps.reload)
                 rc = { ...rc, config: deps.reload() };
             await flushPending(rc);
-            if (!isPaused(rc.configDir)) {
+            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 })) {

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/package.json

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