@voidlabs.gg/voidshift-agents 0.4.1 → 0.4.3

package/README.md

@@ -5,7 +5,7 @@ One CLI for the Void dev tools. Install it once, run `vsf` (short for
 defaults you can change. Everything setup does can be seen and changed later
 from the command line.
 
-> Early release. macOS only for now; Windows and Linux are next.
+> Early release. macOS and Linux (awake is macOS only); Windows is next.
 
 ```sh
 npm i -g @voidlabs.gg/voidshift
@@ -104,10 +104,13 @@ to trust the recall hook once: run `/hooks` in Codex.
 - **Your own logins.** Agents run the official `claude` and `codex` CLIs you
   already use, signed in with your own account. VoidShift never reads or
   stores those credentials. The Linear API key for the runner lives in your
-  macOS Keychain.
+  macOS Keychain, or on Linux in `~/.config/voidshift/agents/secrets.json`
+  (mode 0600).
 - **Trust.** The Dev agent can run shell commands inside its copy of the repo
   so it can install and test. Review its pull requests like any other.
 - **Your config** lives in `~/.config/voidshift`.
+- **Linux.** The runner is a systemd user timer. Run
+  `sudo loginctl enable-linger $USER` so it keeps going after you log out.
 
 ```sh
 vsf doctor                     # check everything is set up, and whether an update is out

package/dist/control.d.ts

@@ -1,5 +1,6 @@
 import { type Current, type RunEntry } from './state.ts';
 import type { Check, ToolCommand, ToolContext } from './types.ts';
+export { parsePlistArgs } from './launchd.ts';
 export declare function parseAge(input: string): number | null;
 export declare function formatDuration(ms: number): string;
 export declare function stampDate(stamp: string): Date;
@@ -12,7 +13,6 @@ export declare function scanRunnerErrors(text: string, now: number): {
     count: number;
     last: string;
 };
-export declare function parsePlistArgs(plist: string): string[];
 export declare const controlUsage: Record<string, string>;
 export interface CancelDeps {
     ours: (pid: number) => boolean;

package/dist/control.js

@@ -3,9 +3,9 @@ import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, r
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { agentsDir, readAgentsConfig } from "./config.js";
-import { readLinearKey } from "./keychain.js";
+import { readLinearKey } from "./secrets.js";
 import { isPaused, listRuns, ours, clearCurrent, liveCurrent, readCurrent, setPaused, writeRun } from "./state.js";
-import { plistPath, runnerLoaded, startRunner, stopRunner } from "./launchd.js";
+import { runnerService } from "./service.js";
 import { createLinear } from "./linear.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
 import { isStatusLabel } from "./workflow.js";
@@ -14,8 +14,9 @@ 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+$/;
 const ISO_LINE = /^(\d{4}-\d\d-\d\dT[\d:.]+Z)\s*(.*)$/;
-function linear() {
-    const key = readLinearKey();
+export { parsePlistArgs } from "./launchd.js";
+function linear(configDir) {
+    const key = readLinearKey(configDir);
     if (!key)
         throw new Error('No Linear API key. Run vsf agents key');
     return createLinear(key);
@@ -88,12 +89,6 @@ export function scanRunnerErrors(text, now) {
     }
     return { count: bad.length, last: bad.at(-1) ?? '' };
 }
-// The <string> values of a launchd plist's ProgramArguments.
-export function parsePlistArgs(plist) {
-    const block = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(plist)?.[1] ?? '';
-    const unxml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
-    return [...block.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1]));
-}
 function lastTickOf(text) {
     for (const line of text.split('\n').reverse()) {
         const m = ISO_LINE.exec(line);
@@ -160,7 +155,7 @@ const guard = (fn) => async (args, ctx) => {
 };
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function runnerState(ctx) {
-    if (!runnerLoaded())
+    if (!runnerService().loaded())
         return 'stopped';
     return isPaused(ctx.configDir) ? 'paused' : 'running';
 }
@@ -219,7 +214,7 @@ async function startCmd(ctx) {
         return 1;
     }
     try {
-        await linear().viewer();
+        await linear(ctx.configDir).viewer();
     }
     catch (err) {
         const msg = err.message;
@@ -227,18 +222,18 @@ async function startCmd(ctx) {
         return 1;
     }
     setPaused(ctx.configDir, false);
-    if (!startRunner(ctx.home, program(ctx), logPath(ctx.configDir))) {
+    if (!runnerService().start(ctx.home, program(ctx), logPath(ctx.configDir))) {
         ctx.log('Could not start the runner. Check vsf agents logs.');
         return 1;
     }
     return 0;
 }
 async function stopCmd(ctx) {
-    stopRunner(ctx.home);
-    // launchd may have stopped the pass; finish or tidy up whatever the lock still names.
+    runnerService().stop(ctx.home);
+    // Stopping the runner may have stopped the pass; finish or tidy up whatever the lock still names.
     const c = readCurrent(ctx.configDir);
     if (c)
-        await cancelCurrent(ctx, c, realDeps(ctx, linear));
+        await cancelCurrent(ctx, c, realDeps(ctx, () => linear(ctx.configDir)));
     ctx.log('Runner stopped.');
     return 0;
 }
@@ -358,7 +353,7 @@ const run = guard(async (args, ctx) => {
             return 2;
         }
     }
-    const code = await tick({ configDir: ctx.configDir, config, linear: linear(), log: ctx.log, selfCommand: ctx.selfCommand }, card, { workflow, from });
+    const code = await tick({ configDir: ctx.configDir, config, linear: linear(ctx.configDir), log: ctx.log, selfCommand: ctx.selfCommand }, card, { workflow, from });
     if (!card && code === 0) {
         if (isPaused(ctx.configDir))
             ctx.log('The runner is paused, so nothing was picked up. vsf agents resume, or name a card.');
@@ -383,7 +378,7 @@ const cancel = guard(async (args, ctx) => {
         ctx.log(`${c.card ?? 'Another card'} is running, not ${card}.`);
         return 1;
     }
-    await cancelCurrent(ctx, c, realDeps(ctx, linear));
+    await cancelCurrent(ctx, c, realDeps(ctx, () => linear(ctx.configDir)));
     return 0;
 });
 const retry = guard(async (args, ctx) => {
@@ -399,7 +394,7 @@ const retry = guard(async (args, ctx) => {
     }
     const config = readAgentsConfig(ctx.configDir);
     const names = Object.keys(config.workflows);
-    const l = linear();
+    const l = linear(ctx.configDir);
     const card = await l.card(id);
     const startsOn = (n) => config.workflows[n].triggers.some((t) => t.team === card.teamKey);
     let chosen;
@@ -479,7 +474,7 @@ const show = guard(async (args, ctx) => {
     }
     let labels = null;
     try {
-        labels = (await linear().card(id)).labels;
+        labels = (await linear(ctx.configDir).card(id)).labels;
     }
     catch {
         // live labels are optional
@@ -646,16 +641,16 @@ const clean = guard(async (args, ctx) => {
     ctx.log(`Removed ${plural(worktrees.length, 'worktree')} and ${plural(old.length, 'run')}.`);
     return 0;
 });
-// Internal: launchd runs this every minute.
+// Internal: the runner (launchd or systemd) runs this every minute.
 const tickCmd = async (_args, ctx) => {
     const stamped = (l) => ctx.log(`${new Date().toISOString()} ${l}`);
     try {
         const config = readAgentsConfig(ctx.configDir);
-        if (!readLinearKey()) {
+        if (!readLinearKey(ctx.configDir)) {
             stamped('No Linear API key. Run vsf agents key.');
             return 1;
         }
-        return await tick({ configDir: ctx.configDir, config, linear: linear(), log: stamped, selfCommand: ctx.selfCommand });
+        return await tick({ configDir: ctx.configDir, config, linear: linear(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand });
     }
     catch (err) {
         stamped(`Could not run the check: ${err.message}`);
@@ -690,9 +685,10 @@ export async function controlChecks(ctx) {
         : state === 'paused'
             ? { name: 'agent runner', status: 'warn', detail: 'paused', fix: 'vsf agents resume' }
             : { name: 'agent runner', status: 'warn', detail: 'not running', fix: 'vsf agents start' });
-    const plist = plistPath(ctx.home);
-    if (existsSync(plist)) {
-        const missing = parsePlistArgs(readFileSync(plist, 'utf8')).filter((a) => a.startsWith('/') && !existsSync(a));
+    const service = runnerService();
+    const installed = service.programArgs(ctx.home);
+    if (installed) {
+        const missing = installed.filter((a) => a.startsWith('/') && !existsSync(a));
         checks.push(missing.length
             ? { name: 'runner program', status: 'fail', detail: `runner points at a missing ${missing[0]}`, fix: 'vsf agents restart' }
             : { name: 'runner program', status: 'ok', detail: 'found' });
@@ -706,6 +702,7 @@ export async function controlChecks(ctx) {
             ? { name: 'runner errors', status: 'warn', detail: `${plural(count, 'error')} in the last hour, last: ${last.slice(0, 120)}`, fix: 'vsf agents logs' }
             : { name: 'runner errors', status: 'ok', detail: 'no errors in the last hour' });
     }
+    checks.push(...service.checks());
     checks.push(engineLogin(readAgentsConfig(ctx.configDir).engine));
     return checks;
 }

package/dist/git.d.ts

@@ -24,7 +24,7 @@ export declare function summarizeChecks(text: string): CheckSummary;
 export declare function ciReport(s: CheckSummary): string;
 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';
+    verdict: 'SHIP' | 'FIX' | 'SKIP' | 'PENDING';
     report: string;
 }>;
 export declare function resetWorktree(worktree: string): void;

package/dist/git.js

@@ -124,7 +124,7 @@ export async function waitForChecks(worktree, branch, timeoutMs = 30 * 60_000, s
             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/index.js

@@ -6,8 +6,8 @@ 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 { controlChecks, controlCommands, controlUsage } from "./control.js";
-import { looksLikeLinearKey, readLinearKey, storeLinearKey } from "./keychain.js";
-import { startRunner, stopRunner } from "./launchd.js";
+import { keyStore, looksLikeLinearKey, readLinearKey, storeLinearKey } from "./secrets.js";
+import { runnerService } from "./service.js";
 import { createLinear } from "./linear.js";
 import { duplicateTriggerWarnings, moveKey, parseTrigger, renameKey, sameTrigger, validateConfig, validateWorkflow, workflowsUsing } from "./manage.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
@@ -81,14 +81,14 @@ async function chooseHomes(ui, configDir, saved) {
     return homes;
 }
 // Checks the key against Linear, and only then stores it.
-async function verifyAndStore(key, info, warn) {
+async function verifyAndStore(configDir, key, info, warn) {
     try {
         const me = await createLinear(key).viewer();
-        if (!storeLinearKey(key)) {
-            warn('Linear accepted the key but the Keychain did not store it.');
+        if (!storeLinearKey(configDir, key)) {
+            warn(`Linear accepted the key but it could not be stored in ${keyStore()}.`);
             return null;
         }
-        info(`Linear connected as ${me.name}. Key stored in your macOS Keychain.`);
+        info(`Linear connected as ${me.name}. Key stored in ${keyStore()}.`);
         return me.name;
     }
     catch (err) {
@@ -97,14 +97,14 @@ async function verifyAndStore(key, info, warn) {
     }
 }
 // Asks for the key, checks it against Linear, and only then stores it.
-async function setupKey(ui) {
+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(key.trim(), ui.info, ui.warn);
+    return verifyAndStore(configDir, key.trim(), ui.info, ui.warn);
 }
-async function currentLinearUser() {
+async function currentLinearUser(configDir) {
     try {
-        return readLinearKey() ? (await linear().viewer()).name : null;
+        return readLinearKey(configDir) ? (await linear(configDir).viewer()).name : null;
     }
     catch {
         return null;
@@ -181,8 +181,8 @@ function syncLinks(chosen, all, enabled, log) {
             log(`Agents linked in ${homeLabel(home)}: ${linked} linked${skipped ? `, ${skipped} skipped (something else is already there)` : ''}`);
     }
 }
-function linear() {
-    const key = readLinearKey();
+function linear(configDir) {
+    const key = readLinearKey(configDir);
     if (!key)
         throw new Error('No Linear API key. Run vsf agents key');
     return createLinear(key);
@@ -489,7 +489,7 @@ function pickWorkflow(config, input, ctx) {
 }
 async function teamsOrNull(ctx) {
     try {
-        return await linear().teams();
+        return await linear(ctx.configDir).teams();
     }
     catch (err) {
         ctx.log(`Could not list Linear teams: ${err.message}`);
@@ -1045,22 +1045,22 @@ const agents = {
                 config.models = { ...DEFAULTS.models };
         }
         config.engine = engine;
-        const name = await currentLinearUser();
+        const name = await currentLinearUser(ctx.configDir);
         if (!name || !(await ui.confirm(`Keep using Linear as ${name}?`))) {
-            if (!(await setupKey(ui)))
+            if (!(await setupKey(ui, ctx.configDir)))
                 throw new Error('Linear is not connected. Run vsf setup agents to retry.');
         }
         await setupProjects(ui, config, ctx.log);
-        await setupWorkflows(ui, config, await linear().teams(), 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.'))) {
-            const ok = startRunner(ctx.home, [...ctx.selfCommand, 'agents', 'tick'], join(agentsDir(ctx.configDir), 'runner.log'));
+            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.');
         }
         ctx.log('In Claude Code or Codex, connect Linear too, then use /vs-plan, /vs-plan-review and /vs-publish on a card.');
     },
     async uninstall(ctx) {
-        stopRunner(ctx.home);
+        runnerService().stop(ctx.home);
         syncLinks([], candidateHomes(ctx.configDir, readAgentsConfig(ctx.configDir).homes), [], ctx.log);
         ctx.log('Agents unlinked and the runner stopped. Config and the Linear key were kept.');
     },
@@ -1078,7 +1078,7 @@ const agents = {
                 : { name: `agents in ${homeLabel(h)}`, status: 'warn', detail: `missing ${missing.join(', ')}`, fix: `vsf agents link ${tilde(h.dir)}` });
         }
         try {
-            const me = await linear().viewer();
+            const me = await linear(ctx.configDir).viewer();
             checks.push({ name: 'Linear', status: 'ok', detail: `connected as ${me.name}` });
         }
         catch (err) {
@@ -1142,13 +1142,13 @@ const agents = {
                 return 2;
             }
             if (interactive())
-                return (await setupKey(ctx.ui)) ? 0 : 1;
+                return (await setupKey(ctx.ui, ctx.configDir)) ? 0 : 1;
             const key = readFileSync(0, 'utf8').trim();
             if (!looksLikeLinearKey(key)) {
                 ctx.log('Linear keys start with lin_api_');
                 return 2;
             }
-            return (await verifyAndStore(key, ctx.log, ctx.log)) ? 0 : 1;
+            return (await verifyAndStore(ctx.configDir, key, ctx.log, ctx.log)) ? 0 : 1;
         },
         async help(args, ctx) {
             const want = args.join(' ').trim();

package/dist/launchd.d.ts

@@ -5,3 +5,4 @@ export declare function runnerEnv(): Record<string, string>;
 export declare const runnerLoaded: () => boolean;
 export declare function startRunner(home: string, program: string[], logPath: string): boolean;
 export declare function stopRunner(home: string): void;
+export declare function parsePlistArgs(plist: string): string[];

package/dist/launchd.js

@@ -66,3 +66,9 @@ export function stopRunner(home) {
         launchctl(['bootout', `${domain()}/${LABEL}`]);
     rmSync(plistPath(home), { force: true });
 }
+// The <string> values of a launchd plist's ProgramArguments.
+export function parsePlistArgs(plist) {
+    const block = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(plist)?.[1] ?? '';
+    const unxml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+    return [...block.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1]));
+}

package/dist/runner.js

@@ -155,7 +155,15 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                     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}`);
                     }
-                    const ci = await waitForChecks(worktree, card.branchName);
+                    // 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 };

package/dist/secrets.d.ts

@@ -0,0 +1,9 @@
+export declare const looksLikeLinearKey: (key: string) => boolean;
+export declare const secretsPath: (configDir: string) => string;
+export declare const keyStore: (platform?: NodeJS.Platform) => "your macOS Keychain" | "a file only you can read";
+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 const readLinearKey: (configDir: string) => string | null;
+export declare const storeLinearKey: (configDir: string, key: string) => boolean;

package/dist/secrets.js

@@ -0,0 +1,55 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+import { agentsDir } from "./config.js";
+// Keys live in the macOS Keychain, or on other platforms in a file only this
+// user can read, in the agents config folder.
+const KEY_SHAPE = /^lin_api_[A-Za-z0-9]+$/;
+// Values the Keychain is handed on stdin; anything that could break out of
+// the `security -i` command line is refused.
+const SAFE_VALUE = /^[A-Za-z0-9_\-.:/+=]+$/;
+export const looksLikeLinearKey = (key) => KEY_SHAPE.test(key);
+export const secretsPath = (configDir) => join(agentsDir(configDir), 'secrets.json');
+// Where keys are kept on this machine, for messages.
+export const keyStore = (platform = process.platform) => platform === 'darwin' ? 'your macOS Keychain' : 'a file only you can read';
+// The secrets file, refused when anyone but its owner can read it.
+export function readSecretsFile(path) {
+    if (!existsSync(path))
+        return {};
+    const mode = statSync(path).mode & 0o777;
+    if (mode & 0o077)
+        throw new Error(`${path} can be read by other users (mode ${mode.toString(8)}). Run chmod 600 on it.`);
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+// Written to a temporary file with mode 0600, then renamed into place, so the
+// file is never readable by others, not even for a moment.
+export function writeSecretsFile(path, values) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(values, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}
+const service = (name) => `voidshift-${name}`;
+export function readSecret(configDir, name, platform = process.platform) {
+    if (platform === 'darwin') {
+        const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', service(name), '-w'], { encoding: 'utf8' });
+        return (r.status === 0 ? r.stdout.trim() : '') || null;
+    }
+    return readSecretsFile(secretsPath(configDir))[name] || null;
+}
+export function storeSecret(configDir, name, value, platform = process.platform) {
+    if (!SAFE_VALUE.test(value) || !/^[a-z-]+$/.test(name))
+        return false;
+    if (platform === 'darwin') {
+        // On stdin through `security -i`, so the value never appears in a process list.
+        const command = `add-generic-password -U -s ${service(name)} -a ${userInfo().username} -w ${value}\n`;
+        return spawnSync('/usr/bin/security', ['-i'], { input: command, encoding: 'utf8' }).status === 0;
+    }
+    const path = secretsPath(configDir);
+    writeSecretsFile(path, { ...readSecretsFile(path), [name]: value });
+    return true;
+}
+export const readLinearKey = (configDir) => readSecret(configDir, 'linear');
+export const storeLinearKey = (configDir, key) => looksLikeLinearKey(key) && storeSecret(configDir, 'linear', key);

package/dist/service.d.ts

@@ -0,0 +1,9 @@
+import type { Check } from './types.ts';
+export interface RunnerService {
+    loaded(): boolean;
+    start(home: string, program: string[], logPath: string): boolean;
+    stop(home: string): void;
+    programArgs(home: string): string[] | null;
+    checks(): Check[];
+}
+export declare const runnerService: (platform?: NodeJS.Platform) => RunnerService;

package/dist/service.js

@@ -0,0 +1,18 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as launchd from "./launchd.js";
+import * as systemd from "./systemd.js";
+const mac = {
+    loaded: launchd.runnerLoaded,
+    start: launchd.startRunner,
+    stop: launchd.stopRunner,
+    programArgs: (home) => (existsSync(launchd.plistPath(home)) ? launchd.parsePlistArgs(readFileSync(launchd.plistPath(home), 'utf8')) : null),
+    checks: () => [],
+};
+const linux = {
+    loaded: systemd.runnerLoaded,
+    start: (home, program, logPath) => systemd.startRunner(home, program, launchd.runnerEnv(), logPath),
+    stop: systemd.stopRunner,
+    programArgs: systemd.programArgs,
+    checks: () => [systemd.lingerCheck()],
+};
+export const runnerService = (platform = process.platform) => (platform === 'darwin' ? mac : linux);

package/dist/systemd.d.ts

@@ -0,0 +1,14 @@
+import type { Check } from './types.ts';
+export declare const UNIT = "voidshift-agents";
+export declare const servicePath: (home: string) => string;
+export declare const timerPath: (home: string) => string;
+export declare function quote(s: string): string;
+export declare function unquote(s: string): string;
+export declare function serviceUnit(program: string[], env: Record<string, string>, logPath: string): string;
+export declare const timerUnit: () => string;
+export declare function parseExecStart(unit: string): string[];
+export declare const runnerLoaded: () => boolean;
+export declare function startRunner(home: string, program: string[], env: Record<string, string>, logPath: string): boolean;
+export declare function stopRunner(home: string): void;
+export declare function programArgs(home: string): string[] | null;
+export declare function lingerCheck(): Check;

package/dist/systemd.js

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+// The runner on Linux: a systemd user service that runs one check, and a
+// timer that starts it a minute after the last one finished.
+export const UNIT = 'voidshift-agents';
+const unitDir = (home) => join(process.env.XDG_CONFIG_HOME ?? join(home, '.config'), 'systemd', 'user');
+export const servicePath = (home) => join(unitDir(home), `${UNIT}.service`);
+export const timerPath = (home) => join(unitDir(home), `${UNIT}.timer`);
+// `systemctl --user` needs the user's runtime dir, which a `sudo -iu` or `su`
+// shell does not set.
+function systemctl(args) {
+    const env = { ...process.env, XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${userInfo().uid}` };
+    const r = spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8', env });
+    return { ok: r.status === 0, stdout: (r.stdout ?? '').trim() };
+}
+// One word of a unit file line: quoted, with the characters systemd expands
+// escaped.
+export function quote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%').replace(/\$/g, '$$$$')}"`;
+}
+export function unquote(s) {
+    return s.replace(/\$\$/g, '$').replace(/%%/g, '%').replace(/\\(.)/g, '$1');
+}
+export function serviceUnit(program, env, logPath) {
+    const vars = Object.entries(env).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`);
+    return `[Unit]
+Description=VoidShift agents runner, one check for cards to work on
+
+[Service]
+Type=oneshot
+ExecStart=${program.map(quote).join(' ')}
+${vars.join('\n')}
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
+TimeoutStartSec=infinity
+`;
+}
+export const timerUnit = () => `[Unit]
+Description=Starts the VoidShift agents runner every minute
+
+[Timer]
+OnActiveSec=5s
+OnUnitInactiveSec=60s
+AccuracySec=1s
+
+[Install]
+WantedBy=timers.target
+`;
+// The words of a service unit's ExecStart line.
+export function parseExecStart(unit) {
+    const line = /^ExecStart=(.*)$/m.exec(unit)?.[1] ?? '';
+    return [...line.matchAll(/"((?:\\.|[^"\\])*)"|(\S+)/g)].map((m) => (m[1] !== undefined ? unquote(m[1]) : m[2]));
+}
+export const runnerLoaded = () => systemctl(['is-active', '--quiet', `${UNIT}.timer`]).ok;
+export function startRunner(home, program, env, logPath) {
+    mkdirSync(unitDir(home), { recursive: true });
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(servicePath(home), serviceUnit(program, env, logPath));
+    writeFileSync(timerPath(home), timerUnit());
+    if (!systemctl(['daemon-reload']).ok)
+        return false;
+    systemctl(['restart', `${UNIT}.timer`]);
+    return systemctl(['enable', '--now', `${UNIT}.timer`]).ok;
+}
+export function stopRunner(home) {
+    systemctl(['disable', '--now', `${UNIT}.timer`]);
+    systemctl(['stop', `${UNIT}.service`]);
+    rmSync(servicePath(home), { force: true });
+    rmSync(timerPath(home), { force: true });
+    systemctl(['daemon-reload']);
+}
+export function programArgs(home) {
+    return existsSync(servicePath(home)) ? parseExecStart(readFileSync(servicePath(home), 'utf8')) : null;
+}
+// Without lingering, systemd stops the user's timers when they log out and
+// does not start them after a reboot.
+export function lingerCheck() {
+    const user = userInfo().username;
+    const r = spawnSync('loginctl', ['show-user', user, '--property=Linger', '--value'], { encoding: 'utf8' });
+    return r.status === 0 && r.stdout.trim() === 'yes'
+        ? { name: 'runner after logout', status: 'ok', detail: 'lingering is on, the runner keeps going after logout and reboot' }
+        : { name: 'runner after logout', status: 'warn', detail: 'lingering is off, the runner stops when you log out', fix: `sudo loginctl enable-linger ${user}` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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": {
@@ -18,7 +18,8 @@
     "agents",
     "linear",
     "cli",
-    "macos"
+    "macos",
+    "linux"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -29,9 +30,6 @@
     "LICENSE",
     "README.md"
   ],
-  "os": [
-    "darwin"
-  ],
   "engines": {
     "node": ">=22.18"
   },

package/dist/keychain.d.ts

@@ -1,3 +0,0 @@
-export declare function readLinearKey(): string | null;
-export declare const looksLikeLinearKey: (key: string) => boolean;
-export declare function storeLinearKey(key: string): boolean;

package/dist/keychain.js

@@ -1,19 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import { userInfo } from 'node:os';
-const SERVICE = 'voidshift-linear';
-const KEY_SHAPE = /^lin_api_[A-Za-z0-9]+$/;
-export function readLinearKey() {
-    const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', SERVICE, '-w'], { encoding: 'utf8' });
-    const key = r.status === 0 ? r.stdout.trim() : '';
-    return key || null;
-}
-export const looksLikeLinearKey = (key) => KEY_SHAPE.test(key);
-// Stores the key through `security -i` on stdin, so it never appears in a
-// process list. The shape check above rules out anything that could break
-// out of the command line.
-export function storeLinearKey(key) {
-    if (!looksLikeLinearKey(key))
-        return false;
-    const command = `add-generic-password -U -s ${SERVICE} -a ${userInfo().username} -w ${key}\n`;
-    return spawnSync('/usr/bin/security', ['-i'], { input: command, encoding: 'utf8' }).status === 0;
-}