@pulsehub/runner 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: Pulse Runner
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  smoke:
+    name: smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm test
+      - run: node src/index.js --help

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish Pulse Runner to npm
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - name: Verify release tag matches package version
+        run: test "v$(node -p 'require("./package.json").version')" = "$GITHUB_REF_NAME"
+      - run: npm test
+      - run: node src/index.js --help
+      - run: npm publish --access public

package/README.md

@@ -0,0 +1,17 @@
+# Pulse Runner
+
+Install with Node 20+: `npm install -g @pulsehub/runner`.
+
+To update an existing installation after a new release, run `npm update -g @pulsehub/runner`, then restart the background service with `pulse-runner service stop` followed by `pulse-runner service start`.
+
+Releases are published to npm from GitHub Actions when a GitHub release is published. The release tag (for example, `v0.2.0`) must match the version in `package.json` (`0.2.0`).
+
+Initialize the local machine with its workspace and agent identifiers plus the release signing public key, then paste the public key printed by `init` into Pulse Settings. The current release key is [`keys/runner-job-v1-public.pem`](keys/runner-job-v1-public.pem). Pulse returns a one-time device credential; `pair` derives and stores the Runner ID and credential with owner-only permissions. Use `diagnose` before `start`.
+
+After a successful agent run, the Runner itself pushes every changed `pul/*` branch in the job's signed project worktrees and creates (or detects) its pull request through the local GitHub CLI. This avoids relying on an interactive agent approval for publication; `git` and `gh` must be authenticated locally.
+
+The Runner only uses local Git and provider sessions, creates disposable worktrees under its application-data directory, and deletes per-job MCP configuration after each execution.
+
+## QA review jobs
+
+An agent can use a dedicated Runner identity for QA. To run more than one agent on the same machine, give each instance its own `PULSE_RUNNER_HOME`; initialize and pair each one with its own agent and Runner credential, then run `pulse-runner start` with that same environment variable. Register the QA Runner in Pulse Settings using its generated signing public key, connect every repository that has a PR in the review, pair its one-time device credential, and select it on the QA agent. Review jobs call `pulse_next_review` and `pulse_get_review_context` through Pulse MCP, inspect every PR, and submit their verdict with `pulse_submit_review`. They do not publish source changes or create PRs.

package/keys/runner-job-v1-public.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAbEgk63X5Y/uckKtBXu/e2M1R4RCe0669brRGUXjS5oM=
+-----END PUBLIC KEY-----

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@pulsehub/runner",
+  "version": "0.1.0",
+  "description": "Local, credential-safe Pulse Runner",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rafaeldavid20/pulse-runner.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": { "pulse-runner": "./src/index.js" },
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test", "smoke": "node src/index.js --help" }
+}

package/src/config.js

