@pulsehub/runner 0.1.4 → 0.1.5

package/README.md

@@ -2,7 +2,7 @@
 
 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`.
+Before updating, stop the existing process with its installed `pulse-runner service stop` command (or Ctrl+C in its terminal). Then run `npm update -g @pulsehub/runner` and `pulse-runner service install`. This release replaces the old detached-process service with an OS-managed per-user service; install it once after upgrading. Service installation also starts it.
 
 Every push to `main` (including a merged pull request) runs the release workflow. It tests the Runner, increments the patch version, commits the version and a matching `vX.Y.Z` tag to `main`, then publishes that version to npm. The npm publisher uses GitHub Actions OIDC; no npm token is stored in GitHub. Development-channel releases can be added separately when a `dev` branch is introduced.
 
@@ -39,3 +39,34 @@ Backend dispatch requires a recent heartbeat and readiness report, a matching id
 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).
+
+
+## Installation and background services (TES-286)
+
+Install Node 20+, Git, the GitHub CLI and the provider CLI on macOS, Linux or Windows. Sign in locally with `gh auth login` and the provider's login command. No GitHub token needs to be entered in Pulse. Initialize with the public signing key shipped in this package, register the generated public key and approved repositories in Settings → Agentes → Pulse Runners, then pair the one-time device credential on that machine. A signing **public** key is safe to install locally; never copy the backend's signing private key.
+
+Run `pulse-runner diagnose`, then use `pulse-runner run --once` for one job or `pulse-runner start` for foreground operation. `service install` registers a LaunchAgent on macOS, a systemd user unit on Linux, or an on-logon Scheduled Task on Windows. `service start|stop|status|uninstall` manages that installation. Run these commands as the same OS user who owns the local provider and Git sessions. Linux background execution requires a working user systemd session; macOS requires a logged-in GUI user; the Windows task starts on user logon.
+
+For multiple instances, use a separate `PULSE_RUNNER_HOME` for every Runner, including when running service commands. Service names derive from that directory, and the installed command retains it through `--home`. A shared lock prevents a daemon and `run --once` from using the same data directory concurrently. If a process died, the next invocation recovers its stale lock and cleans interrupted temporary work before polling.
+
+## Cancellation, recovery and repository scope
+
+In Settings → Agentes → Pulse Runners → Actividad reciente, select **Cancelar** for an active job. Only the Runner owner or a workspace admin can cancel it. A queued job becomes canceled immediately. A delivered job shows **Cancelación solicitada**, revokes its ephemeral MCP access immediately, and retains its active capacity until the Runner stops the process and acknowledges cleanup. Refreshing that panel follows the acknowledgment automatically. A disconnected Runner cannot acknowledge until it reconnects; expired jobs are released by the existing sweeper.
+
+While executing, the Runner sends an outbound heartbeat every two seconds with its active job ID. A cancellation, revocation, expired job or failed heartbeat stops the provider process tree. On Unix it sends SIGTERM, escalating after two seconds; Windows uses `taskkill /T /F`. Cancellation skips subsequent publication and removes per-job MCP configuration and worktrees before reporting `canceled`. It also checks cancellation before each push and PR creation. A push or PR that already finished cannot be undone by a later cancellation.
+
+Ctrl+C or SIGTERM also cancels foreground work. A force-killed daemon recovers on its next start: its local journal stores only the job ID, cleans interrupted worktrees/MCP files, prunes Git registrations and reports the interrupted job canceled. Committed branches remain in the local mirror; uncommitted disposable worktree edits are removed. The source checkout remains untouched. On Windows, forcibly ending the daemon may defer cleanup until that restart.
+
+The local `repo` command can retain or reduce the repository list approved during pairing; the device credential cannot widen it. To approve a larger scope, the owner/admin registers a replacement Runner with the new repository list in Pulse, revokes the old Runner and pairs the replacement locally. A rejected local change leaves the local configuration unchanged.
+
+Codex receives the ephemeral MCP Authorization header through a child-process environment variable, never command-line arguments. Claude receives a user-only temporary MCP configuration file, deleted after execution. Provider authentication is always discovered with native status commands; Pulse receives readiness booleans and sanitized lifecycle/results, not provider sessions.
+
+## Signing and rollout
+
+Backend `RUNNER_JOB_SIGNING_PRIVATE_KEY` must already exist before deployment, be Ed25519, and match this release's `keys/runner-job-v1-public.pem` and `runner-job-v1` key ID. `contextRepos` is included in the signed envelope. Unknown keys, malformed/future/expired timestamps, invalid identities or unauthorized repositories are rejected before worktree creation. Older HMAC envelopes without algorithm/key ID are deliberately rejected; never reinterpret them locally. Before changing the signing format or key, drain/cancel queued jobs and update Runners together with the backend; current envelopes expire after 30 minutes.
+
+Upgrade Runners before enabling the cancellation UI/backend. Older Runners do not observe cancellation requests while their CLI runs, even if the backend revokes MCP access. The backend transaction preserves a requested cancellation if a completion races it. This version retains the TES-304 readiness and Dev/QA identity requirements.
+
+## Verification
+
+`npm test` runs native fixture CLIs for both providers against a loopback control plane and real temporary Git repositories. It covers native session detection, signed envelope rejection before checkout, multi-repo isolation, remote/local/revocation/expiry cancellation, process descendants, sanitized reports, temporary-file cleanup, lock exclusion, interrupted-job recovery and QA permissions. The CI matrix runs the suite and CLI smoke on macOS, Linux and Windows. Fixture tests do not prove live model execution or actual service installation in each OS session.

package/package.json

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

package/src/config.js

@@ -1,9 +1,9 @@
 import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir, platform } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 
 export function dataDir() {
-  if (process.env.PULSE_RUNNER_HOME) return process.env.PULSE_RUNNER_HOME;
+  if (process.env.PULSE_RUNNER_HOME) return resolve(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');

package/src/index.js

@@ -1,198 +1,38 @@
 #!/usr/bin/env node
-import { inspectReadiness, assertLocalReadiness, localIdentities } from './readiness.js';
+import { inspectReadiness, 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';
-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, runAgent } from './process.js';
+import { readFile } from 'node:fs/promises';
+import { readConfig, readCredential, writeConfig, writeCredential } from './config.js';
+import { sanitize } from './job.js';
+import { service } from './service.js';
+
+import { runOnce, recoverInterruptedWork, withRunnerLock, request } from './runtime.js';
 
 const DEFAULT_ENDPOINT = 'https://us-east4-pulse-app-93.cloudfunctions.net';
 const args = process.argv.slice(2);
+const homeIndex = args.indexOf('--home');
+if (homeIndex >= 0 && args[homeIndex + 1]) process.env.PULSE_RUNNER_HOME = args[homeIndex + 1];
+let shutdownRequested = false;
+let activeJobController;
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+  shutdownRequested = true;
+  activeJobController?.abort();
+});
 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|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 {
-    const p = await ensureDataDir();
-    const safeDetails = Object.fromEntries(Object.entries(details).map(([key, value]) => [
-      key,
-      typeof value === 'string' ? sanitize(value) : value,
-    ]));
-    const file = join(p.logs, 'runner.jsonl');
-    await appendFile(file, `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...safeDetails })}\n`, { mode: 0o600 });
-    await chmod(file, 0o600);
-  } catch {
-    // Logging must not turn a successfully completed job into a failed one.
-  }
-}
-
-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();
-}
+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|uninstall`);
 
