@pulsehub/runner 0.1.3 → 0.1.4

package/README.md

@@ -16,4 +16,26 @@ The Runner only uses local Git and provider sessions, creates disposable worktre
 
 ## 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.
+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 each QA instance with `--agent-role qa`, 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.
+
+## Preparation and preflight (TES-304)
+
+In Pulse Settings, select a Runner on the agent, then choose **Verificar preparación**. The expected local identity is shown there. On the Runner machine, under the same OS user as the service, register it explicitly:
+
+```sh
+pulse-runner identity add --agent AGENT_ID --agent-kind codex --agent-role dev
+# For a QA agent (Claude is also supported):
+pulse-runner identity add --agent QA_AGENT_ID --agent-kind claude --agent-role qa
+pulse-runner identity list
+pulse-runner diagnose
+```
+
+`identity remove --agent ID` removes an identity. Each job must match an explicitly configured agent, provider and role, including QA jobs. Use separate `PULSE_RUNNER_HOME` directories for independent local instances. The service reloads identity configuration on each polling cycle.
+
+Sign in locally with `codex login` or `claude auth login`. Diagnostics use the providers' native status commands and Git `ls-remote`; Pulse receives only agent/provider/role identifiers and CLI/session/repository availability booleans. Account information, command output and provider credentials are discarded locally. A status check confirms locally available authentication, not that a later provider request cannot fail. The daemon refreshes readiness at least once per minute and runs a fresh local check before executing a delivered job. Probes time out without opening interactive login prompts.
+
+Backend dispatch requires a recent heartbeat and readiness report, a matching identity/provider/role, repository authorization and access, and capacity. It checks these centrally for tasks, rework, handoff, retry and QA; delivery checks again before issuing a job MCP credential. Failed jobs carry a phase/category and the job ID used in `logs/runner.jsonl`.
+
+Rollout: upgrade the Runner and configure all Dev/QA identities before enabling the new backend preflight. Older Runners without readiness reports will be blocked with an actionable message. The frontend and backend changes are required together for the preparation panel. Manual UI and live provider verification remain part of TES-308.
+
+Authentication command references: [Codex CLI](https://developers.openai.com/codex/cli/reference), [Claude CLI](https://code.claude.com/docs/en/cli-reference).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsehub/runner",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local, credential-safe Pulse Runner",
   "repository": {
     "type": "git",

package/src/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { inspectReadiness, assertLocalReadiness, localIdentities } from './readiness.js';
 import { generateKeyPairSync } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { appendFile, chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
@@ -6,13 +7,13 @@ 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';
+import { command, 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`);
+const usage = () => console.log(`pulse-runner <init|pair|start|run|diagnose|identity|repo|service>\n\ninit --workspace WS --agent AGENT [--agent-kind codex|claude] [--agent-role dev|qa] --signing-public-key FILE --allow-autonomous [--endpoint URL] [--repo owner/repo]\npair --credential runner.secret\nidentity add|remove --agent ID --agent-kind codex|claude --agent-role dev|qa | identity list\nstart | run --once | diagnose | repo add|remove|list | service install|start|stop|status`);
 
 async function logEvent(event, details = {}) {
   try {
@@ -141,8 +142,15 @@ async function publish(checkouts, jobId) {
   }
   return publications;
 }
+let readinessCache;
+async function readinessFor(config, force = false) {
+  const key = JSON.stringify([config.workspaceId, localIdentities(config), config.repos]);
+  if (force || !readinessCache || readinessCache.key !== key || Date.now() - readinessCache.at > 60_000) readinessCache = { key, at: Date.now(), value: await inspectReadiness(config) };
+  return readinessCache.value;
+}
 async function runOnce(config) {
-  await request(config, 'pulseRunnerHeartbeat', { status: 'online' });
+  const readiness = await readinessFor(config);
+  await request(config, 'pulseRunnerHeartbeat', { status: 'online', readiness });
   const delivery = await request(config, 'pulseRunnerPoll', {}); if (!delivery.job) return false;
   const job = delivery.job;
   await logEvent('job.received', { jobId: job.id, issueId: job.issueId, agentId: job.agentId, mode: job.mode, repo: job.repoFullName });
@@ -150,6 +158,8 @@ async function runOnce(config) {
   try {
     const agent = delivery.agent || { kind: config.agentKind, role: job.agentId === config.agentId ? 'dev' : null };
     validateJob(job, config, agent);
+    jobPhase = 'local-preflight';
+    assertLocalReadiness(job, config, agent, await readinessFor(config, true));
     await logEvent('job.validated', { jobId: job.id, repoCount: (job.contextRepos || [job.repoFullName]).length });
     jobPhase = 'prepare-worktrees';
     await request(config, 'pulseRunnerHeartbeat', { status: 'busy' });
@@ -167,15 +177,16 @@ async function runOnce(config) {
       const publication = shouldPublish ? await publish(checkouts, job.id) : { succeeded: [], failed: [] };
       const outcome = result.code === 0 && publication.failed.length === 0 ? 'completed' : 'failed';
       const summary = completionSummary(result, publication);
+      const failure = outcome === 'failed' ? { phase: result.code !== 0 ? 'run-agent' : publication.failed[0]?.phase || 'publication', category: 'execution', correlationId: job.id } : null;
       jobPhase = 'report-completion';
-      await request(config, 'pulseRunnerComplete', { jobId: job.id, outcome, result: sanitize(summary) });
+      await request(config, 'pulseRunnerComplete', { jobId: job.id, outcome, result: sanitize(summary), failure });
       await logEvent('job.completed', { jobId: job.id, outcome, publicationFailures: publication.failed.length });
     } finally { await removeTemporary(temp); await cleanup(checkouts); await removeTemporary(join(paths().worktrees, job.id)); }
   } catch (error) {
     const phase = error.phase || jobPhase;
     const message = error?.message || String(error);
     await logEvent('job.failed', { jobId: job.id, issueId: job.issueId, repo: job.repoFullName, phase, error: message });
-    await request(config, 'pulseRunnerComplete', { jobId: job.id, outcome: 'failed', result: sanitize(`${phase}: ${message}`) }).catch((completionError) => {
+    await request(config, 'pulseRunnerComplete', { jobId: job.id, outcome: 'failed', result: sanitize(`${phase}: ${message}`), failure: { phase, category: phase === 'validate-job' ? 'configuration' : ['local-preflight', 'prepare-worktrees'].includes(phase) ? 'local_preparation' : 'execution', correlationId: job.id } }).catch((completionError) => {
       logEvent('job.completion-report-failed', { jobId: job.id, error: completionError?.message || String(completionError) });
     });
     throw error;
@@ -187,14 +198,34 @@ async function runOnce(config) {
 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.');
+  if (!['codex', 'claude'].includes(value('--agent-kind') || 'codex') || !['dev', 'qa'].includes(value('--agent-role') || 'dev')) throw new Error('init requires a valid --agent-kind codex|claude and --agent-role dev|qa.');
   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 });
+  await writeConfig({ version: 1, endpoint: value('--endpoint') || DEFAULT_ENDPOINT, workspaceId: value('--workspace'), agentId: value('--agent'), agentKind: value('--agent-kind') || 'codex', agentRole: value('--agent-role') || 'dev', 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 diagnose(config) {
+  const readiness = await readinessFor(config, true);
+  console.log(JSON.stringify(readiness, null, 2));
+  if (await readCredential()) await request(config, 'pulseRunnerHeartbeat', { status: 'online', readiness });
+  const providers = localIdentities(config).map((identity) => readiness.providers[identity.kind]);
+  if (providers.some((provider) => !provider?.cli || !provider?.session) || readiness.repositories.some((repo) => !repo.accessible)) process.exitCode = 1;
+}
+async function identity(config) {
+  if (args[1] === 'list') return console.log(JSON.stringify(localIdentities(config), null, 2));
+  const agentId = value('--agent');
+  const kind = value('--agent-kind');
+  const role = value('--agent-role');
+  if (!agentId || !/^[-A-Za-z0-9_]{1,100}$/.test(agentId) || !['add', 'remove'].includes(args[1])) throw new Error('Use identity add|remove --agent ID [--agent-kind codex|claude --agent-role dev|qa].');
+  if (args[1] === 'add' && (!['codex', 'claude'].includes(kind) || !['dev', 'qa'].includes(role))) throw new Error('identity add requires a valid provider and role.');
+  const identities = localIdentities(config).filter((entry) => entry.agentId !== agentId);
+  if (args[1] === 'add') identities.push({ agentId, kind, role });
+  const updated = { ...config, identities };
+  await writeConfig(updated);
+  await diagnose(updated);
+}
 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}.`); }
@@ -208,5 +239,5 @@ 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) { await logEvent('service.loop-failed', { error: error.message }); console.error(sanitize(error.message)); backoff = Math.min(backoff * 2, 60_000); } await new Promise((resolve) => setTimeout(resolve, backoff)); } } else usage(); }
+  else { const config = await readConfig(); if (!config) throw new Error('Runner is not initialized.'); if (args[0] === 'identity') await identity(config); else 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((await readConfig()) || config); backoff = ranJob ? 1_000 : 5_000; } catch (error) { await logEvent('service.loop-failed', { error: error.message }); 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

@@ -14,11 +14,9 @@ export function validateJob(job, config, agentOrNow = null, suppliedNow = Date.n
   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 identity = (config.identities || [{ agentId: config.agentId, kind: config.agentKind, role: config.agentRole || 'dev' }]).find((entry) => entry.agentId === job.agentId);
+  const role = job.mode === 'review' ? 'qa' : 'dev';
+  if (!identity || identity.role !== role || (agent && (agent.kind !== identity.kind || agent.role !== role))) throw new Error('Job identity does not match this Runner provider/role.');
   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;

package/src/process.js

@@ -6,9 +6,11 @@ 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 });
+    const timer = options.timeout ? setTimeout(() => child.kill('SIGKILL'), options.timeout) : null;
     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 }));