@@ -0,0 +1,43 @@
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+export function dataDir() {
+  if (process.env.PULSE_RUNNER_HOME) return process.env.PULSE_RUNNER_HOME;
+  if (platform() === 'darwin') return join(homedir(), 'Library', 'Application Support', 'pulse-runner');
+  if (platform() === 'win32') return join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'pulse-runner');
+  return join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'pulse-runner');
+}
+
+export const paths = () => ({ root: dataDir(), config: join(dataDir(), 'config.json'), credential: join(dataDir(), 'device-credential'), repos: join(dataDir(), 'repos'), worktrees: join(dataDir(), 'worktrees'), logs: join(dataDir(), 'logs') });
+
+export async function ensureDataDir() {
+  const p = paths();
+  await Promise.all(Object.values(p).filter((value) => value !== p.config && value !== p.credential).map((value) => mkdir(value, { recursive: true, mode: 0o700 })));
+  return p;
+}
+
+export async function readConfig() {
+  const p = paths();
+  try { return JSON.parse(await readFile(p.config, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+export async function writeConfig(config) {
+  const p = await ensureDataDir();
+  await writeFile(p.config, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await chmod(p.config, 0o600);
+}
+
+export async function readCredential() {
+  try { return (await readFile(paths().credential, 'utf8')).trim(); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+export async function writeCredential(value) {
+  const p = await ensureDataDir();
+  await writeFile(p.credential, `${value}\n`, { mode: 0o600 });
+  await chmod(p.credential, 0o600);
+}
+
+export async function removeTemporary(path) { await rm(path, { force: true, recursive: true }); }

package/src/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { generateKeyPairSync } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { platform } from 'node:os';
+import { ensureDataDir, paths, readConfig, readCredential, removeTemporary, writeConfig, writeCredential } from './config.js';
+import { validateJob, sanitize } from './job.js';
+import { command, executable, runAgent } from './process.js';
+
+const DEFAULT_ENDPOINT = 'https://us-east4-pulse-app-93.cloudfunctions.net';
+const args = process.argv.slice(2);
+const value = (flag) => { const i = args.indexOf(flag); return i < 0 ? undefined : args[i + 1]; };
+const has = (flag) => args.includes(flag);
+const usage = () => console.log(`pulse-runner <init|pair|start|run|diagnose|repo|service>\n\ninit --workspace WS --agent AGENT --signing-public-key FILE --allow-autonomous [--endpoint URL] [--repo owner/repo]\npair --credential runner.secret\nstart | run --once | diagnose | repo add|remove|list | service install|start|stop|status`);
+
+async function request(config, path, body) {
+  const credential = await readCredential();
+  if (!credential) throw new Error('Runner is not paired. Run pulse-runner pair first.');
+  const response = await fetch(`${config.endpoint}/${path}`, { method: 'POST', headers: { Authorization: `Bearer ${credential}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  if (!response.ok) throw new Error(`Pulse endpoint rejected request (${response.status}).`);
+  return response.json();
+}
+
+function repoPath(repo) { return repo.replace('/', '__'); }
+async function checkoutRepo(repo, worktree) {
+  const p = paths(); const mirror = join(p.repos, `${repoPath(repo)}.git`);
+  const existing = await command('git', ['--git-dir', mirror, 'rev-parse', '--git-dir']).catch(() => ({ code: 1, output: '' }));
+  if (existing.code !== 0) {
+    const cloned = await command('git', ['clone', '--mirror', `https://github.com/${repo}.git`, mirror]);
+    if (cloned.code) throw new Error(sanitize(cloned.output));
+  }
+  const fetchResult = await command('git', ['--git-dir', mirror, 'fetch', '--prune', 'origin']); if (fetchResult.code) throw new Error(sanitize(fetchResult.output));
+  const added = await command('git', ['--git-dir', mirror, 'worktree', 'add', '--detach', worktree, 'HEAD']); if (added.code) throw new Error(sanitize(added.output));
+  const base = await command('git', ['-C', worktree, 'rev-parse', 'HEAD']);
+  if (base.code) throw new Error(sanitize(base.output));
+  return { repo, mirror, worktree, baseCommit: base.output.trim() };
+}
+async function checkout(job) {
+  const root = join(paths().worktrees, job.id); const repos = [...new Set(job.contextRepos || [job.repoFullName])]; const checkouts = [];
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  try {
+    for (const repo of repos) {
+      const checkout = await checkoutRepo(repo, join(root, repoPath(repo)));
+      await writeFile(join(checkout.worktree, '.pulse-runner-job'), job.id, { mode: 0o600 });
+      checkouts.push(checkout);
+    }
+    const primary = checkouts.find((checkout) => checkout.repo === job.repoFullName);
+    if (!primary) throw new Error('Job context does not include its target repository.');
+    return { primary, checkouts };
+  } catch (error) { await cleanup(checkouts); await removeTemporary(root); throw error; }
+}
+async function cleanup(checkouts) {
+  await Promise.all(checkouts.map(async ({ worktree, mirror }) => {
+    await command('git', ['--git-dir', mirror, 'worktree', 'remove', '--force', worktree]).catch(() => {});
+    await removeTemporary(worktree);
+  }));
+}
+async function publishCheckout(checkout) {
+  const branchResult = await command('git', ['-C', checkout.worktree, 'branch', '--show-current']);
+  const branch = branchResult.output.trim();
+  if (!branch || !branch.startsWith('pul/')) return '';
+  const status = await command('git', ['-C', checkout.worktree, 'status', '--porcelain']);
+  const uncommitted = status.output.split('\n').filter((line) => line && !line.endsWith('.pulse-runner-job'));
+  if (uncommitted.length > 0) throw new Error(`Uncommitted changes remain in ${checkout.repo}; the agent must commit every changed worktree.`);
+  const head = await command('git', ['-C', checkout.worktree, 'rev-parse', 'HEAD']);
+  if (head.code || head.output.trim() === checkout.baseCommit) return '';
+  // Sólo se publica una rama de trabajo Pulse de un worktree firmado como
+  // contexto de este job. El Runner no elige repos ni destinos externos.
+  const pushed = await command('git', ['-c', 'remote.origin.mirror=false', '--git-dir', checkout.mirror, 'push', 'origin', `refs/heads/${branch}:refs/heads/${branch}`]);
+  if (pushed.code) throw new Error(sanitize(pushed.output));
+  const existing = await command('gh', ['pr', 'view', branch, '--repo', checkout.repo, '--json', 'url']);
+  if (existing.code === 0) return `Published ${checkout.repo}:${branch}; existing PR detected.`;
+  const created = await command('gh', ['pr', 'create', '--repo', checkout.repo, '--base', 'main', '--head', branch, '--fill']);
+  if (created.code) throw new Error(sanitize(created.output));
+  return `Published ${checkout.repo}:${branch}; ${created.output.trim()}`;
+}
+async function publish(checkouts) {
+  const publications = [];
+  for (const checkout of checkouts) {
+    const published = await publishCheckout(checkout);
+    if (published) publications.push(published);
+  }
+  return publications.join('\n');
+}
+async function runOnce(config) {
+  await request(config, 'pulseRunnerHeartbeat', { status: 'online' });
+  const delivery = await request(config, 'pulseRunnerPoll', {}); if (!delivery.job) return false;
+  const job = delivery.job;
+  try {
+    const agent = delivery.agent || { kind: config.agentKind, role: job.agentId === config.agentId ? 'dev' : null };
+    validateJob(job, config, agent); await request(config, 'pulseRunnerHeartbeat', { status: 'busy' });
+    const { primary, checkouts } = await checkout(job); const temp = join(paths().root, 'tmp', job.id);
+    try {
+      const result = await runAgent(agent.kind, job, primary.worktree, checkouts.filter((checkout) => checkout !== primary), config, delivery.mcpCredential, temp);
+      const publication = result.code === 0 && job.mode !== 'review' ? await publish(checkouts) : '';
+      await request(config, 'pulseRunnerComplete', { jobId: job.id, outcome: result.code === 0 ? 'completed' : 'failed', result: sanitize([result.output, publication].filter(Boolean).join('\n')) });
+    } finally { await removeTemporary(temp); await cleanup(checkouts); await removeTemporary(join(paths().worktrees, job.id)); }
+  } catch (error) { await request(config, 'pulseRunnerComplete', { jobId: job.id, outcome: 'failed', result: sanitize(error.message) }).catch(() => {}); throw error; }
+  finally { await request(config, 'pulseRunnerHeartbeat', { status: 'online' }).catch(() => {}); }
+  return true;
+}
+
+async function init() {
+  const publicKeyPath = value('--signing-public-key'); if (!publicKeyPath || !value('--workspace') || !value('--agent')) throw new Error('init requires --workspace, --agent and --signing-public-key.');
+  if (!has('--allow-autonomous')) throw new Error('Autonomous agent execution requires explicit --allow-autonomous confirmation.');
+  const { publicKey } = generateKeyPairSync('ed25519'); const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const signingPublicKey = await readFile(publicKeyPath, 'utf8');
+  await writeConfig({ version: 1, endpoint: value('--endpoint') || DEFAULT_ENDPOINT, workspaceId: value('--workspace'), agentId: value('--agent'), agentKind: value('--agent-kind') || 'codex', signingKeyId: value('--signing-key-id') || 'runner-job-v1', signingPublicKey, repos: args.filter((item, index) => args[index - 1] === '--repo'), autonomousConfirmed: true });
+  console.log(`Public key for pairing:\n${publicKeyPem}\n\nPaste it in Pulse Settings, then run: pulse-runner pair --credential <runner credential>`);
+}
+async function syncRepos(config) { await request(config, 'pulseRunnerConfigure', { connectedRepos: config.repos }); }
+async function repo(config) { const op = args[1]; const name = args[2]; if (op === 'list') return console.log(config.repos.join('\n')); if (!name || !/^[^/\s]+\/[^/\s]+$/.test(name)) throw new Error('Repository must be owner/repo.'); const repos = new Set(config.repos); op === 'add' ? repos.add(name) : repos.delete(name); const updated = { ...config, repos: [...repos].sort() }; await writeConfig(updated); await syncRepos(updated); }
+async function diagnose(config) { const checks = { paired: !!(await readCredential()), git: await executable('git'), githubCli: await executable('gh'), codex: await executable('codex'), claude: await executable('claude'), configuredRepos: config.repos.length, platform: platform() }; console.log(JSON.stringify(checks, null, 2)); if (!checks.git || !checks.githubCli) process.exitCode = 1; }
+async function service(config) {
+  const action = args[1]; const p = paths(); const definition = join(p.root, 'service-install.json'); const pidFile = join(p.root, 'service.pid');
+  if (action === 'install') { await mkdir(p.logs, { recursive: true, mode: 0o700 }); await writeFile(definition, JSON.stringify({ command: process.execPath, args: [new URL('./index.js', import.meta.url).pathname, 'start'], platform: platform() }, null, 2), { mode: 0o600 }); return console.log(`Service definition prepared at ${definition}.`); }
+  if (action === 'status') { try { const { pid } = JSON.parse(await readFile(pidFile, 'utf8')); process.kill(pid, 0); return console.log(`Pulse Runner is running (pid ${pid}).`); } catch { return console.log('Pulse Runner is stopped.'); } }
+  if (action === 'start') { try { const { pid } = JSON.parse(await readFile(pidFile, 'utf8')); process.kill(pid, 0); return console.log(`Pulse Runner is already running (pid ${pid}).`); } catch {} const child = spawn(process.execPath, [new URL('./index.js', import.meta.url).pathname, 'start'], { detached: true, stdio: 'ignore', windowsHide: true, env: process.env }); child.unref(); await writeFile(pidFile, JSON.stringify({ pid: child.pid }), { mode: 0o600 }); return console.log(`Pulse Runner started (pid ${child.pid}).`); }
+  if (action === 'stop') { try { const { pid } = JSON.parse(await readFile(pidFile, 'utf8')); process.kill(pid, 'SIGTERM'); } catch {} await rm(pidFile, { force: true }); return console.log('Pulse Runner stopped.'); }
+  throw new Error('Supported service commands: install, start, stop, status.');
+}
+
+try {
+  if (!args.length || has('--help')) usage();
+  else if (args[0] === 'init') await init();
+  else if (args[0] === 'pair') { const credential = value('--credential'); const match = credential?.match(/^(runner-[A-Za-z0-9_-]{12})\.[A-Za-z0-9_-]{32,}$/); if (!match) throw new Error('Invalid Runner credential.'); const config = await readConfig(); if (!config) throw new Error('Run pulse-runner init before pairing.'); const paired = { ...config, runnerId: match[1] }; await writeCredential(credential); await writeConfig(paired); await syncRepos(paired); console.log(`Runner ${paired.runnerId} paired.`); }
+  else { const config = await readConfig(); if (!config) throw new Error('Runner is not initialized.'); if (args[0] === 'repo') await repo(config); else if (args[0] === 'diagnose') await diagnose(config); else if (args[0] === 'service') await service(config); else if (args[0] === 'run') await runOnce(config); else if (args[0] === 'start') { let backoff = 5_000; for (;;) { try { const ranJob = await runOnce(config); backoff = ranJob ? 1_000 : 5_000; } catch (error) { console.error(sanitize(error.message)); backoff = Math.min(backoff * 2, 60_000); } await new Promise((resolve) => setTimeout(resolve, backoff)); } } else usage(); }
+} catch (error) { console.error(`pulse-runner: ${sanitize(error.message)}`); process.exitCode = 1; }

package/src/job.js

@@ -0,0 +1,29 @@
+import { verify } from 'node:crypto';
+
+const b64 = (value) => Buffer.from(value, 'base64url');
+export function jobPayload(job) {
+  const contextRepos = [...new Set(job.contextRepos || [job.repoFullName])].sort().join(',');
+  return [job.id, job.workspaceId, job.issueId, job.agentId, job.runnerId, job.repoFullName, contextRepos, job.mode, job.issuedAt, job.expiresAt, job.signatureAlgorithm, job.signingKeyId].join('.');
+}
+
+/** Reject an envelope before it can cause filesystem or process activity. */
+export function validateJob(job, config, agentOrNow = null, suppliedNow = Date.now()) {
+  const agent = typeof agentOrNow === 'object' && agentOrNow !== null ? agentOrNow : null;
+  const now = typeof agentOrNow === 'number' ? agentOrNow : suppliedNow;
+  if (!job || job.signatureAlgorithm !== 'ed25519' || job.signingKeyId !== config.signingKeyId) throw new Error('Job signing key is not trusted.');
+  if (!config.signingPublicKey || !verify(null, Buffer.from(jobPayload(job)), config.signingPublicKey, b64(job.signature))) throw new Error('Job signature is invalid.');
+  if (!job.id?.startsWith('rjob-') || new Date(job.expiresAt).getTime() <= now) throw new Error('Job is expired or malformed.');
+  if (job.workspaceId !== config.workspaceId || job.runnerId !== config.runnerId) throw new Error('Job identity does not match this Runner.');
+  if (job.mode === 'review') {
+    if (!agent || agent.role !== 'qa' || agent.kind !== config.agentKind) throw new Error('QA review identity does not match this Runner provider.');
+  } else if (job.agentId !== config.agentId || (agent && agent.kind !== config.agentKind)) {
+    throw new Error('Job identity does not match this Runner.');
+  }
+  const contextRepos = [...new Set(job.contextRepos || [job.repoFullName])];
+  if (!contextRepos.includes(job.repoFullName) || contextRepos.some((repo) => !config.repos.includes(repo))) throw new Error('Job repository context is not allowed by this Runner.');
+  return true;
+}
+
+export function sanitize(value) {
+  return String(value || '').slice(-500).replace(/\b(?:sk-ant-|sk-proj-|sk-|pulse_sk_|ghp_|github_pat_)[A-Za-z0-9_-]+/gi, '[redacted]').replace(/\bBearer\s+[A-Za-z0-9._-]+/gi, 'Bearer [redacted]');
+}

package/src/process.js

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export function command(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let output = '';
+    child.stdout.on('data', (chunk) => { output += chunk; }); child.stderr.on('data', (chunk) => { output += chunk; });
+    child.on('error', reject); child.on('close', (code) => resolve({ code, output }));
+  });
+}
+
+export function resolveExecutable(name) {
+  const override = process.env[`PULSE_RUNNER_${name.toUpperCase()}_BIN`];
+  if (override) return override;
+  // ChatGPT for macOS bundles Codex instead of placing it on PATH. The
+  // fallback keeps a launchd/background Runner usable without shell startup
+  // files while remaining overridable for custom installations.
+  if (name === 'codex' && existsSync('/Applications/ChatGPT.app/Contents/Resources/codex')) return '/Applications/ChatGPT.app/Contents/Resources/codex';
+  return name;
+}
+
+export async function executable(name) { try { return (await command(resolveExecutable(name), ['--version'])).code === 0; } catch { return false; } }
+
+export function agentPermissionArgs(kind, mode) {
+  if (mode === 'review') {
+    if (kind === 'codex') return ['--sandbox', 'read-only', '--ask-for-approval', 'never'];
+    if (kind === 'claude') return ['--permission-mode', 'plan'];
+  }
+  if (kind === 'codex') return ['--approve-for-me'];
+  if (kind === 'claude') return ['--permission-mode', 'bypassPermissions', '--dangerously-skip-permissions'];
+  return [];
+}
+
+async function mcpConfig(dir, credential, endpoint) {
+  const path = join(dir, 'pulse-mcp.json');
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await writeFile(path, JSON.stringify({ mcpServers: { pulse: { type: 'http', url: endpoint.replace(/\/pulseRunner(?:\w+)?$/, '/pulseMcp'), headers: { Authorization: `Bearer ${credential}` } } } }), { mode: 0o600 });
+  return path;
+}
+
+export async function runAgent(kind, job, worktree, additionalWorktrees, config, credential, tempDir) {
+  const context = additionalWorktrees.length
+    ? job.mode === 'review'
+      ? ` Additional review worktrees for inspection: ${additionalWorktrees.map(({ repo, worktree: path }) => `${repo} (${path})`).join('; ')}.`
+      : ` Additional writable project worktrees: ${additionalWorktrees.map(({ repo, worktree: path }) => `${repo} (${path})`).join('; ')}. They are authorized for this same job: do not request a repository handoff. For every repository you change, create a pul/* branch in that worktree and commit the changes; the Runner will publish a PR for each changed branch.`
+    : '';
+  const prompt = job.mode === 'review'
+    ? `You are Pulse Runner performing a QA review for issue ${job.issueId}. First call pulse_next_review with identifier "${job.issueId}"; if found is false, stop without reviewing. Then call pulse_get_review_context with the same identifier. Review every pull request and its diff returned by that tool, along with the issue acceptance criteria and project Definition of Done. Use the provided local worktrees only to inspect files when a diff is too large or more context is needed. Do not modify files, commit, push, or create pull requests. Submit the evidence-based verdict with pulse_submit_review. If you cannot submit a verdict for any reason, call pulse_report_review_incomplete before ending. Do not print, persist, or transmit credentials.${context}`
+    : `You are Pulse Runner executing ${job.mode} for issue ${job.issueId}. Use the Pulse MCP server for issue context and reporting. Work only in the provided project worktrees. Do not print, persist, or transmit credentials.${context}`;
+  const mcp = await mcpConfig(tempDir, credential, config.endpoint);
+  const additionalDirs = additionalWorktrees.flatMap(({ worktree: path }) => ['--add-dir', path]);
+  try {
+    // `--approve-for-me` selects Codex's workspace-write sandbox itself.
+    // Supplying both flags is rejected by current Codex releases.
+    if (kind === 'codex') {
+      return await command(resolveExecutable('codex'), ['exec', '--ephemeral', ...agentPermissionArgs(kind, job.mode), '--cd', worktree, ...additionalDirs, '-c', `mcp_servers.pulse.url="${config.endpoint.replace(/\"/g, '\\\"')}/pulseMcp"`, '-c', `mcp_servers.pulse.http_headers={Authorization="Bearer ${credential}"}`, prompt], { cwd: worktree });
+    }
+    if (kind === 'claude') {
+      return await command(resolveExecutable('claude'), ['--print', '--no-session-persistence', ...agentPermissionArgs(kind, job.mode), ...additionalDirs, '--strict-mcp-config', '--mcp-config', mcp, prompt], { cwd: worktree });
+    }
+    throw new Error(`Unsupported agent kind '${kind}'.`);
+  } finally { await rm(mcp, { force: true }); }
+}

package/test/job.test.js

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { generateKeyPairSync, sign } from 'node:crypto';
+import { jobPayload, sanitize, validateJob } from '../src/job.js';
+
+test('accepts a signed, bound job and rejects changed identity', () => {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const job = { id: 'rjob-123', workspaceId: 'ws-1', issueId: 'issue-1', agentId: 'agent-1', runnerId: 'runner-123456789012', repoFullName: 'owner/repo', contextRepos: ['owner/repo', 'owner/app'], mode: 'task', issuedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 60_000).toISOString(), signatureAlgorithm: 'ed25519', signingKeyId: 'runner-job-v1' };
+  job.signature = sign(null, Buffer.from(jobPayload(job)), privateKey).toString('base64url');
+  const config = { workspaceId: 'ws-1', agentId: 'agent-1', runnerId: 'runner-123456789012', repos: ['owner/repo', 'owner/app'], signingKeyId: 'runner-job-v1', signingPublicKey: publicKey.export({ type: 'spki', format: 'pem' }).toString() };
+  assert.equal(validateJob(job, config), true);
+  assert.throws(() => validateJob({ ...job, repoFullName: 'owner/other' }, config));
+  assert.throws(() => validateJob({ ...job, contextRepos: ['owner/repo'] }, config));
+});
+test('sanitizes provider tokens', () => assert.equal(sanitize('Bearer secret.token sk-ant-secret'), 'Bearer [redacted] [redacted]'));

package/test/process.test.js

@@ -0,0 +1,13 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { agentPermissionArgs } from '../src/process.js';
+
+test('QA Runner sessions use read-only filesystem permissions', () => {
+  assert.deepEqual(agentPermissionArgs('codex', 'review'), ['--sandbox', 'read-only', '--ask-for-approval', 'never']);
+  assert.deepEqual(agentPermissionArgs('claude', 'review'), ['--permission-mode', 'plan']);
+});
+
+test('development jobs retain their configured write permissions', () => {
+  assert.deepEqual(agentPermissionArgs('codex', 'task'), ['--approve-for-me']);
+  assert.deepEqual(agentPermissionArgs('claude', 'task'), ['--permission-mode', 'bypassPermissions', '--dangerously-skip-permissions']);
+});