-function repoPath(repo) { return repo.replace('/', '__'); }
-function failureDetail(output) {
-  return sanitize(output).split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3).join(' | ').slice(-240);
-}
-function completionSummary(result, publication) {
-  const entries = [{
-    label: result.code === 0 ? 'Agent completed' : `Agent failed (exit ${result.code})`,
-    detail: result.code === 0 ? '' : failureDetail(result.output),
-  }];
-  for (const published of publication.succeeded) entries.push({ label: 'Publication succeeded', detail: published });
-  for (const failed of publication.failed) entries.push({
-    label: `Publication failed for ${failed.repo} during ${failed.phase}`,
-    detail: failureDetail(failed.error),
-  });
-  const detailCount = entries.filter((entry) => entry.detail).length;
-  const prefixSize = entries.reduce((sum, entry) => sum + entry.label.length + (entry.detail ? 2 : 0), 0) + entries.length - 1;
-  const detailBudget = detailCount ? Math.max(0, Math.floor((480 - prefixSize) / detailCount)) : 0;
-  return entries.map(({ label, detail }) => detail && detailBudget ? `${label}: ${detail.slice(-detailBudget)}` : label).join('\n').slice(-500);
-}
-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);
+async function start(config) {
+  return withRunnerLock(async () => {
+    await recoverInterruptedWork(config);
+    let backoff = 5_000;
+    while (!shutdownRequested) {
+      try { activeJobController = new AbortController(); const ranJob = await runOnce((await readConfig()) || config, { signal: activeJobController.signal }); backoff = ranJob ? 1_000 : 5_000; }
+      catch (error) { console.error(sanitize(error.message)); backoff = Math.min(backoff * 2, 60_000); }
+      finally { activeJobController = undefined; }
+      if (!shutdownRequested) await new Promise((resolve) => setTimeout(resolve, backoff));
     }
-    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, jobId) {
-  const branchResult = await command('git', ['-C', checkout.worktree, 'branch', '--show-current']);
-  const branch = branchResult.output.trim();
-  if (!branch || !branch.startsWith('pul/')) {
-    await logEvent('publication.skipped', { jobId, repo: checkout.repo, reason: 'branch-not-pulse' });
-    return '';
-  }
-  let phase = 'validate-commit';
-  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 Object.assign(new Error(`Uncommitted changes remain in ${checkout.repo}; the agent must commit every changed worktree.`), { phase });
-  phase = 'inspect-commit';
-  const head = await command('git', ['-C', checkout.worktree, 'rev-parse', 'HEAD']);
-  if (head.code) throw Object.assign(new Error(sanitize(head.output)), { phase });
-  if (head.output.trim() === checkout.baseCommit) {
-    await logEvent('publication.skipped', { jobId, repo: checkout.repo, branch, reason: 'no-commits' });
-    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.
-  phase = 'push';
-  await logEvent('publication.started', { jobId, repo: checkout.repo, branch, phase });
-  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 Object.assign(new Error(sanitize(pushed.output)), { phase });
-  await logEvent('publication.pushed', { jobId, repo: checkout.repo, branch, phase });
-  phase = 'find-pull-request';
-  const existing = await command('gh', ['pr', 'view', branch, '--repo', checkout.repo, '--json', 'url']);
-  if (existing.code === 0) {
-    await logEvent('publication.pull-request-exists', { jobId, repo: checkout.repo, branch });
-    return `Published ${checkout.repo}:${branch}; existing PR detected.`;
-  }
-  if (!/no pull requests found/i.test(existing.output)) throw Object.assign(new Error(sanitize(existing.output)), { phase });
-  phase = 'create-pull-request';
-  const created = await command('gh', ['pr', 'create', '--repo', checkout.repo, '--base', 'main', '--head', branch, '--fill']);
-  if (created.code) throw Object.assign(new Error(sanitize(created.output)), { phase });
-  await logEvent('publication.pull-request-created', { jobId, repo: checkout.repo, branch, url: created.output.trim() });
-  return `Published ${checkout.repo}:${branch}; ${created.output.trim()}`;
-}
-async function publish(checkouts, jobId) {
-  const publications = { succeeded: [], failed: [] };
-  for (const checkout of checkouts) {
-    try {
-      const published = await publishCheckout(checkout, jobId);
-      if (published) publications.succeeded.push(published);
-    } catch (error) {
-      const failure = { repo: checkout.repo, phase: error.phase || 'prepare', error: sanitize(error.message) };
-      publications.failed.push(failure);
-      await logEvent('publication.failed', { jobId, ...failure });
-    }
-  }
-  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) {
-  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 });
-  let jobPhase = 'validate-job';
-  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' });
-    const { primary, checkouts } = await checkout(job); const temp = join(paths().root, 'tmp', job.id);
-    try {
-      jobPhase = 'run-agent';
-      await logEvent('agent.started', { jobId: job.id, repo: primary.repo, mode: job.mode });
-      const result = await runAgent(agent.kind, job, primary.worktree, checkouts.filter((checkout) => checkout !== primary), config, delivery.mcpCredential, temp);
-      const shouldPublish = result.code === 0 && job.mode !== 'review';
-      await logEvent(result.code === 0 ? 'agent.completed' : 'agent.failed', {
-        jobId: job.id,
-        exitCode: result.code,
-        ...(result.code === 0 ? {} : { error: failureDetail(result.output) }),
-      });
-      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), 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}`), 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;
-  }
-  finally { await request(config, 'pulseRunnerHeartbeat', { status: 'online' }).catch(() => {}); }
-  return true;
+  });
 }
 
 async function init() {
@@ -205,9 +45,9 @@ async function init() {
   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 repo(config) { const op = args[1]; const name = args[2]; if (op === 'list') return console.log(config.repos.join('\n')); if (!['add', 'remove'].includes(op) || !name || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.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 syncRepos(updated); await writeConfig(updated); }
 async function diagnose(config) {
-  const readiness = await readinessFor(config, true);
+  const readiness = await inspectReadiness(config);
   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]);
@@ -226,18 +66,10 @@ async function identity(config) {
   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}.`); }
-  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] === '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(); }
+  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(args[1]); else if (args[0] === 'run') { activeJobController = new AbortController(); try { await withRunnerLock(async () => { await recoverInterruptedWork(config); await runOnce(config, { signal: activeJobController.signal }); }); } finally { activeJobController = undefined; } } else if (args[0] === 'start') await start(config); else usage(); }
 } catch (error) { console.error(`pulse-runner: ${sanitize(error.message)}`); process.exitCode = 1; }

package/src/job.js

@@ -10,9 +10,11 @@ export function jobPayload(job) {
 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 (!job || typeof job.signature !== 'string' || 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.');
+  const issuedAt = Date.parse(job.issuedAt);
+  const expiresAt = Date.parse(job.expiresAt);
+  if (!/^rjob-[A-Za-z0-9_-]+$/.test(job.id || '') || !Number.isFinite(issuedAt) || !Number.isFinite(expiresAt) || issuedAt > now || expiresAt <= now || expiresAt <= issuedAt || !['task', 'rework', 'review', 'handoff'].includes(job.mode)) 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.');
   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';

package/src/process.js

@@ -3,14 +3,43 @@ import { existsSync } from 'node:fs';
 import { mkdir, writeFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 
-export function command(command, args, options = {}) {
+export function command(executable, 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;
+    if (options.signal?.aborted) { resolve({ code: null, output: '' }); return; }
+    // Node CLI entrypoints can be used directly on every supported OS.
+    const isScript = /\.(?:cjs|mjs|js)$/.test(executable);
+    const child = spawn(isScript ? process.execPath : executable, isScript ? [executable, ...args] : args, {
+      cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true, detached: process.platform !== 'win32',
+    });
+    let escalation;
+    const killTree = (signal) => {
+      try {
+        if (process.platform === 'win32') {
+          const killer = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+          killer.on('error', () => { try { child.kill(signal); } catch {} });
+        } else process.kill(-child.pid, signal);
+      } catch {}
+    };
+    const abort = () => {
+      killTree('SIGTERM');
+      escalation = setTimeout(() => killTree('SIGKILL'), 2000);
+      escalation.unref();
+    };
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = options.timeout ? setTimeout(abort, options.timeout) : null;
     let 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 }); });
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      // Kill any descendants before releasing the process group on cancellation.
+      if (options.signal?.aborted || escalation) killTree('SIGKILL');
+      if (escalation) clearTimeout(escalation);
+      options.signal?.removeEventListener('abort', abort);
+    };
+    child.on('error', (error) => { cleanup(); reject(error); });
+    child.on('close', (code) => { cleanup(); resolve({ code, output }); });
   });
 }
 