+    const append = (chunk) => { output = (output + chunk).slice(-(options.maxOutput || 1_000_000)); };
+    child.stdout.on('data', append); child.stderr.on('data', append);
+    child.on('error', (error) => { if (timer) clearTimeout(timer); reject(error); }); child.on('close', (code) => { if (timer) clearTimeout(timer); resolve({ code, output }); });
   });
 }
 
@@ -34,10 +36,14 @@ export function agentPermissionArgs(kind, mode) {
   return [];
 }
 
+export function mcpEndpoint(endpoint) {
+  return endpoint.replace(/\/(?:pulseRunner\w*|pulseMcp)\/?$/, '').replace(/\/$/, '') + '/pulseMcp';
+}
+
 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 });
+  await writeFile(path, JSON.stringify({ mcpServers: { pulse: { type: 'http', url: mcpEndpoint(endpoint), headers: { Authorization: `Bearer ${credential}` } } } }), { mode: 0o600 });
   return path;
 }
 
@@ -56,7 +62,7 @@ export async function runAgent(kind, job, worktree, additionalWorktrees, config,
     // `--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 });
+      return await command(resolveExecutable('codex'), ['exec', '--ephemeral', ...agentPermissionArgs(kind, job.mode), '--cd', worktree, ...additionalDirs, '-c', `mcp_servers.pulse.url="${mcpEndpoint(config.endpoint).replace(/\"/g, '\\\"')}"`, '-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 });

package/src/readiness.js

@@ -0,0 +1,35 @@
+import { command, resolveExecutable } from './process.js';
+
+export function localIdentities(config) {
+  return config.identities || [{ agentId: config.agentId, kind: config.agentKind, role: config.agentRole || 'dev' }];
+}
+
+export async function inspectReadiness(config, run = command) {
+  const providers = {};
+  for (const kind of ['codex', 'claude']) {
+    const cli = await run(resolveExecutable(kind), ['--version'], { timeout: 10_000, maxOutput: 4096 }).then((result) => result.code === 0).catch(() => false);
+    const session = cli && await run(resolveExecutable(kind), kind === 'codex' ? ['login', 'status'] : ['auth', 'status'], { timeout: 10_000, maxOutput: 4096 }).then((result) => {
+      if (result.code !== 0) return false;
+      // Claude can exit successfully while reporting loggedIn:false. Never
+      // return its raw JSON (which may include account identifiers).
+      if (kind === 'claude') { try { return JSON.parse(result.output).loggedIn === true; } catch { return false; } }
+      return true;
+    }).catch(() => false);
+    providers[kind] = { cli, session: !!session };
+  }
+  const repositories = [];
+  for (const repo of config.repos) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new Error('Invalid repository.');
+    const accessible = await run('git', ['ls-remote', '--exit-code', `https://github.com/${repo}.git`, 'HEAD'], { env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, timeout: 10_000, maxOutput: 4096 }).then((result) => result.code === 0).catch(() => false);
+    repositories.push({ repo, accessible });
+  }
+  return { workspaceId: config.workspaceId, identities: localIdentities(config), providers, repositories };
+}
+
+export function assertLocalReadiness(job, config, agent, readiness) {
+  const identity = localIdentities(config).find((entry) => entry.agentId === job.agentId);
+  const role = job.mode === 'review' ? 'qa' : 'dev';
+  if (!identity || identity.kind !== agent.kind || identity.role !== role || agent.role !== role) throw new Error('Local agent identity/provider/role mismatch. Run pulse-runner identity add with this agent configuration.');
+  if (!readiness.providers[agent.kind]?.cli || !readiness.providers[agent.kind]?.session) throw new Error(`Local ${agent.kind} CLI/session is unavailable. Sign in locally and run pulse-runner diagnose.`);
+  if ((job.contextRepos || [job.repoFullName]).some((repo) => !readiness.repositories.some((entry) => entry.repo === repo && entry.accessible))) throw new Error('Local repository access is unavailable. Check Git authentication and run pulse-runner diagnose.');
+}

package/test/job.test.js

@@ -13,3 +13,14 @@ test('accepts a signed, bound job and rejects changed identity', () => {
   assert.throws(() => validateJob({ ...job, contextRepos: ['owner/repo'] }, config));
 });
 test('sanitizes provider tokens', () => assert.equal(sanitize('Bearer secret.token sk-ant-secret'), 'Bearer [redacted] [redacted]'));
+
+test('signed QA jobs require explicit agent identity and provider/role compatibility', () => {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const job = { id: 'rjob-qa', workspaceId: 'ws-1', issueId: 'issue-1', agentId: 'qa-1', runnerId: 'runner-1', repoFullName: 'owner/repo', mode: 'review', issuedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 60000).toISOString(), signatureAlgorithm: 'ed25519', signingKeyId: 'key' };
+  job.signature = sign(null, Buffer.from(jobPayload(job)), privateKey).toString('base64url');
+  const config = { workspaceId: 'ws-1', runnerId: 'runner-1', agentId: 'dev-1', agentKind: 'codex', repos: ['owner/repo'], signingKeyId: 'key', signingPublicKey: publicKey.export({ type: 'spki', format: 'pem' }).toString() };
+  assert.throws(() => validateJob(job, config, { kind: 'codex', role: 'qa' }), /identity/);
+  config.identities = [{ agentId: 'qa-1', kind: 'codex', role: 'qa' }];
+  assert.equal(validateJob(job, config, { kind: 'codex', role: 'qa' }), true);
+  assert.throws(() => validateJob(job, config, { kind: 'claude', role: 'qa' }), /provider/);
+});

package/test/process.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { agentPermissionArgs } from '../src/process.js';
+import { agentPermissionArgs, mcpEndpoint } 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']);
@@ -11,3 +11,9 @@ 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']);
 });