@@ -47,7 +76,19 @@ async function mcpConfig(dir, credential, endpoint) {
   return path;
 }
 
-export async function runAgent(kind, job, worktree, additionalWorktrees, config, credential, tempDir) {
+export function providerInvocation(kind, worktree, additionalDirs, config, mcp, prompt, mode = 'task') {
+  if (kind === 'codex') return {
+    executable: resolveExecutable('codex'),
+    args: ['exec', '--ephemeral', ...agentPermissionArgs(kind, mode), '--cd', worktree, ...additionalDirs, '-c', `mcp_servers.pulse.url=${JSON.stringify(mcpEndpoint(config.endpoint))}`, '-c', 'mcp_servers.pulse.env_http_headers={Authorization="PULSE_RUNNER_MCP_CREDENTIAL"}', prompt],
+  };
+  if (kind === 'claude') return {
+    executable: resolveExecutable('claude'),
+    args: ['--print', '--no-session-persistence', ...agentPermissionArgs(kind, mode), ...additionalDirs, '--strict-mcp-config', '--mcp-config', mcp, prompt],
+  };
+  throw new Error(`Unsupported agent kind '${kind}'.`);
+}
+
+export async function runAgent(kind, job, worktree, additionalWorktrees, config, credential, tempDir, options = {}) {
   const context = additionalWorktrees.length
     ? job.mode === 'review'
       ? ` Additional review worktrees for inspection: ${additionalWorktrees.map(({ repo, worktree: path }) => `${repo} (${path})`).join('; ')}.`
@@ -59,14 +100,8 @@ export async function runAgent(kind, job, worktree, additionalWorktrees, config,
   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="${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 });
-    }
-    throw new Error(`Unsupported agent kind '${kind}'.`);
+    const invocation = providerInvocation(kind, worktree, additionalDirs, config, mcp, prompt, job.mode);
+    const env = kind === 'codex' ? { ...process.env, PULSE_RUNNER_MCP_CREDENTIAL: `Bearer ${credential}` } : process.env;
+    return await command(invocation.executable, invocation.args, { cwd: worktree, env, signal: options.signal });
   } finally { await rm(mcp, { force: true }); }
 }

package/src/runtime.js

@@ -0,0 +1,292 @@
+import { appendFile, chmod, mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureDataDir, paths, readCredential, removeTemporary } from './config.js';
+import { validateJob, sanitize } from './job.js';
+import { command, resolveExecutable, runAgent } from './process.js';
+import { addIsolatedWorktree, removeIsolatedWorktree } from './worktree.js';
+import { inspectReadiness, assertLocalReadiness, localIdentities } from './readiness.js';
+
+export async function logEvent(event, details = {}) {
+  try {
+    const p = await ensureDataDir();
+    const safeDetails = Object.fromEntries(Object.entries(details).map(([key, value]) => [
+      key,
+      typeof value === 'string' ? sanitize(value) : value,
+    ]));
+    const file = join(p.logs, 'runner.jsonl');
+    await appendFile(file, `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...safeDetails })}\n`, { mode: 0o600 });
+    await chmod(file, 0o600);
+  } catch {
+    // Logging must not turn a successfully completed job into a failed one.
+  }
+}
+
+export 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), signal: AbortSignal.timeout(10_000) });
+  if (!response.ok) throw Object.assign(new Error(`Pulse endpoint rejected request (${response.status}).`), { status: response.status });
+  return response.json();
+}
+
+function repoPath(repo) { return repo.replace('/', '__'); }
+function failureDetail(output) {
+  return sanitize(output).split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3).join(' | ').slice(-240);
+}
+function completionSummary(result, publication) {
+  const entries = [{
+    label: result.code === 0 ? 'Agent completed' : `Agent failed (exit ${result.code})`,
+    detail: result.code === 0 ? '' : failureDetail(result.output),
+  }];
+  for (const published of publication.succeeded) entries.push({ label: 'Publication succeeded', detail: published });
+  for (const failed of publication.failed) entries.push({
+    label: `Publication failed for ${failed.repo} during ${failed.phase}`,
+    detail: failureDetail(failed.error),
+  });
+  const detailCount = entries.filter((entry) => entry.detail).length;
+  const prefixSize = entries.reduce((sum, entry) => sum + entry.label.length + (entry.detail ? 2 : 0), 0) + entries.length - 1;
+  const detailBudget = detailCount ? Math.max(0, Math.floor((480 - prefixSize) / detailCount)) : 0;
+  return entries.map(({ label, detail }) => detail && detailBudget ? `${label}: ${detail.slice(-detailBudget)}` : label).join('\n').slice(-500);
+}
+async function checkoutRepo(repo, worktree, signal) {
+  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], { signal, timeout: 120_000 });
+    if (cloned.code !== 0) throw new Error(sanitize(cloned.output));
+  }
+  const fetchResult = await command('git', ['--git-dir', mirror, 'fetch', '--prune', 'origin'], { signal, timeout: 120_000 }); if (fetchResult.code !== 0) throw new Error(sanitize(fetchResult.output));
+  return addIsolatedWorktree(repo, mirror, worktree, { signal });
+}
+async function checkout(job, options = {}) {
+  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)), options.signal);
+      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 removeIsolatedWorktree({ mirror, worktree });
+    await removeTemporary(worktree);
+  }));
+}
+async function publishCheckout(checkout, jobId, checkActive, signal) {
+  const branchResult = await command('git', ['-C', checkout.worktree, 'branch', '--show-current'], { signal });
+  const branch = branchResult.output.trim();
+  if (!branch || !branch.startsWith('pul/')) {
+    await logEvent('publication.skipped', { jobId, repo: checkout.repo, reason: 'branch-not-pulse' });
+    return '';
+  }
+  let phase = 'validate-commit';
+  const status = await command('git', ['-C', checkout.worktree, 'status', '--porcelain'], { signal });
+  const uncommitted = status.output.split('\n').filter((line) => line && !line.endsWith('.pulse-runner-job'));
+  if (uncommitted.length > 0) throw Object.assign(new Error(`Uncommitted changes remain in ${checkout.repo}; the agent must commit every changed worktree.`), { phase });
+  phase = 'inspect-commit';
+  const head = await command('git', ['-C', checkout.worktree, 'rev-parse', 'HEAD'], { signal });
+  if (head.code !== 0) throw Object.assign(new Error(sanitize(head.output)), { phase });
+  if (head.output.trim() === checkout.baseCommit) {
+    await logEvent('publication.skipped', { jobId, repo: checkout.repo, branch, reason: 'no-commits' });
+    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.
+  phase = 'push';
+  await logEvent('publication.started', { jobId, repo: checkout.repo, branch, phase });
+  await checkActive();
+  const pushed = await command('git', ['-c', 'remote.origin.mirror=false', '--git-dir', checkout.mirror, 'push', 'origin', `refs/heads/${branch}:refs/heads/${branch}`], { signal, timeout: 120_000 });
+  if (pushed.code !== 0) throw Object.assign(new Error(sanitize(pushed.output)), { phase });
+  await logEvent('publication.pushed', { jobId, repo: checkout.repo, branch, phase });
+  phase = 'find-pull-request';
+  const existing = await command(resolveExecutable('gh'), ['pr', 'view', branch, '--repo', checkout.repo, '--json', 'url'], { signal, timeout: 30_000 });
+  if (existing.code === 0) {
+    await logEvent('publication.pull-request-exists', { jobId, repo: checkout.repo, branch });
+    return `Published ${checkout.repo}:${branch}; existing PR detected.`;
+  }
+  if (!/no pull requests found/i.test(existing.output)) throw Object.assign(new Error(sanitize(existing.output)), { phase });
+  phase = 'create-pull-request';
+  await checkActive();
+  const created = await command(resolveExecutable('gh'), ['pr', 'create', '--repo', checkout.repo, '--base', 'main', '--head', branch, '--fill'], { signal, timeout: 30_000 });
+  if (created.code !== 0) throw Object.assign(new Error(sanitize(created.output)), { phase });
+  await logEvent('publication.pull-request-created', { jobId, repo: checkout.repo, branch, url: created.output.trim() });
+  return `Published ${checkout.repo}:${branch}; ${created.output.trim()}`;
+}
+async function publish(checkouts, jobId, checkActive, signal) {
+  const publications = { succeeded: [], failed: [] };
+  for (const checkout of checkouts) {
+    try {
+      const published = await publishCheckout(checkout, jobId, checkActive, signal);
+      if (published) publications.succeeded.push(published);
+    } catch (error) {
+      if (error.name === 'AbortError') throw error;
+      const failure = { repo: checkout.repo, phase: error.phase || 'prepare', error: sanitize(error.message) };
+      publications.failed.push(failure);
+      await logEvent('publication.failed', { jobId, ...failure });
+    }
+  }
+  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;
+}
+/** Run one delivered job. Dependencies allow integration tests to use a local control plane. */
+export async function runOnce(config, options = {}) {
+  const remote = options.request || request;
+  const readinessForJob = options.readinessFor || readinessFor;
+  const prepare = options.checkout || checkout;
+  const publishWork = options.publish || publish;
+  const cleanWork = options.cleanup || cleanup;
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  if (options.signal?.aborted) return false;
+  options.signal?.addEventListener('abort', cancel, { once: true });
+  let watcher;
+  let expiryTimer;
+  const stopWatching = new AbortController();
+  let job;
+  let jobPhase = 'poll';
+  let completionReported = false;
+  const journal = join(paths().root, 'active-job.json');
+  const checkActive = async () => {
+    controller.signal.throwIfAborted();
+    if (Date.parse(job.expiresAt) <= Date.now()) controller.abort();
+    const response = await remote(config, 'pulseRunnerHeartbeat', { status: 'busy', jobId: job.id });
+    if (response.cancelRequested) controller.abort();
+    controller.signal.throwIfAborted();
+  };
+  try {
+    const readiness = await readinessForJob(config);
+    await remote(config, 'pulseRunnerHeartbeat', { status: 'online', readiness });
+    const delivery = await remote(config, 'pulseRunnerPoll', {});
+    if (!delivery.job) return false;
+    job = delivery.job;
+    await logEvent('job.received', { jobId: job.id, issueId: job.issueId, agentId: job.agentId, mode: job.mode, repo: job.repoFullName });
+    jobPhase = 'validate-job';
+    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 readinessForJob(config, true));
+    await logEvent('job.validated', { jobId: job.id, repoCount: (job.contextRepos || [job.repoFullName]).length });
+    await checkActive();
+    expiryTimer = setTimeout(cancel, Math.max(0, Date.parse(job.expiresAt) - Date.now()));
+    expiryTimer.unref();
+    // Heartbeat stays outbound while the CLI runs. Losing authorization or
+    // contact with Pulse stops local execution rather than publishing blindly.
+    watcher = (async () => {
+      while (!stopWatching.signal.aborted) {
+        await new Promise((resolve) => {
+          const done = () => { clearTimeout(timer); stopWatching.signal.removeEventListener('abort', done); resolve(); };
+          const timer = setTimeout(done, options.heartbeatIntervalMs || 2000);
+          stopWatching.signal.addEventListener('abort', done, { once: true });
+        });
+        if (stopWatching.signal.aborted) break;
+        try { await checkActive(); } catch { controller.abort(); break; }
+      }
+    })();
+    jobPhase = 'prepare-worktrees';
+    await writeFile(journal, JSON.stringify({ jobId: job.id }), { mode: 0o600 });
+    await chmod(journal, 0o600);
+    const { primary, checkouts } = await prepare(job, { signal: controller.signal });
+    const temp = join(paths().root, 'tmp', job.id);
+    let completion;
+    try {
+      controller.signal.throwIfAborted();
+      jobPhase = 'run-agent';
+      await logEvent('agent.started', { jobId: job.id, repo: primary.repo, mode: job.mode });
+      const result = await runAgent(agent.kind, job, primary.worktree, checkouts.filter((entry) => entry !== primary), config, delivery.mcpCredential, temp, { signal: controller.signal });
+      controller.signal.throwIfAborted();
+      await checkActive();
+      await logEvent(result.code === 0 ? 'agent.completed' : 'agent.failed', { jobId: job.id, exitCode: result.code, ...(result.code === 0 ? {} : { error: failureDetail(result.output) }) });
+      jobPhase = 'publication';
+      const publication = result.code === 0 && job.mode !== 'review' ? await publishWork(checkouts, job.id, checkActive, controller.signal) : { succeeded: [], failed: [] };
+      await checkActive();
+      const outcome = result.code === 0 && publication.failed.length === 0 ? 'completed' : 'failed';
+      const failure = outcome === 'failed' ? { phase: result.code !== 0 ? 'run-agent' : publication.failed[0]?.phase || 'publication', category: 'execution', correlationId: job.id } : null;
+      jobPhase = 'report-completion';
+      completion = { jobId: job.id, outcome, result: sanitize(completionSummary(result, publication)), failure };
+    } finally {
+      await removeTemporary(temp);
+      await cleanWork(checkouts);
+      await removeTemporary(join(paths().worktrees, job.id));
+    }
+    controller.signal.throwIfAborted();
+    await remote(config, 'pulseRunnerComplete', completion);
+    completionReported = true;
+    await logEvent('job.completed', { jobId: job.id, outcome: completion.outcome });
+  } catch (error) {
+    if (!job) throw error;
+    const canceled = controller.signal.aborted;
+    const phase = error.phase || jobPhase;
+    const message = canceled ? 'Job canceled; local execution stopped.' : error?.message || String(error);
+    await logEvent(canceled ? 'job.canceled' : 'job.failed', { jobId: job.id, phase, error: message });
+    await remote(config, 'pulseRunnerComplete', { jobId: job.id, outcome: canceled ? 'canceled' : 'failed', result: sanitize(`${phase}: ${message}`), failure: canceled ? null : { phase, category: phase === 'validate-job' ? 'configuration' : ['local-preflight', 'prepare-worktrees'].includes(phase) ? 'local_preparation' : 'execution', correlationId: job.id } }).then(() => { completionReported = true; }).catch(async (completionError) => {
+      await logEvent('job.completion-report-failed', { jobId: job.id, error: completionError.message });
+    });
+    if (!canceled) throw error;
+  } finally {
+    stopWatching.abort();
+    if (expiryTimer) clearTimeout(expiryTimer);
+    await watcher;
+    if (completionReported) await rm(journal, { force: true });
+    options.signal?.removeEventListener('abort', cancel);
+    if (job) await remote(config, 'pulseRunnerHeartbeat', { status: 'online' }).catch(() => {});
+  }
+  return true;
+}
+
+export async function recoverInterruptedWork(config) {
+  const p = await ensureDataDir();
+  for (const area of [p.worktrees, join(p.root, 'tmp')]) {
+    await mkdir(area, { recursive: true, mode: 0o700 });
+    const jobs = await readdir(area, { withFileTypes: true });
+    await Promise.all(jobs.map((entry) => rm(join(area, entry.name), { recursive: true, force: true })));
+  }
+  const repositories = await readdir(p.repos, { withFileTypes: true });
+  await Promise.all(repositories.filter((entry) => entry.isDirectory()).map((entry) => command('git', ['--git-dir', join(p.repos, entry.name), 'worktree', 'prune']).catch(() => {})));
+  if (config) {
+    const journal = join(p.root, 'active-job.json');
+    const interrupted = await readFile(journal, 'utf8').then(JSON.parse).catch((error) => {
+      if (error.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (interrupted) {
+      await request(config, 'pulseRunnerComplete', { jobId: interrupted.jobId, outcome: 'canceled', result: 'Runner restarted; interrupted worktrees and temporary MCP files cleaned.' }).catch((error) => {
+        if (![404, 409].includes(error.status)) throw error;
+      });
+      await rm(journal, { force: true });
+    }
+  }
+}
+
+/** A per-data-directory lock covers both the daemon and one-shot execution. */
+export async function withRunnerLock(run) {
+  const p = await ensureDataDir();
+  const lockPath = join(p.root, 'runner.lock');
+  let lock;
+  try { lock = await open(lockPath, 'wx', 0o600); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const pid = Number((await readFile(lockPath, 'utf8')).trim());
+    let active = false;
+    if (Number.isInteger(pid) && pid > 0) {
+      try { process.kill(pid, 0); active = true; } catch (probeError) { active = probeError.code !== 'ESRCH'; }
+    } else active = Date.now() - (await stat(lockPath)).mtimeMs < 10_000;
+    if (active) throw new Error('Pulse Runner is already active.');
+    await rm(lockPath, { force: true });
+    lock = await open(lockPath, 'wx', 0o600);
+  }
+  try { await lock.writeFile(`${process.pid}\n`); return await run(); }
+  finally { await lock.close(); await rm(lockPath, { force: true }); }
+}
+
+

package/src/service.js

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { ensureDataDir } from './config.js';
+import { command as nativeCommand } from './process.js';
+import { sanitize } from './job.js';
+
+export async function service(action, options = {}) {
+  const p = await ensureDataDir();
+  const os = options.platform || platform();
+  const userId = options.userId ?? process.getuid?.() ?? 0;
+  const userHome = options.userHome || homedir();
+  const command = options.command || nativeCommand;
+  const print = options.print || console.log;
+  const scriptPath = fileURLToPath(new URL('./index.js', import.meta.url));
+  const instance = createHash('sha256').update(p.root).digest('hex').slice(0, 12);
+  const label = `com.pulse.runner.${instance}`;
+  const unitName = `pulse-runner-${instance}.service`;
+  const taskName = `PulseRunner-${instance}`;
+  const launchAgent = join(userHome, 'Library', 'LaunchAgents', `${label}.plist`);
+  const systemdDir = join((!options.userHome && process.env.XDG_CONFIG_HOME) || join(userHome, '.config'), 'systemd', 'user');
+  const unitPath = join(systemdDir, unitName);
+  const lockPath = join(p.root, 'runner.lock');
+  const xml = (value) => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+  const manager = async (exe, argv) => { const result = await command(exe, argv); if (result.code !== 0) throw new Error(sanitize(result.output)); };
+  const unitValue = (value) => String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '').replaceAll('\r', '');
+  const currentPid = async () => { try { return Number((await readFile(lockPath, 'utf8')).trim()); } catch { return 0; } };
+
+  if (action === 'install') {
+    if (os === 'darwin') {
+      await mkdir(join(userHome, 'Library', 'LaunchAgents'), { recursive: true, mode: 0o700 });
+      const plist = `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(scriptPath)}</string><string>start</string><string>--home</string><string>${xml(p.root)}</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(process.env.PATH || '')}</string></dict><key>StandardOutPath</key><string>${xml(join(p.logs, 'service.log'))}</string><key>StandardErrorPath</key><string>${xml(join(p.logs, 'service.log'))}</string></dict></plist>`;
+      await writeFile(launchAgent, plist, { mode: 0o600 });
+      await command('launchctl', ['bootout', `gui/${userId}/${label}`]).catch(() => {});
+      await manager('launchctl', ['bootstrap', `gui/${userId}`, launchAgent]);
+    } else if (os === 'linux') {
+      await mkdir(systemdDir, { recursive: true, mode: 0o700 });
+      const unit = `[Unit]\nDescription=Pulse local Runner\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart="${unitValue(process.execPath)}" "${unitValue(scriptPath)}" start --home "${unitValue(p.root)}"\nRestart=on-failure\nRestartSec=5\nEnvironment="PATH=${unitValue(process.env.PATH || '/usr/local/bin:/usr/bin:/bin')}"\n\n[Install]\nWantedBy=default.target\n`;
+      await writeFile(unitPath, unit, { mode: 0o600 });
+      await manager('systemctl', ['--user', 'daemon-reload']);
+      await manager('systemctl', ['--user', 'enable', '--now', unitName]);
+    } else if (os === 'win32') {
+      await manager('schtasks', ['/Create', '/SC', 'ONLOGON', '/TN', taskName, '/TR', `"${process.execPath}" "${scriptPath}" start --home "${p.root}"`, '/RL', 'LIMITED', '/F']);
+      await manager('schtasks', ['/Run', '/TN', taskName]);
+    } else throw new Error(`Service installation is not supported on ${os}.`);
+    return print('Pulse Runner is installed as a per-user background service.');
+  }
+
+  if (action === 'uninstall') {
+    if (os === 'darwin') { await command('launchctl', ['bootout', `gui/${userId}/${label}`]).catch(() => {}); await rm(launchAgent, { force: true }); }
+    else if (os === 'linux') { await command('systemctl', ['--user', 'disable', '--now', unitName]).catch(() => {}); await rm(unitPath, { force: true }); await command('systemctl', ['--user', 'daemon-reload']).catch(() => {}); }
+    else if (os === 'win32') { await command('schtasks', ['/End', '/TN', taskName]).catch(() => {}); await command('schtasks', ['/Delete', '/TN', taskName, '/F']).catch(() => {}); }
+    return print('Pulse Runner background service removed.');
+  }
+  if (action === 'start') {
+    if (os === 'darwin') {
+      await command('launchctl', ['bootstrap', `gui/${userId}`, launchAgent]).catch(() => {});
+      await manager('launchctl', ['kickstart', `gui/${userId}/${label}`]);
+    }
+    else if (os === 'linux') await manager('systemctl', ['--user', 'start', unitName]);
+    else if (os === 'win32') await manager('schtasks', ['/Run', '/TN', taskName]);
+    else throw new Error(`Service management is not supported on ${os}.`);
+    return print('Pulse Runner service started.');
+  }
+  if (action === 'stop') {
+    if (os === 'darwin') await command('launchctl', ['bootout', `gui/${userId}/${label}`]).catch(() => {});
+    else if (os === 'linux') await command('systemctl', ['--user', 'stop', unitName]).catch(() => {});
+    else if (os === 'win32') {
+      const processId = await currentPid();
+      if (processId) { try { process.kill(processId, 'SIGTERM'); } catch {} }
+      await command('schtasks', ['/End', '/TN', taskName]).catch(() => {});
+    }
+    return print('Pulse Runner service stopped.');
+  }
+  if (action === 'status') {
+    const processId = await currentPid();
+    if (processId) { try { process.kill(processId, 0); return print(`Pulse Runner is running (pid ${processId}).`); } catch {} }
+    return print('Pulse Runner is stopped.');
+  }
+  throw new Error('Supported service commands: install, start, stop, status, uninstall.');
+}
+

package/src/worktree.js

@@ -0,0 +1,18 @@
+import { command } from './process.js';
+import { sanitize } from './job.js';
+
+export async function addIsolatedWorktree(repo, gitDir, worktree, options = {}) {
+  options.signal?.throwIfAborted();
+  const added = await command('git', ['--git-dir', gitDir, 'worktree', 'add', '--detach', worktree, 'HEAD'], options);
+  if (added.code !== 0) throw new Error(sanitize(added.output));
+  const base = await command('git', ['-C', worktree, 'rev-parse', 'HEAD'], options);
+  if (base.code !== 0) {
+    await command('git', ['--git-dir', gitDir, 'worktree', 'remove', '--force', worktree]).catch(() => {});
+    throw new Error(sanitize(base.output));
+  }
+  return { repo, mirror: gitDir, worktree, baseCommit: base.output.trim() };
+}
+
+export async function removeIsolatedWorktree(checkout) {
+  await command('git', ['--git-dir', checkout.mirror, 'worktree', 'remove', '--force', checkout.worktree]).catch(() => {});
+}

package/test/integration.test.js

@@ -0,0 +1,269 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { generateKeyPairSync, sign } from 'node:crypto';
+import { createServer } from 'node:http';
+import { mkdtemp, mkdir, readFile, writeFile, rm, access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { paths, ensureDataDir, writeCredential } from '../src/config.js';
+import { jobPayload } from '../src/job.js';
+import { command } from '../src/process.js';
+import { inspectReadiness } from '../src/readiness.js';
+import { runOnce, recoverInterruptedWork, withRunnerLock } from '../src/runtime.js';
+
+const exists = (file) => access(file).then(() => true).catch(() => false);
+async function git(args) { const result = await command('git', args); assert.equal(result.code, 0, result.output); return result.output.trim(); }
+
+async function fixture(kind, callback) {
+  const root = await mkdtemp(join(tmpdir(), 'pulse-runtime-'));
+  const saved = { ...process.env };
+  process.env.PULSE_RUNNER_HOME = join(root, 'runner');
+  const source = join(root, 'source');
+  const trace = join(root, 'trace.json');
+  const fake = join(root, 'provider.mjs');
+  await writeFile(fake, `
+import { writeFileSync, readFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+const args = process.argv.slice(2);
+const settings = JSON.parse(readFileSync(${JSON.stringify(join(root, 'settings.json'))}, 'utf8'));
+if (args.includes('--version')) console.log('fixture-cli');
+else if (args[0] === 'login') process.exit(settings.session ? 0 : 1);
+else if (args[0] === 'auth') console.log(JSON.stringify({loggedIn: settings.session}));
+else {
+  const file = args[args.indexOf('--mcp-config') + 1];
+  const received = args.includes('exec') ? !!process.env.PULSE_RUNNER_MCP_CREDENTIAL?.startsWith('Bearer ') : !!JSON.parse(readFileSync(file)).mcpServers.pulse.headers.Authorization;
+  const child = settings.slow ? spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {stdio:'ignore'}) : null;
+  writeFileSync(${JSON.stringify(trace)}, JSON.stringify({args, received, pid: process.pid, childPid: child?.pid}));
+  writeFileSync('job-output.txt', 'isolated output');
+  if (settings.publish) {
+    for (const argv of [['switch','-c','pul/fixture'],['add','job-output.txt'],['-c','user.name=Fixture','-c','user.email=fixture@example.invalid','commit','-m','fixture job']]) {
+      const result=spawnSync('git',argv,{encoding:'utf8'});
+      if(result.status!==0) throw new Error(result.stderr);
+    }
+  }
+  if (settings.slow) setInterval(() => {}, 1000);
+  else { console.log('Bearer fixture-secret pulse_sk_fixture'); process.exitCode = settings.fail ? 1 : 0; }
+}
+`);
+  const fakeGh = join(root,'gh.mjs');
+  await writeFile(fakeGh, `
+import { appendFileSync } from 'node:fs';
+appendFileSync(${JSON.stringify(join(root,'gh-calls.jsonl'))},JSON.stringify(process.argv.slice(2))+'\\n');
+if (process.argv.includes('view')) {console.error('no pull requests found');process.exitCode=1;}
+else console.log('https://github.com/owner/repo/pull/123');
+`);
+  process.env.PULSE_RUNNER_GH_BIN = fakeGh;
+  process.env.PULSE_RUNNER_CODEX_BIN = fake;
+  process.env.PULSE_RUNNER_CLAUDE_BIN = fake;
+  const settings = { session: true, slow: false, fail: false };
+  const updateSettings = () => writeFile(join(root, 'settings.json'), JSON.stringify(settings));
+  await updateSettings();
+  const p = await ensureDataDir();
+  await writeCredential('runner-fixture.synthetic-device');
+  await git(['init', source]);
+  await writeFile(join(source, 'source.txt'), 'original');
+  await git(['-C', source, 'add', 'source.txt']);
+  await git(['-C', source, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-m', 'initial']);
+  await git(['clone', '--mirror', source, join(p.repos, 'owner__repo.git')]);
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const config = { workspaceId: 'ws-test', runnerId: 'runner-fixture', agentId: 'agent-test', agentKind: kind, agentRole: 'dev', repos: ['owner/repo'], signingKeyId: 'fixture', signingPublicKey: publicKey.export({type:'spki',format:'pem'}).toString() };
+  const job = { id: 'rjob-test', workspaceId: config.workspaceId, runnerId: config.runnerId, agentId: config.agentId, issueId: 'issue-fixture', repoFullName: 'owner/repo', mode: 'task', issuedAt: new Date().toISOString(), expiresAt: new Date(Date.now()+60_000).toISOString(), signatureAlgorithm:'ed25519', signingKeyId: config.signingKeyId };
+  const signJob = () => { job.signature = sign(null, Buffer.from(jobPayload(job)), privateKey).toString('base64url'); };
+  signJob();
+  const calls = [];
+  const control = { cancel: false, cancelWhenRunning: false, disconnectWhenRunning: false };
+  const server = createServer(async (req, res) => {
+    let raw = ''; for await (const chunk of req) raw += chunk;
+    const body = JSON.parse(raw); calls.push({path:req.url, body});
+    res.setHeader('Content-Type', 'application/json');
+    if (req.url === '/pulseRunnerPoll') res.end(JSON.stringify({job, agent:{kind,role: job.mode === 'review' ? 'qa' : 'dev'}, mcpCredential:'pulse_sk_fixture'}));
+    else if (body.jobId && req.url === '/pulseRunnerHeartbeat') {
+      const running = await exists(trace);
+      if (control.disconnectWhenRunning && running) {res.statusCode=401;res.end('{}');}
+      else res.end(JSON.stringify({cancelRequested: control.cancel || (control.cancelWhenRunning && running)}));
+    } else res.end('{}');
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  config.endpoint = `http://127.0.0.1:${server.address().port}`;
+  const readinessFor = () => inspectReadiness(config, (exe, args, options) => command(exe, exe === 'git' ? ['ls-remote', '--exit-code', source, 'HEAD'] : args, options));
+  const run = (extra = {}) => runOnce(config, { readinessFor, heartbeatIntervalMs: 20, ...extra });
+  try { await callback({root, source, trace, config, job, signJob, settings, updateSettings, calls, control, run}); }
+  finally {
+    server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
+    for (const key of ['PULSE_RUNNER_HOME', 'PULSE_RUNNER_CODEX_BIN', 'PULSE_RUNNER_CLAUDE_BIN', 'PULSE_RUNNER_GH_BIN']) {
+      if (saved[key] === undefined) delete process.env[key]; else process.env[key] = saved[key];
+    }
+    await rm(root, {recursive:true,force:true});
+  }
+}
+
+for (const kind of ['claude','codex']) {
+  test(`integration: ${kind} executes a real fixture CLI, isolates work and cleans MCP configuration`, () => fixture(kind, async f => {
+    await f.run();
+    const trace = JSON.parse(await readFile(f.trace,'utf8'));
+    assert.equal(trace.received, true);
+    assert.ok(!trace.args.join(' ').includes('pulse_sk_fixture'));
+    assert.equal(await readFile(join(f.source,'source.txt'),'utf8'),'original');
+    assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
+    assert.equal(await exists(join(paths().root,'tmp',f.job.id)),false);
+    const completion = f.calls.find(c=>c.path==='/pulseRunnerComplete').body;
+    assert.equal(completion.outcome,'completed');
+    assert.ok(!JSON.stringify(f.calls).includes('pulse_sk_fixture'));
+  }));
+  test(`integration: ${kind} missing native session rejects before creating worktrees`, () => fixture(kind, async f => {
+    f.settings.session = false; await f.updateSettings();
+    let prepared = false;
+    await assert.rejects(f.run({checkout:async()=>{prepared=true;}}),/session is unavailable/);
+    assert.equal(prepared,false);
+    assert.equal(await exists(f.trace),false);
+    assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'failed');
+  }));
+}
+
+test('integration: invalid signed jobs never reach checkout', () => fixture('codex', async f => {
+  const original = {...f.job};
+  const cases = [
+    {signature:'invalid'}, {workspaceId:'other'}, {runnerId:'other'}, {agentId:'other'},
+    {repoFullName:'other/repo'}, {expiresAt:new Date(Date.now()-1000).toISOString()},
+    {expiresAt:'invalid'}, {issuedAt:'invalid'}, {id:'rjob-../../outside'}, {mode:'other'},
+  ];
+  for (const mutation of cases) {
+    Object.assign(f.job,original,mutation);
+    if (!mutation.signature) f.signJob();
+    let prepared=false;
+    await assert.rejects(f.run({checkout:async()=>{prepared=true;}}));
+    assert.equal(prepared,false);
+    assert.equal(await exists(f.trace),false);
+  }
+}));
+
+for (const cause of ['remote', 'signal', 'revoked']) {
+  test(`integration: ${cause} cancellation stops the CLI and descendants, skips publication and cleans worktrees`, () => fixture('codex', async f => {
+    f.settings.slow=true; await f.updateSettings();
+    f.control.cancelWhenRunning=cause==='remote';
+    f.control.disconnectWhenRunning=cause==='revoked';
+    const controller=new AbortController();
+    let published=false;
+    const running=f.run({signal:controller.signal,publish:async()=>{published=true;}});
+    if(cause==='signal') {
+      for(let i=0;i<200 && !(await exists(f.trace));i++) await new Promise(r=>setTimeout(r,10));
+      assert.equal(await exists(f.trace),true);
+      controller.abort();
+    }
+    await running;
+    const trace=JSON.parse(await readFile(f.trace,'utf8'));
+    assert.equal(published,false);
+    assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'canceled');
+    assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
+    assert.equal(await exists(join(paths().root,'tmp',f.job.id)),false);
+    assert.equal(await git(['-C',f.source,'status','--porcelain']),'');
+    for(const pid of [trace.pid,trace.childPid]) {
+      let alive=true;
+      for(let i=0;i<50 && alive;i++) {try{process.kill(pid,0);}catch{alive=false;} if(alive) await new Promise(r=>setTimeout(r,20));}
+      assert.equal(alive,false,`process ${pid} must terminate`);
+    }
+    assert.equal(f.calls.at(-1).body.status,'online');
+  }));
+}
+
+test('integration: a cancellation before execution never starts the CLI', () => fixture('claude',async f=>{
+  f.control.cancel=true;
+  await f.run();
+  assert.equal(await exists(f.trace),false);
+  assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'canceled');
+}));
+
+test('integration: failed provider output is sanitized in reports and local logs',()=>fixture('codex',async f=>{
+  f.settings.fail=true; await f.updateSettings();
+  await f.run();
+  const completion=f.calls.find(c=>c.path==='/pulseRunnerComplete').body;
+  assert.equal(completion.outcome,'failed');
+  assert.match(completion.result,/redacted/);
+  assert.ok(!JSON.stringify(f.calls).includes('fixture-secret'));
+  const logs=await readFile(join(paths().logs,'runner.jsonl'),'utf8');
+  assert.ok(!logs.includes('pulse_sk_fixture'));
+  assert.ok(!logs.includes('fixture-secret'));
+}));
+
+test('integration: recovery prunes interrupted worktrees and temporary MCP files without touching the source',()=>fixture('codex',async f=>{
+  const mirror=join(paths().repos,'owner__repo.git');
+  const interrupted=join(paths().worktrees,'rjob-interrupted');
+  await git(['--git-dir',mirror,'worktree','add','--detach',interrupted,'HEAD']);
+  await writeFile(join(interrupted,'source.txt'),'interrupted edits');
+  const temp=join(paths().root,'tmp','rjob-interrupted');
+  await mkdir(temp,{recursive:true}); await writeFile(join(temp,'pulse-mcp.json'),'synthetic temporary data');
+  await writeFile(join(paths().root, 'active-job.json'), JSON.stringify({jobId:f.job.id}));
+  await recoverInterruptedWork(f.config);
+  assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'canceled');
+  assert.equal(await exists(join(paths().root,'active-job.json')),false);
+  f.calls.length=0;
+  assert.equal(await exists(interrupted),false);
+  assert.equal(await exists(temp),false);
+  assert.ok(!(await git(['--git-dir',mirror,'worktree','list','--porcelain'])).includes('rjob-interrupted'));
+  assert.equal(await readFile(join(f.source,'source.txt'),'utf8'),'original');
+  await f.run();
+  assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'completed');
+}));
+
+
+test('integration: one-shot and daemon share a lock; stale locks and thrown jobs release it',()=>fixture('codex',async()=>{
+  await withRunnerLock(async()=>{
+    await assert.rejects(withRunnerLock(async()=>{}),/already active/);
+  });
+  assert.equal(await exists(join(paths().root,'runner.lock')),false);
+  await writeFile(join(paths().root,'runner.lock'),'2147483647\n');
+  await assert.rejects(withRunnerLock(async()=>{throw new Error('fixture failure');}),/fixture failure/);
+  assert.equal(await exists(join(paths().root,'runner.lock')),false);
+  await withRunnerLock(async()=>{});
+}));
+
+test('integration: a job expires during execution and is stopped before publication',()=>fixture('claude',async f=>{
+  f.settings.slow=true; await f.updateSettings();
+  f.job.expiresAt=new Date(Date.now()+5000).toISOString(); f.signJob();
+  let published=false;
+  await f.run({publish:async()=>{published=true;}});
+  assert.equal(published,false);
+  assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'canceled');
+  assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
+}));
+
+test('integration: QA execution retains read-only flags and never publishes',()=>fixture('codex',async f=>{
+  f.job.mode='review'; f.signJob();
+  f.config.agentRole='qa';
+  let published=false;
+  await f.run({publish:async()=>{published=true;}});
+  const trace=JSON.parse(await readFile(f.trace,'utf8'));
+  assert.ok(trace.args.includes('read-only'));
+  assert.equal(published,false);
+  assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'completed');
+}));
+
+test('integration: signed multi-repo worktrees are passed to the adapter and all cleaned',()=>fixture('codex',async f=>{
+  await git(['clone','--mirror',f.source,join(paths().repos,'owner__app.git')]);
+  f.config.repos.push('owner/app');
+  f.job.contextRepos=['owner/repo','owner/app']; f.signJob();
+  await f.run();
+  const trace=JSON.parse(await readFile(f.trace,'utf8'));
+  assert.ok(trace.args.includes('--add-dir'));
+  assert.ok(trace.args.some(arg=>arg.endsWith('owner__app')));
+  assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
+  for (const repo of ['owner__repo.git','owner__app.git']) {
+    assert.ok(!(await git(['--git-dir',join(paths().repos,repo),'worktree','list','--porcelain'])).includes('rjob-test'));
+  }
+}));
+
+
+test('integration: committed job branches push to a local remote and report the fixture PR',()=>fixture('codex',async f=>{
+  f.settings.publish=true; await f.updateSettings();
+  const original=await git(['-C',f.source,'rev-parse','HEAD']);
+  await f.run();
+  const completion=f.calls.find(c=>c.path==='/pulseRunnerComplete').body;
+  assert.equal(completion.outcome,'completed');
+  assert.match(completion.result,/owner\/repo:pul\/fixture/);
+  assert.match(completion.result,/https:\/\/github.com\/owner\/repo\/pull\/123/);
+  assert.equal(await git(['-C',f.source,'rev-parse','HEAD']),original);
+  assert.notEqual(await git(['-C',f.source,'rev-parse','refs/heads/pul/fixture']),original);
+  const calls=(await readFile(join(f.root,'gh-calls.jsonl'),'utf8')).trim().split('\n').map(JSON.parse);
+  assert.equal(calls[0][1],'view'); assert.equal(calls[1][1],'create');
+  assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
+}));