+
+test('both providers use the same MCP URL for cloud and local emulator endpoints', () => {
+  assert.equal(mcpEndpoint('https://example.cloudfunctions.net'), 'https://example.cloudfunctions.net/pulseMcp');
+  assert.equal(mcpEndpoint('http://127.0.0.1:5001/demo-pulse-local/us-east4'), 'http://127.0.0.1:5001/demo-pulse-local/us-east4/pulseMcp');
+  assert.equal(mcpEndpoint('http://localhost:5001/demo-pulse-local/us-east4/pulseRunnerPoll'), 'http://localhost:5001/demo-pulse-local/us-east4/pulseMcp');
+});

package/test/readiness.test.js

@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { inspectReadiness, assertLocalReadiness } from '../src/readiness.js';
+const config = { workspaceId: 'ws-1', agentId: 'agent-1', agentKind: 'codex', repos: ['owner/repo'] };
+const job = { agentId: 'agent-1', repoFullName: 'owner/repo', mode: 'task' };
+const agent = { kind: 'codex', role: 'dev' };
+test('readiness uses native status commands and reports only booleans', async () => {
+  const calls = [];
+  const report = await inspectReadiness(config, async (cmd, args) => {
+    calls.push(args);
+    return { code: 0, output: args[0] === 'auth' ? JSON.stringify({ loggedIn: true, email: 'private', token: 'private' }) : 'private' };
+  });
+  assert.ok(calls.some((args) => args.join(' ') === 'login status'));
+  assert.ok(calls.some((args) => args.join(' ') === 'auth status'));
+  assert.equal(JSON.stringify(report).includes('private'), false);
+  assert.doesNotThrow(() => assertLocalReadiness(job, config, agent, report));
+  assert.throws(() => assertLocalReadiness({ ...job, agentId: 'other' }, config, agent, report), /identity/);
+});
+test('CLI missing, session false and Git denial remain unavailable', async () => {
+  const report = await inspectReadiness(config, async (cmd, args) => {
+    if (cmd.includes('codex')) throw new Error('missing');
+    return { code: args[0] === 'ls-remote' ? 1 : 0, output: '{"loggedIn":false}' };
+  });
+  assert.equal(report.providers.codex.cli, false);
+  assert.equal(report.providers.claude.session, false);
+  assert.equal(report.repositories[0].accessible, false);
+  assert.throws(() => assertLocalReadiness(job, config, agent, report), /CLI/);
+});
+test('QA identity is explicitly allowed and cannot execute development jobs', async () => {
+  const qaConfig = { ...config, identities: [{ agentId: 'qa-1', kind: 'claude', role: 'qa' }] };
+  const report = await inspectReadiness(qaConfig, async () => ({ code: 0, output: '{"loggedIn":true}' }));
+  assert.doesNotThrow(() => assertLocalReadiness({ ...job, agentId: 'qa-1', mode: 'review' }, qaConfig, { kind: 'claude', role: 'qa' }, report));
+  assert.throws(() => assertLocalReadiness({ ...job, agentId: 'qa-1' }, qaConfig, { kind: 'claude', role: 'qa' }, report), /role/);
+});