package/test/job.test.js

@@ -24,3 +24,15 @@ test('signed QA jobs require explicit agent identity and provider/role compatibi
   assert.equal(validateJob(job, config, { kind: 'codex', role: 'qa' }), true);
   assert.throws(() => validateJob(job, config, { kind: 'claude', role: 'qa' }), /provider/);
 });
+
+test('rejects signed envelopes with missing or invalid timestamps before execution', () => {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const config = { workspaceId: 'ws-1', agentId: 'agent-1', runnerId: 'runner-123456789012', repos: ['owner/repo'], signingKeyId: 'runner-job-v1', signingPublicKey: publicKey.export({ type: 'spki', format: 'pem' }).toString() };
+  const job = { id: 'rjob-456', workspaceId: 'ws-1', issueId: 'issue-1', agentId: 'agent-1', runnerId: 'runner-123456789012', repoFullName: 'owner/repo', mode: 'task', issuedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 60_000).toISOString(), signatureAlgorithm: 'ed25519', signingKeyId: 'runner-job-v1' };
+  const malformed = { ...job, expiresAt: 'invalid' };
+  malformed.signature = sign(null, Buffer.from(jobPayload(malformed)), privateKey).toString('base64url');
+  assert.throws(() => validateJob(malformed, config), /expired or malformed/);
+  const expired = { ...job, expiresAt: new Date(Date.now() - 1_000).toISOString() };
+  expired.signature = sign(null, Buffer.from(jobPayload(expired)), privateKey).toString('base64url');
+  assert.throws(() => validateJob(expired, config), /expired or malformed/);
+});

package/test/runtime.test.js

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { command, providerInvocation } from '../src/process.js';
+import { addIsolatedWorktree, removeIsolatedWorktree } from '../src/worktree.js';
+
+test('cancellation terminates the active child process', async () => {
+  const controller = new AbortController();
+  const running = command(process.execPath, ['-e', 'setTimeout(() => {}, 30000)'], { signal: controller.signal });
+  setTimeout(() => controller.abort(), 100);
+  const result = await running;
+  assert.notEqual(result.code, 0);
+});
+
+test('Claude and Codex adapters receive only ephemeral MCP configuration references', () => {
+  const config = { endpoint: 'https://pulse.example.test' };
+  const codex = providerInvocation('codex', '/tmp/job', [], config, '/tmp/pulse-mcp.json', 'run task');
+  const claude = providerInvocation('claude', '/tmp/job', [], config, '/tmp/pulse-mcp.json', 'run task');
+  assert.match(codex.args.join(' '), /env_http_headers/);
+  assert.doesNotMatch(codex.args.join(' '), /secret|credential-value/);
+  assert.ok(claude.args.includes('/tmp/pulse-mcp.json'));
+  assert.throws(() => providerInvocation('unknown', '/tmp/job', [], config, '', 'run task'), /Unsupported agent kind/);
+});
+
+test('an isolated worktree can change and clean up without changing its source checkout', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'pulse-runner-worktree-'));
+  const repo = join(root, 'repo');
+  const worktree = join(root, 'job');
+  try {
+    await command('git', ['init', repo]);
+    await writeFile(join(repo, 'source.txt'), 'original\n');
+    await command('git', ['-C', repo, 'add', 'source.txt']);
+    await command('git', ['-C', repo, '-c', 'user.name=Pulse Test', '-c', 'user.email=pulse@example.invalid', 'commit', '-m', 'initial']);
+    const checkout = await addIsolatedWorktree('owner/repo', join(repo, '.git'), worktree);
+    assert.ok(checkout.baseCommit);
+    await writeFile(join(worktree, 'source.txt'), 'changed in job\n');
+    assert.equal(await readFile(join(repo, 'source.txt'), 'utf8'), 'original\n');
+    await removeIsolatedWorktree(checkout);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});

package/test/service.test.js

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { service } from '../src/service.js';
+
+for (const platform of ['darwin','linux','win32']) {
+  test(`service: ${platform} retains instance home and supports install, stop, start and uninstall`,async()=>{
+    const root=await mkdtemp(join(tmpdir(),'pulse-service-'));
+    const saved=process.env.PULSE_RUNNER_HOME;
+    process.env.PULSE_RUNNER_HOME=join(root,'instance home');
+    const calls=[];
+    const options={platform,userHome:join(root,'os-user'),print:()=>{},command:async(exe,args)=>{calls.push({exe,args});return {code:0,output:''};}};
+    try {
+      await service('install',options);
+      if(platform==='darwin') {
+        const folder=join(options.userHome,'Library','LaunchAgents');
+        const [file]=await readdir(folder);const plist=await readFile(join(folder,file),'utf8');
+        assert.match(plist,/<string>--home<\/string>/);
+        assert.ok(plist.includes(process.env.PULSE_RUNNER_HOME));
+        assert.match(file,/com\.pulse\.runner\.[0-9a-f]{12}\.plist/);
+      } else if(platform==='linux') {
+        const folder=join(options.userHome,'.config','systemd','user');
+        const [file]=await readdir(folder);const unit=await readFile(join(folder,file),'utf8');
+        const homeArgument=unit.match(/--home ("(?:\\.|[^"])*")/)?.[1];
+        assert.equal(JSON.parse(homeArgument),process.env.PULSE_RUNNER_HOME);
+        assert.match(file,/pulse-runner-[0-9a-f]{12}\.service/);
+      } else {
+        const install=calls.find(c=>c.args.includes('/Create'));
+        assert.ok(install.args.some(arg=>arg.includes(`--home "${process.env.PULSE_RUNNER_HOME}"`)));
+        assert.ok(install.args.some(arg=>/^PulseRunner-[0-9a-f]{12}$/.test(arg)));
+      }
+      await service('stop',options);
+      const afterStop=calls.length;
+      await service('start',options);
+      if(platform==='darwin') assert.deepEqual(calls.slice(afterStop).map(c=>c.args[0]),['bootstrap','kickstart']);
+      await service('uninstall',options);
+      const firstName=calls.find(c=>c.args.some(arg=>/pulse\.runner\.|pulse-runner-|PulseRunner-/.test(arg))).args.join(' ');
+      process.env.PULSE_RUNNER_HOME=join(root,'second instance');
+      calls.length=0; await service('install',options);
+      const secondName=calls.find(c=>c.args.some(arg=>/pulse\.runner\.|pulse-runner-|PulseRunner-/.test(arg))).args.join(' ');
+      assert.notEqual(firstName,secondName);
+    } finally {
+      if(saved===undefined) delete process.env.PULSE_RUNNER_HOME;else process.env.PULSE_RUNNER_HOME=saved;
+      await rm(root,{recursive:true,force:true});
+    }
+  });
+}