@pulsehub/runner 0.1.12 → 0.1.13

package/README.md

@@ -124,3 +124,70 @@ resultados, errores libres, prompts y transcripts nunca se guardan ni se envían
 en el reporte QA. Los nombres de herramientas desconocidas se registran como
 `other`. Las líneas se limitan a 256 KiB y se emiten como máximo 500 eventos
 más el resumen. Un fallo al escribir el diagnóstico no interrumpe el job.
+
+## Local GitHub App identity (TES-305)
+
+Development jobs now require protocol 3 from Pulse. QA snapshots continue using
+protocol 2. Upgrade the backend and Runner together; configure every project/repo
+before starting development. No fallback to the active `gh` account, inherited Git
+credentials, or a PAT is performed. GitHub Actions agents are outside this flow.
+
+Use a GitHub App administered by the owner of this Runner/project. **Do not copy
+Pulse's shared service App private key to an end user's computer.** Install your
+local App only on the needed repositories with Metadata read, Contents write and
+Pull requests write. The bot identity is displayed in readiness. Changes to
+`.github/workflows` are blocked by this initial implementation; it does not
+silently grant Workflows permission. Configure an additional permission path
+before attempting such work. Repository rules and organization policy may still
+reject a publication after preflight.
+
+Store the App PEM private key in the OS credential store, using the service name
+`pulse-runner.github-app.APP_ID.KEY_ID`:
+
+- macOS: create a generic password in **Keychain Access**, with that service name
+  and the PEM as its password. Run Runner under the same OS user and permit access
+  when Keychain asks. Never place the PEM in command arguments or Runner config.
+- Linux: use a Secret Service compatible credential manager and store a secret
+  with attribute `service` equal to that name. `secret-tool` must be installed and
+  the user keyring unlocked for the Runner service.
+- Windows: local App key access is not supported yet; configuration fails closed.
+  QA remains supported. No plaintext fallback is provided.
+
+Associate public metadata explicitly; KEY_ID is a local reference, not a secret:
+
+```sh
+pulse-runner github-app set --project PROJECT_ID --repo owner/repo \
+  --app-id APP_ID --installation-id INSTALLATION_ID \
+  --slug app-slug --key-id KEY_ID
+pulse-runner github-app list
+pulse-runner diagnose
+```
+
+Repeat for all repositories, including additional worktrees. An installation must
+belong to the repository owner. Setup checks the App identity, installation and
+actual token grant before saving the binding. Token grants are requested for one
+repository with only Contents/PR write and Metadata read; the key and tokens never
+reach Pulse/MCP, config, URLs, CLI arguments, logs, or the agent environment.
+Removing a binding with `github-app remove --project PROJECT_ID --repo owner/repo`
+does not delete the key or revoke its installation. Revoke those in the OS store
+and GitHub as needed, and send a fresh diagnose report.
+
+Pulse signs the repository, bot identity, installation, base and branch of each
+job. Runner prepares those exact branches and commits remain local until its
+publication step. Public manifests under `publications/` and Git refs under
+`refs/pulse-recovery/` preserve commits independently of temporary worktrees.
+Interrupted work that has not been checkpointed is retained with a
+`.publication-pending` marker, while temporary provider MCP files are removed.
+
+When the agent finishes but GitHub publication fails, the job reports both
+outcomes and the failed stage. **Reintentar publicación** in Pulse creates a new
+signed authorization for the same repos/refs/commits on the same Runner. It does
+not run the provider CLI. Existing branches and PRs are reconciled; no force push
+is used. All PRs are explicitly linked to the issue. Revoked access, a changed
+project/App identity, a missing recovery ref, or divergent remote work blocks the
+retry with a safe diagnosis. Recovery refs/manifests are retained after success;
+remove them only after verifying the work is safely published.
+
+The agent still runs as the local OS user. This feature isolates the Runner's
+publication transport; it is not an OS sandbox preventing arbitrary agent code
+from reading other user credentials.

package/package.json

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

package/src/github-app.js

@@ -0,0 +1,101 @@
+import { createSign } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { platform } from 'node:os';
+import { command } from './process.js';
+import { writeConfig } from './config.js';
+
+const exec = promisify(execFile);
+const repoPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const identifier = /^[-A-Za-z0-9_]{1,100}$/;
+export function validateBinding(entry) {
+  if (!entry || !identifier.test(entry.projectId || '') || !repoPattern.test(entry.repo || '') || !/^\d+$/.test(String(entry.appId || '')) || !/^\d+$/.test(String(entry.installationId || '')) || !identifier.test(entry.slug || '') || !identifier.test(entry.keyId || '')) throw new Error('Invalid local GitHub App binding.');
+  return { projectId: entry.projectId, repo: entry.repo, appId: String(entry.appId), installationId: String(entry.installationId), slug: entry.slug, keyId: entry.keyId };
+}
+export function bindingFor(config, projectId, repo) {
+  const bindings = (config.githubApps || []).filter((e) => e.projectId === projectId && e.repo === repo);
+  if (bindings.length !== 1) throw new Error(`Configure one local GitHub App for project ${projectId}, repo ${repo}.`);
+  return validateBinding(bindings[0]);
+}
+export async function readAppKey(binding) {
+  const service = `pulse-runner.github-app.${binding.appId}.${binding.keyId}`;
+  try {
+    // Read only. Setup is performed in the OS credential manager, never through
+    // secret CLI arguments. Do not forward stdout/stderr or exec errors.
+    const result = platform() === 'darwin'
+      ? await exec('/usr/bin/security', ['find-generic-password', '-s', service, '-w'], { timeout: 10_000, maxBuffer: 32_768 })
+      : platform() === 'linux'
+        ? await exec('secret-tool', ['lookup', 'service', service], { timeout: 10_000, maxBuffer: 32_768 })
+        : null;
+    if (!result || !/-----BEGIN (?:RSA )?PRIVATE KEY-----/.test(result.stdout)) throw new Error();
+    return result.stdout.trim();
+  } catch { throw new Error('Local GitHub App key is unavailable in the OS credential store.'); }
+}
+export function appJwt(appId, privateKey, now = Date.now()) {
+  const seconds = Math.floor(now / 1000);
+  const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+  const message = `${encode({ alg: 'RS256', typ: 'JWT' })}.${encode({ iat: seconds - 60, exp: seconds + 540, iss: String(appId) })}`;
+  return `${message}.${createSign('RSA-SHA256').update(message).sign(privateKey).toString('base64url')}`;
+}
+export async function githubApi(path, token, options = {}, fetcher = fetch) {
+  if (!path.startsWith('/') || path.includes('://')) throw new Error('Invalid GitHub API path.');
+  const response = await fetcher(`https://api.github.com${path}`, {
+    method: options.method || 'GET', redirect: 'error', signal: options.signal || AbortSignal.timeout(30_000),
+    headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', ...(options.body ? { 'Content-Type': 'application/json' } : {}) },
+    ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+  });
+  // Response bodies can contain reflected credentials; only report status/stage.
+  if (!response.ok) throw Object.assign(new Error(`GitHub rejected ${options.method || 'GET'} request (HTTP ${response.status}).`), { status: response.status });
+  return response.status === 204 ? null : response.json();
+}
+export async function authorizeRepo(config, projectId, repo, options = {}) {
+  const binding = bindingFor(config, projectId, repo);
+  const api = options.api || githubApi;
+  let jwt;
+  try { jwt = appJwt(binding.appId, await (options.readKey || readAppKey)(binding)); }
+  catch { throw new Error('Local GitHub App key cannot sign requests.'); }
+  const app = await api('/app', jwt);
+  if (String(app.id) !== binding.appId || app.slug !== binding.slug) throw new Error('GitHub App identity differs from the selected local binding.');
+  const installation = await api(`/app/installations/${binding.installationId}`, jwt);
+  if (installation.suspended_at || installation.account?.login?.toLowerCase() !== repo.split('/')[0].toLowerCase()) throw new Error('GitHub App installation is suspended or belongs to another repository owner.');
+  if (installation.permissions?.contents !== 'write' || installation.permissions?.pull_requests !== 'write') throw new Error('GitHub App requires Contents write and Pull requests write.');
+  const granted = await api(`/app/installations/${binding.installationId}/access_tokens`, jwt, { method: 'POST', body: { repositories: [repo.split('/')[1]], permissions: { contents: 'write', pull_requests: 'write', metadata: 'read' } } });
+  if (!granted.token || !Number.isFinite(Date.parse(granted.expires_at)) || Date.parse(granted.expires_at) <= Date.now() || granted.permissions?.contents !== 'write' || granted.permissions?.pull_requests !== 'write' || !Array.isArray(granted.repositories) || granted.repositories.length !== 1 || granted.repositories[0].full_name.toLowerCase() !== repo.toLowerCase()) throw new Error('GitHub did not grant the exact repository and publication permissions requested.');
+  const metadata = await api(`/repos/${repo}`, granted.token);
+  if (metadata.archived || metadata.disabled || metadata.full_name.toLowerCase() !== repo.toLowerCase() || !metadata.default_branch) throw new Error('Selected repository is unavailable for publication.');
+  return { token: granted.token, expiresAt: granted.expires_at, base: metadata.default_branch, identity: { projectId, repo, appId: binding.appId, installationId: binding.installationId, slug: binding.slug }, api: (path, options) => api(path, granted.token, options) };
+}
+export async function githubReadiness(config, options = {}) {
+  const entries = [];
+  for (const entry of config.githubApps || []) {
+    const binding = validateBinding(entry);
+    const identity = { projectId: binding.projectId, repo: binding.repo, appId: binding.appId, installationId: binding.installationId, slug: binding.slug };
+    try { const grant = await authorizeRepo(config, binding.projectId, binding.repo, options); entries.push({ ...identity, ready: true, base: grant.base }); }
+    catch { entries.push({ ...identity, ready: false }); }
+  }
+  return entries;
+}
+export async function appGit(grant, repo, args, options = {}, run = command) {
+  if (!repoPattern.test(repo) || grant.identity.repo !== repo || Date.parse(grant.expiresAt) <= Date.now()) throw new Error('GitHub repository grant is invalid or expired.');
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^GIT_|^(GH_TOKEN|GITHUB_TOKEN|GH_ENTERPRISE_TOKEN|GITHUB_ENTERPRISE_TOKEN)$/.test(key)));
+  // Credentials remain in the transport environment, never in argv/config/URL.
+  Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'http.https://github.com/.extraHeader', GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`x-access-token:${grant.token}`).toString('base64')}` });
+  const result = await run('git', ['-c', 'credential.helper=', '-c', 'http.extraHeader=', '-c', 'http.followRedirects=false', '-c', 'http.sslVerify=true', '-c', 'http.proxy=', '-c', 'core.hooksPath=/dev/null', ...args], { ...options, env });
+  if (result.code !== 0) throw new Error('GitHub Git transport failed; check repository permissions, branch rules or connectivity.');
+  return result;
+}
+export async function githubAppCommand(config, args) {
+  if (args[1] === 'list') return console.log(JSON.stringify(config.githubApps || [], null, 2));
+  const value = (flag) => args[args.indexOf(flag) + 1];
+  const projectId = value('--project'); const repo = value('--repo');
+  if (!args.includes('--project') || !args.includes('--repo') || !['set', 'remove'].includes(args[1])) throw new Error('Use github-app set|remove --project ID --repo owner/repo [--app-id ID --installation-id ID --slug SLUG --key-id ID].');
+  const entries = (config.githubApps || []).filter((e) => e.projectId !== projectId || e.repo !== repo);
+  if (args[1] === 'set') {
+    if (['--app-id','--installation-id','--slug','--key-id'].some(flag => !args.includes(flag))) throw new Error('All public GitHub App identity flags are required.');
+    const binding = validateBinding({ projectId, repo, appId: value('--app-id'), installationId: value('--installation-id'), slug: value('--slug'), keyId: value('--key-id') });
+    await authorizeRepo({ ...config, githubApps: [...entries, binding] }, projectId, repo);
+    entries.push(binding);
+  }
+  await writeConfig({ ...config, githubApps: entries });
+  console.log('Local GitHub App binding updated. Run pulse-runner diagnose.');
+}

package/src/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { githubAppCommand } from './github-app.js';
 import { inspectReadiness, localIdentities } from './readiness.js';
 import { generateKeyPairSync } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
@@ -21,7 +22,7 @@ for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
 });
 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|profile|service>\n\ninit --workspace WS --agent AGENT [--agent-kind codex|claude] [--agent-role dev|qa] --signing-public-key FILE --allow-autonomous [--endpoint URL] \npair --credential runner.secret\nidentity add|remove --agent ID --agent-kind codex|claude --agent-role dev|qa | identity list\nprofile list|set|remove [--model MODEL] [--repo owner/repo --directory PATH]\nstart | run --once | diagnose | service install|start|stop|status|uninstall`);
+const usage = () => console.log(`pulse-runner <init|pair|start|run|diagnose|identity|repo|profile|github-app|service>\n\ninit --workspace WS --agent AGENT [--agent-kind codex|claude] [--agent-role dev|qa] --signing-public-key FILE --allow-autonomous [--endpoint URL] \npair --credential runner.secret\nidentity add|remove --agent ID --agent-kind codex|claude --agent-role dev|qa | identity list\nprofile list|set|remove [--model MODEL] [--repo owner/repo --directory PATH]\nstart | run --once | diagnose | service install|start|stop|status|uninstall`);
 
 async function start(config) {
   return withRunnerLock(async () => {
@@ -51,7 +52,7 @@ async function diagnose(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]);
-  if (providers.some((provider) => !provider?.cli || !provider?.session) || readiness.repositories.some((repo) => !repo.accessible)) process.exitCode = 1;
+  if (providers.some((provider) => !provider?.cli || !provider?.session) || readiness.repositories.some((repo) => !repo.accessible) || readiness.githubApps.some((entry) => !entry.ready)) process.exitCode = 1;
 }
 async function identity(config) {
   if (args[1] === 'list') return console.log(JSON.stringify(localIdentities(config), null, 2));
@@ -71,5 +72,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);  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(); else if (args[0] === 'profile') await profileCommand(config, args); 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(); }
+  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] === 'github-app') await githubAppCommand(config, args); else if (args[0] === 'repo') await repo(); else if (args[0] === 'profile') await profileCommand(config, args); 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

@@ -1,10 +1,11 @@
+import { publicationPayload, validBranch } from './publication.js';
 import { verify } from 'node:crypto';
 
 const b64 = (value) => Buffer.from(value, 'base64url');
 export function jobPayload(job) {
   const contextRepos = [...new Set(job.contextRepos || [job.repoFullName])].sort().join(',');
   const fields = [job.id, job.workspaceId, job.issueId, job.agentId, job.runnerId, job.repoFullName, contextRepos, job.mode, job.issuedAt, job.expiresAt, job.signatureAlgorithm, job.signingKeyId];
-  return (job.protocolVersion === 2 ? [...fields, job.protocolVersion, job.projectId] : fields).join('.');
+  return (job.protocolVersion === 3 ? [...fields, 3, job.projectId, publicationPayload(job.publicationTargets), job.recoveryOf || ''] : job.protocolVersion === 2 ? [...fields, 2, job.projectId] : fields).join('.');
 }
 
 /** Reject an envelope before it can cause filesystem or process activity. */
@@ -12,8 +13,8 @@ export function validateJob(job, config, agentOrNow = null, suppliedNow = Date.n
   const agent = typeof agentOrNow === 'object' && agentOrNow !== null ? agentOrNow : null;
   const now = typeof agentOrNow === 'number' ? agentOrNow : suppliedNow;
   if (!job || typeof job.signature !== 'string' || job.signatureAlgorithm !== 'ed25519' || job.signingKeyId !== config.signingKeyId) throw new Error('Job signing key is not trusted.');
-  if (job.protocolVersion !== undefined && job.protocolVersion !== 2) throw new Error('Job protocol is not supported.');
-  if (job.protocolVersion === 2 && (typeof job.projectId !== 'string' || !/^[-A-Za-z0-9_]+$/.test(job.projectId))) throw new Error('Job project is invalid.');
+  if (job.protocolVersion !== undefined && ![2, 3].includes(job.protocolVersion)) throw new Error('Job protocol is not supported.');
+  if ([2, 3].includes(job.protocolVersion) && (typeof job.projectId !== 'string' || !/^[-A-Za-z0-9_]+$/.test(job.projectId))) throw new Error('Job project is invalid.');
   if (!config.signingPublicKey || !verify(null, Buffer.from(jobPayload(job)), config.signingPublicKey, b64(job.signature))) throw new Error('Job signature is invalid.');
   const issuedAt = Date.parse(job.issuedAt);
   const expiresAt = Date.parse(job.expiresAt);
@@ -23,7 +24,16 @@ export function validateJob(job, config, agentOrNow = null, suppliedNow = Date.n
   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) => typeof repo !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || (job.protocolVersion !== 2 && !(config.repos || []).includes(repo)))) throw new Error('Job repository context is not allowed by this Runner.');
+  if (!contextRepos.includes(job.repoFullName) || contextRepos.some((repo) => typeof repo !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || (![2, 3].includes(job.protocolVersion) && !(config.repos || []).includes(repo)))) throw new Error('Job repository context is not allowed by this Runner.');
+  if (job.protocolVersion === 3) {
+    if (!Array.isArray(job.publicationTargets) || job.publicationTargets.length > 100 || !job.publicationTargets.length || job.mode === 'review') throw new Error('Invalid signed publication scope.');
+    const repos = new Set();
+    for (const t of job.publicationTargets) {
+      if (!contextRepos.includes(t.repo) || repos.has(t.repo) || !validBranch(t.branch) || !t.branch.startsWith('pul/') || !validBranch(t.base) || !/^\d+$/.test(t.appId) || !/^\d+$/.test(t.installationId) || !/^[-A-Za-z0-9_]{1,100}$/.test(t.slug) || (job.recoveryOf && !/^[a-f0-9]{40}$/.test(t.sha))) throw new Error('Invalid signed publication target.');
+      repos.add(t.repo);
+    }
+    if ((!job.recoveryOf && contextRepos.some(repo => !repos.has(repo))) || (job.recoveryOf && !/^rjob-[A-Za-z0-9_-]+$/.test(job.recoveryOf))) throw new Error('Invalid publication recovery scope.');
+  }
   return true;
 }
 

package/src/process.js

@@ -109,9 +109,10 @@ export async function runAgent(kind, job, worktree, additionalWorktrees, config,
       ? ` Snapshot manifest: ${join(worktree, '..', 'qa-sources.json')}. Additional review worktrees for inspection: ${reviewWorktrees.map(({ repo, worktree: path }) => `${repo} (${path})`).join('; ')}.`
       : ` Additional writable project worktrees: ${reviewWorktrees.map(({ repo, worktree: path }) => `${repo} (${path})`).join('; ')}. They are authorized for this same job: do not request a repository handoff. For every repository you change, create a pul/* branch in that worktree and commit the changes; the Runner will publish a PR for each changed branch.`
     : '';
+  const publicationInstructions = job.publicationTargets ? ` Signed publication branches: ${job.publicationTargets.map(t => `${t.repo}: ${t.branch}`).join('; ')}. Use exactly these branches for new work; for rework keep the prepared detached HEAD. The Runner handles push and PR creation; commit locally and do not publish or use GitHub credentials.` : '';
   const prompt = job.mode === 'review'
     ? `You are Pulse Runner performing a QA review for issue ${job.issueId}. First call pulse_next_review with identifier "${job.issueId}"; if found is false, stop without reviewing. Then call pulse_get_review_context with the same identifier. Review every pull request and its diff returned by that tool, along with the issue acceptance criteria and project Definition of Done. Use the provided local worktrees only to inspect files when a diff is too large or more context is needed. Snapshots are read-only and have no Git identity. Do not install dependencies or run build/tests/scripts from the reviewed code: provider sessions are present. Do not modify files, commit, push, or create pull requests. Submit the evidence-based verdict with pulse_submit_review. If you cannot submit a verdict for any reason, call pulse_report_review_incomplete before ending. Do not print, persist, or transmit credentials.${context}`
-    : `You are Pulse Runner executing ${job.mode} for issue ${job.issueId}. Use the Pulse MCP server for issue context and reporting. Work only in the provided project worktrees. Do not print, persist, or transmit credentials.${context}`;
+    : `You are Pulse Runner executing ${job.mode} for issue ${job.issueId}. Use the Pulse MCP server for issue context and reporting. Work only in the provided project worktrees. Do not print, persist, or transmit credentials.${context}${publicationInstructions}`;
   const mcp = await mcpConfig(tempDir, credential, config.endpoint);
   const additionalDirs = reviewWorktrees.flatMap(({ worktree: path }) => ['--add-dir', path]);
   try {
@@ -119,7 +120,8 @@ export async function runAgent(kind, job, worktree, additionalWorktrees, config,
     const agentDirectory = job.mode === 'review' ? tempDir : worktree;
     const invocation = providerInvocation(kind, agentDirectory, additionalDirs, config, mcp, prompt, job.mode);
     if (options.profile?.model) invocation.args.splice(kind === 'codex' ? 1 : 0, 0, '--model', options.profile.model);
-    const env = kind === 'codex' ? { ...process.env, PULSE_RUNNER_MCP_CREDENTIAL: `Bearer ${credential}` } : process.env;
+    const providerEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(GH_TOKEN|GITHUB_TOKEN|GH_ENTERPRISE_TOKEN|GITHUB_ENTERPRISE_TOKEN|GIT_CONFIG_VALUE_\d+)$/.test(key)));
+    const env = kind === 'codex' ? { ...providerEnv, PULSE_RUNNER_MCP_CREDENTIAL: `Bearer ${credential}` } : providerEnv;
     const diagnosticMode = kind === 'codex' && job.mode === 'review';
     let writes = Promise.resolve();
     let stderrBytes = 0;

package/src/publication.js

@@ -0,0 +1,114 @@
+import { mkdir, readFile, rename, writeFile, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { paths } from './config.js';
+import { command } from './process.js';
+import { authorizeRepo, appGit } from './github-app.js';
+import { sanitize } from './job.js';
+
+const jobIdPattern = /^rjob-[A-Za-z0-9_-]+$/;
+export function publicationPayload(targets = []) {
+  return JSON.stringify([...targets].sort((a, b) => a.repo.localeCompare(b.repo)).map(t => [t.repo, t.branch, t.base, t.appId, t.installationId, t.slug, t.sha || '']));
+}
+export function validBranch(value) {
+  return typeof value === 'string' && value.length <= 200 && !/\.\.|@\{|[\s~^:?*\[\\]|\/\/|\.$|\.lock(?:\/|$)|^\/|\/$/.test(value) && value.split('/').every(p => p && !p.startsWith('.'));
+}
+function manifestPath(jobId) {
+  if (!jobIdPattern.test(jobId)) throw new Error('Invalid publication job.');
+  return join(paths().root, 'publications', `${jobId}.json`);
+}
+export async function savePublication(manifest) {
+  const file = manifestPath(manifest.jobId);
+  await mkdir(join(paths().root, 'publications'), { recursive: true, mode: 0o700 });
+  await writeFile(`${file}.tmp`, `${JSON.stringify(manifest)}\n`, {mode: 0o600});
+  await chmod(`${file}.tmp`, 0o600); await rename(`${file}.tmp`, file);
+}
+export async function loadPublication(jobId) { return JSON.parse(await readFile(manifestPath(jobId), 'utf8')); }
+export function publicationReport(manifest) {
+  return {execution: manifest.execution, repositories: manifest.repositories.map(({repo, branch, sha, stage, prNumber, prUrl}) => ({repo, branch, sha, stage, ...(prNumber ? {prNumber, prUrl} : {})}))};
+}
+async function git(args, signal) {
+  const result = await command('git', ['-c', 'core.hooksPath=/dev/null', ...args], {signal});
+  if (result.code !== 0) throw new Error('Local publication commit inspection failed.');
+  return result.output.trim();
+}
+export async function preparePublication(job, checkouts, execution = 'completed', signal) {
+  if (job.protocolVersion !== 3 || !job.publicationTargets) throw new Error('Publication requires a signed local GitHub App job. Upgrade Pulse and configure github-app.');
+  const manifest = {version: 1, jobId: job.id, workspaceId: job.workspaceId, runnerId: job.runnerId, projectId: job.projectId, issueId: job.issueId, execution, repositories: []};
+  // Record each recovery ref before cleanup, including commits from local source repos.
+  for (const checkout of checkouts) {
+    const target = job.publicationTargets.find(t => t.repo === checkout.repo);
+    if (!target) throw new Error('Repository is outside signed publication scope.');
+    const sha = await git(['-C', checkout.worktree, 'rev-parse', 'HEAD'], signal);
+
+    const branch = await git(['-C', checkout.worktree, 'branch', '--show-current'], signal);
+    if (branch !== target.branch && !(job.mode === 'rework' && branch === '')) throw new Error('Agent commit branch differs from the signed job branch.');
+    const status = await git(['-C', checkout.worktree, 'status', '--porcelain'], signal);
+    if (status.split('\n').some(line => line && !line.endsWith('.pulse-runner-job'))) throw new Error('Commit all changes before publication.');
+    if (sha === checkout.baseCommit) continue;
+    const storage = checkout.sourceDirectory || checkout.mirror;
+    const recoveryRef = `refs/pulse-recovery/${job.id}/${checkout.repo.replace('/', '__')}`;
+    await git([...(checkout.sourceDirectory ? ['-C', storage] : ['--git-dir', storage]), 'update-ref', recoveryRef, sha], signal);
+    const title = sanitize(await git(['-C', checkout.worktree, 'log', '-1', '--format=%s'], signal)).replace(/\s+/g, ' ').slice(0, 120) || 'Pulse Runner update';
+    manifest.repositories.push({...target, baseCommit: checkout.baseCommit, sha, title, storage, sourceDirectory: !!checkout.sourceDirectory, recoveryRef, stage: 'pending'});
+    await savePublication(manifest);
+  }
+  await savePublication(manifest);
+  return manifest;
+}
+export async function resumePublication(job) {
+  const original = await loadPublication(job.recoveryOf);
+  if (original.workspaceId !== job.workspaceId || original.runnerId !== job.runnerId || original.projectId !== job.projectId || original.issueId !== job.issueId || original.execution !== 'completed') throw new Error('Publication recovery identity mismatch.');
+  const repositories = job.publicationTargets.map(target => {
+    const entry = original.repositories.find(e => e.repo === target.repo);
+    if (!entry || entry.sha !== target.sha || ['branch','base','appId','installationId','slug'].some(key => entry[key] !== target[key])) throw new Error('Publication recovery scope mismatch.');
+    return {...entry};
+  });
+  if (repositories.length !== original.repositories.length) throw new Error('Publication recovery omitted repositories.');
+  const manifest = {...original, jobId: job.id, repositories};
+  await savePublication(manifest);
+  return manifest;
+}
+export async function publishManifest(config, job, manifest, checkActive, remote, signal, deps = {}) {
+  const succeeded = []; const failed = [];
+  for (const entry of manifest.repositories) {
+    let phase = 'github-preflight';
+    try {
+      await checkActive();
+      const grant = await (deps.authorizeRepo || authorizeRepo)(config, job.projectId, entry.repo);
+      if (['appId', 'installationId', 'slug'].some(key => grant.identity[key] !== entry[key])) throw new Error('Selected local App identity differs from signed job.');
+      if (grant.base !== entry.base) throw new Error('Repository base changed since the job was authorized.');
+      const prefix = entry.sourceDirectory ? ['-C', entry.storage] : ['--git-dir', entry.storage];
+      const recovered = await git([...prefix, 'rev-parse', entry.recoveryRef], signal);
+      if (recovered !== entry.sha) throw new Error('Recovered commit differs from signed publication.');
+      const workflows = await git([...prefix, 'diff', '--name-only', entry.baseCommit, entry.sha, '--', '.github/workflows'], signal);
+      if (workflows) throw new Error('Workflow changes require separately authorized GitHub Workflows permission.');
+      // Reconcile the exact branch even when the previous attempt recorded a PR.
+      // A timeout can leave a push/PR complete but not recorded in the manifest.
+      phase = 'push';
+      await checkActive();
+      let remoteRef;
+      try { remoteRef = await grant.api(`/repos/${entry.repo}/git/ref/heads/${entry.branch.split('/').map(encodeURIComponent).join('/')}`); } catch (error) { if (error.status !== 404) throw error; }
+      if (remoteRef && remoteRef.object?.sha !== entry.sha && remoteRef.object?.sha !== entry.baseCommit) throw new Error('Remote branch diverged from the recovered publication commit.');
+      if (remoteRef?.object?.sha !== entry.sha) await (deps.appGit || appGit)(grant, entry.repo, [...prefix, 'push', `https://github.com/${entry.repo}.git`, `${entry.sha}:refs/heads/${entry.branch}`], {signal, timeout: 120_000});
+      entry.stage = 'pushed'; await savePublication(manifest);
+      phase = 'find-pull-request';
+      const prs = await grant.api(`/repos/${entry.repo}/pulls?state=all&head=${encodeURIComponent(`${entry.repo.split('/')[0]}:${entry.branch}`)}&base=${encodeURIComponent(entry.base)}&per_page=100`);
+      let pr = prs.find(p => p.head?.ref === entry.branch && p.head?.repo?.full_name === entry.repo && p.base?.ref === entry.base && p.state === 'open');
+      if (!pr && prs.length) throw new Error('A previous PR is closed or its publication scope changed.');
+      if (!pr) {
+        phase = 'create-pull-request'; await checkActive();
+        pr = await grant.api(`/repos/${entry.repo}/pulls`, {method: 'POST', body: {title: entry.title, head: entry.branch, base: entry.base, body: `Pulse Runner work for issue ${job.issueId}.`, draft: true}});
+      }
+      if (pr.head?.sha !== entry.sha || pr.head?.ref !== entry.branch || pr.head?.repo?.full_name !== entry.repo || pr.base?.repo?.full_name !== entry.repo || pr.base?.ref !== entry.base || !Number.isSafeInteger(pr.number) || pr.html_url !== `https://github.com/${entry.repo}/pull/${pr.number}` || pr.state !== 'open') throw new Error('GitHub PR does not match the exact publication commit and repository.');
+      entry.prNumber = pr.number; entry.prUrl = pr.html_url; entry.stage = 'pr_created'; await savePublication(manifest);
+      phase = 'link-pull-request'; await checkActive();
+      await remote(config, 'pulseRunnerLinkPr', {jobId: job.id, repo: entry.repo, branch: entry.branch, sha: entry.sha, prNumber: pr.number, prUrl: pr.html_url, prState: pr.draft ? 'draft' : 'open'});
+      entry.stage = 'linked'; await savePublication(manifest);
+      succeeded.push(entry.prUrl);
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      failed.push({repo: entry.repo, phase, error: sanitize(error.message)});
+    }
+  }
+  return {succeeded, failed};
+}

package/src/readiness.js

@@ -1,3 +1,4 @@
+import { githubReadiness } from './github-app.js';
 import { command, resolveExecutable } from './process.js';
 
 export function localIdentities(config) {
@@ -17,19 +18,16 @@ export async function inspectReadiness(config, run = command) {
     }).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, jobProtocolVersion: 2, qaSourceProtocolVersion: 1 };
+  const githubApps = await githubReadiness(config);
+  const repositories = [...new Set([...(config.repos || []), ...githubApps.map(e => e.repo)])].map(repo => ({repo, accessible: githubApps.some(e => e.repo === repo && e.ready)}));
+
+  return { workspaceId: config.workspaceId, identities: localIdentities(config), providers, repositories, githubApps, jobProtocolVersion: 3, qaSourceProtocolVersion: 1 };
 }
 
 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.mode !== 'review' && (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.');
+  if (!job.recoveryOf && (!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.mode !== 'review' && job.protocolVersion !== 3 && (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/src/runtime.js

@@ -1,9 +1,11 @@
+import { authorizeRepo, appGit } from './github-app.js';
+import { preparePublication, resumePublication, publishManifest, publicationReport, loadPublication } from './publication.js';
 import { appendFile, chmod, mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { ensureDataDir, paths, readCredential, readProfiles, removeTemporary } from './config.js';
 import { validateJob, sanitize } from './job.js';
-import { command, resolveExecutable, runAgent } from './process.js';
+import { command, runAgent } from './process.js';
 import { addIsolatedWorktree, removeIsolatedWorktree } from './worktree.js';
 import { resolveProfile, validateLocalRepo } from './profile.js';
 import { inspectReadiness, assertLocalReadiness, localIdentities } from './readiness.js';
@@ -50,16 +52,20 @@ function completionSummary(result, publication) {
   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, sourceDirectory) {
-  if (sourceDirectory) return addIsolatedWorktree(repo, sourceDirectory, worktree, { signal, sourceDirectory });
+async function checkoutRepo(repo, worktree, signal, sourceDirectory, grant, target, transport = appGit) {
+  if (sourceDirectory) {
+    const ref = target?.branch && target.rework ? target.branch : target.base;
+    await transport(grant, repo, ['-C', sourceDirectory, 'fetch', `https://github.com/${repo}.git`, `refs/heads/${ref}`], {signal, timeout: 120_000});
+    return addIsolatedWorktree(repo, sourceDirectory, worktree, {signal, sourceDirectory, ref: 'FETCH_HEAD'});
+  }
   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 });
+    const cloned = await transport(grant, repo, ['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 });
+  const fetchResult = await transport(grant, repo, ['--git-dir', mirror, 'fetch', `https://github.com/${repo}.git`, '+refs/heads/*:refs/heads/*'], { signal, timeout: 120_000 }); if (fetchResult.code !== 0) throw new Error(sanitize(fetchResult.output));
+  return addIsolatedWorktree(repo, mirror, worktree, { signal, ref: `refs/heads/${target.rework ? target.branch : target.base}` });
 }
 async function checkout(job, options = {}) {
   if (job.mode === 'review') return checkoutQa(job, options);
@@ -67,8 +73,13 @@ async function checkout(job, options = {}) {
   await mkdir(root, { recursive: true, mode: 0o700 });
   try {
     for (const repo of repos) {
-      const checkout = await checkoutRepo(repo, join(root, repoPath(repo)), options.signal, repo === job.repoFullName ? options.profile?.directory : undefined);
+      const checkout = await checkoutRepo(repo, join(root, repoPath(repo)), options.signal, repo === job.repoFullName ? options.profile?.directory : undefined, options.grants?.[repo], {...job.publicationTargets?.find(t => t.repo === repo), rework: job.mode === 'rework'}, options.transport);
       await writeFile(join(checkout.worktree, '.pulse-runner-job'), job.id, { mode: 0o600 });
+      const target = job.publicationTargets?.find(t => t.repo === repo);
+      if (target && job.mode !== 'rework') {
+        const switched = await command('git', ['-C', checkout.worktree, 'switch', '-c', target.branch], {signal: options.signal});
+        if (switched.code !== 0) throw new Error('Could not prepare the signed publication branch.');
+      }
       checkouts.push(checkout);
     }
     const primary = checkouts.find((checkout) => checkout.repo === job.repoFullName);
@@ -104,68 +115,9 @@ async function cleanup(checkouts) {
     await removeTemporary(worktree);
   }));
 }
-async function publishCheckout(checkout, jobId, issueId, 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 '';
-  }
-  const subject = await command('git', ['-C', checkout.worktree, 'log', '-1', '--format=%s'], { signal });
-  if (subject.code !== 0) throw Object.assign(new Error(sanitize(subject.output)), { phase });
-  const pullRequestTitle = sanitize(subject.output.trim().replace(/\s+/g, ' ')).slice(0, 120) || 'Pulse Runner update';
-  // 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', [...(checkout.sourceDirectory ? ['-C', checkout.worktree] : ['-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 pullRequestBody = `Automated changes from Pulse Runner for issue ${sanitize(issueId)}.`;
-  const created = await command(resolveExecutable('gh'), ['pr', 'create', '--repo', checkout.repo, '--base', 'main', '--head', branch, '--title', pullRequestTitle, '--body', pullRequestBody], { 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, issueId, checkActive, signal) {
-  const publications = { succeeded: [], failed: [] };
-  for (const checkout of checkouts) {
-    try {
-      const published = await publishCheckout(checkout, jobId, issueId, 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]);
+  const key = JSON.stringify([config.workspaceId, localIdentities(config), config.repos, config.githubApps]);
   if (force || !readinessCache || readinessCache.key !== key || Date.now() - readinessCache.at > 60_000) readinessCache = { key, at: Date.now(), value: await inspectReadiness(config) };
   return readinessCache.value;
 }
@@ -174,7 +126,8 @@ 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 publishWork = options.publish;
+  const authorize = options.authorizeRepo || authorizeRepo;
   const cleanWork = options.cleanup || cleanup;
   const controller = new AbortController();
   const cancel = () => controller.abort();
@@ -205,9 +158,16 @@ export async function runOnce(config, options = {}) {
     const agent = delivery.agent || { kind: config.agentKind, role: job.agentId === config.agentId ? 'dev' : null };
     validateJob(job, config, agent);
     jobPhase = 'local-preflight';
-    const profile = await resolveProfile({ ...config, agentKind: agent.kind }, job);
-    const jobConfig = job.protocolVersion === 2 ? { ...config, repos: job.contextRepos || [job.repoFullName] } : config;
+    const profile = job.recoveryOf ? null : await resolveProfile({ ...config, agentKind: agent.kind }, job);
+    const jobConfig = [2, 3].includes(job.protocolVersion) ? { ...config, repos: job.contextRepos || [job.repoFullName] } : config;
+    if (job.mode !== 'review' && job.protocolVersion !== 3) throw new Error('Development publication requires a signed GitHub App job (protocol 3). Upgrade Pulse and configure github-app locally.');
     assertLocalReadiness(job, jobConfig, agent, await readinessForJob(jobConfig, true));
+    const grants = {};
+    if (job.protocolVersion === 3) for (const target of job.publicationTargets) {
+      const grant = await authorize(jobConfig, job.projectId, target.repo);
+      if (['appId','installationId','slug'].some(key => grant.identity[key] !== target[key]) || grant.base !== target.base) throw new Error('Selected local GitHub App does not match signed publication identity.');
+      grants[target.repo] = grant;
+    }
     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()));
@@ -225,31 +185,48 @@ export async function runOnce(config, options = {}) {
         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, profile, config, credential: delivery.mcpCredential });
-    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, profile, onDiagnostic: ({ event, ...details }) => logEvent(event, { jobId: job.id, ...details }) });
-      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, job.issueId, 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));
+    if (job.recoveryOf) {
+      jobPhase = 'recover-publication';
+      const manifest = await resumePublication(job);
+      const publication = await publishManifest(config, job, manifest, checkActive, remote, controller.signal, {authorizeRepo: authorize, ...options.publicationDeps});
+      completion = {jobId: job.id, outcome: publication.failed.length ? 'failed' : 'completed', result: sanitize(completionSummary({code: 0}, publication)), publication: publicationReport(manifest), failure: publication.failed.length ? {phase: publication.failed[0].phase, category: 'execution', correlationId: job.id} : null};
+    } else {
+      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, profile, config, credential: delivery.mcpCredential, grants, transport: options.appGit });
+      const temp = join(paths().root, 'tmp', job.id);
+      let preserveWork = job.protocolVersion === 3;
+      const marker = join(paths().worktrees, job.id, '.publication-pending');
+      if (preserveWork) await writeFile(marker, 'Local work awaiting durable publication snapshot.', {mode: 0o600});
+      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, profile, onDiagnostic: ({ event, ...details }) => logEvent(event, { jobId: job.id, ...details }) });
+        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';
+        let manifest;
+        if (job.protocolVersion === 3) {
+          manifest = await preparePublication(job, checkouts, result.code === 0 ? 'completed' : 'failed', controller.signal);
+          if (result.code === 0) await remote(config, 'pulseRunnerPublication', {jobId: job.id, publication: publicationReport(manifest)});
+          preserveWork = false; await rm(marker, {force: true});
+        }
+        const publication = result.code === 0 && job.mode !== 'review'
+          ? publishWork ? await publishWork(checkouts, job.id, job.issueId, checkActive, controller.signal) : await publishManifest(config, job, manifest, checkActive, remote, controller.signal, {authorizeRepo: authorize, ...options.publicationDeps})
+          : {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, ...(manifest ? {publication: publicationReport(manifest)} : {}) };
+      } finally {
+        await removeTemporary(temp);
+        if (!preserveWork) { await cleanWork(checkouts); await removeTemporary(join(paths().worktrees, job.id)); }
+      }
     }
     controller.signal.throwIfAborted();
     await remote(config, 'pulseRunnerComplete', completion);
@@ -261,7 +238,8 @@ export async function runOnce(config, options = {}) {
     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) => {
+    const savedPublication = await loadPublication(job.id).catch(() => null);
+    await remote(config, 'pulseRunnerComplete', { ...(savedPublication ? {publication: publicationReport(savedPublication)} : {}), 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;
@@ -281,7 +259,7 @@ export async function recoverInterruptedWork(config) {
   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(async (entry) => { if (entry.isDirectory()) await makeWritable(join(area, entry.name)); await rm(join(area, entry.name), { recursive: true, force: true }); }));
+    await Promise.all(jobs.map(async (entry) => { if (area === p.worktrees && await stat(join(area, entry.name, '.publication-pending')).then(() => true).catch(() => false)) return; if (entry.isDirectory()) await makeWritable(join(area, entry.name)); await 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(() => {})));

package/src/worktree.js

@@ -4,7 +4,7 @@ import { sanitize } from './job.js';
 export async function addIsolatedWorktree(repo, gitDir, worktree, options = {}) {
   options.signal?.throwIfAborted();
   const prefix = options.sourceDirectory ? ['-C', options.sourceDirectory] : ['--git-dir', gitDir];
-  const added = await command('git', [...prefix, 'worktree', 'add', '--detach', worktree, 'HEAD'], options);
+  const added = await command('git', [...prefix, 'worktree', 'add', '--detach', worktree, options.ref || '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) {

package/test/github-app.test.js

@@ -0,0 +1,52 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { generateKeyPairSync, verify } from 'node:crypto';
+import { appJwt, authorizeRepo, appGit, bindingFor, githubReadiness, githubApi } from '../src/github-app.js';
+const {privateKey, publicKey}=generateKeyPairSync('rsa',{modulusLength:2048});
+const pem=privateKey.export({type:'pkcs8',format:'pem'}).toString();
+const binding={projectId:'project-1',repo:'owner/repo',appId:'1',installationId:'2',slug:'local-app',keyId:'local-key'};
+const config={githubApps:[binding]};
+function apiFixture(overrides={}) {
+  const calls=[];
+  const api=async(path,token,options)=>{
+    calls.push({path,token,options});
+    if(path==='/app') return {id:1,slug:'local-app',...overrides.app};
+    if(path==='/app/installations/2') return {account:{login:'owner'},permissions:{contents:'write',pull_requests:'write'},...overrides.installation};
+    if(path.endsWith('access_tokens')) return {token:'sentinel-github-secret',expires_at:new Date(Date.now()+3600000).toISOString(),permissions:{contents:'write',pull_requests:'write'},repositories:[{full_name:'owner/repo'}],...overrides.grant};
+    return {full_name:'owner/repo',default_branch:'main',...overrides.repo};
+  };
+  return {calls,api};
+}
+test('local App signs a short-lived JWT and never falls back to active gh identity',async()=>{
+  const jwt=appJwt('1',pem,1000000);
+  const [header,payload,signature]=jwt.split('.');
+  assert(verify('RSA-SHA256',Buffer.from(`${header}.${payload}`),publicKey,Buffer.from(signature,'base64url')));
+  const data=JSON.parse(Buffer.from(payload,'base64url'));assert.equal(data.iss,'1');assert.equal(data.exp-data.iat,600);
+  const f=apiFixture();const grant=await authorizeRepo(config,'project-1','owner/repo',{readKey:async()=>pem,api:f.api});
+  assert.equal(grant.identity.slug,'local-app');
+  const request=f.calls.find(c=>c.path.endsWith('access_tokens'));
+  assert.deepEqual(request.options.body,{repositories:['repo'],permissions:{contents:'write',pull_requests:'write',metadata:'read'}});
+  assert.throws(()=>bindingFor(config,'project-2','owner/repo'));
+  assert.throws(()=>bindingFor({...config,githubApps:[binding,binding]},'project-1','owner/repo'));
+});
+test('preflight rejects wrong App/owner, suspended installations, broad grants and missing PR permission',async()=>{
+  for(const overrides of [{app:{slug:'other'}},{installation:{suspended_at:'now'}},{installation:{account:{login:'other'}}},{installation:{permissions:{contents:'write'}}},{grant:{repositories:[{full_name:'owner/repo'},{full_name:'owner/other'}]}},{grant:{expires_at:'invalid'}},{repo:{archived:true}}]) {
+    const f=apiFixture(overrides);await assert.rejects(authorizeRepo(config,'project-1','owner/repo',{readKey:async()=>pem,api:f.api}));
+  }
+  const readiness=await githubReadiness(config,{readKey:async()=>{throw new Error('sentinel-private-key');}});
+  assert.equal(readiness[0].ready,false);assert(!JSON.stringify(readiness).includes('sentinel'));
+});
+test('Git transport passes secrets only to transport environment and ignores global credentials',async()=>{
+  const grant={identity:{repo:'owner/repo'},token:'sentinel-github-secret',expiresAt:new Date(Date.now()+60000).toISOString()};
+  await appGit(grant,'owner/repo',['push','https://github.com/owner/repo.git','a:refs/heads/pul/job'],{},async(exe,args,opts)=>{
+    assert.equal(exe,'git');assert(!args.join(' ').includes(grant.token));assert(!JSON.stringify(args).includes('Authorization'));
+    assert.equal(opts.env.GH_TOKEN,undefined);assert.equal(opts.env.GITHUB_TOKEN,undefined);
+    assert.equal(opts.env.GIT_CONFIG_NOSYSTEM,'1');assert.equal(opts.env.GIT_CONFIG_GLOBAL,'/dev/null');
+    assert(opts.env.GIT_CONFIG_VALUE_0.startsWith('Authorization: Basic '));return {code:0,output:''};
+  });
+  await assert.rejects(appGit(grant,'owner/other',[]));
+  await assert.rejects(appGit({...grant,expiresAt:'2000-01-01'},'owner/repo',[]));
+});
+test('GitHub errors discard reflected credentials rather than exposing response bodies',async()=>{
+  await assert.rejects(githubApi('/app','sentinel',{},async()=>({ok:false,status:403,text:async()=> 'sentinel-private-key'})),error=>error.message.includes('403')&&!error.message.includes('sentinel'));
+});

package/test/integration.test.js

@@ -37,9 +37,9 @@ else {
   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, cwd: process.cwd(), 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']]) {
+    writeFileSync('job-output.txt', 'isolated output');
+    for (const argv of [['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);
     }
@@ -63,15 +63,18 @@ else console.log('https://github.com/owner/repo/pull/123');
   await updateSettings();
   const p = await ensureDataDir();
   await writeCredential('runner-fixture.synthetic-device');
-  await git(['init', source]);
+  await git(['init', '--initial-branch=main', 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'); };
+  const job = { protocolVersion: 3, projectId: 'project-fixture', 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 = () => {
+    if (job.mode === 'review') {job.protocolVersion=2;delete job.publicationTargets;}
+    else if (job.protocolVersion===3 && !job.recoveryOf) job.publicationTargets=(job.contextRepos || [job.repoFullName]).map(repo=>({repo,branch:'pul/rjob-test',base:'main',appId:'1',installationId:'2',slug:'fixture-app'}));
+    job.signature = sign(null, Buffer.from(jobPayload(job)), privateKey).toString('base64url'); };
   signJob();
   const calls = [];
   const control = { cancel: false, cancelWhenRunning: false, disconnectWhenRunning: false };
@@ -97,7 +100,23 @@ else console.log('https://github.com/owner/repo/pull/123');
   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 });
+  let pushSha;
+  const appGit = async (grant, repo, args, options) => {
+    assert.equal(grant.identity.repo, repo);
+    assert(!args.join(' ').includes('sentinel-token'));
+    const rewritten = args.map(arg => arg.startsWith('https://github.com/') ? source : arg);
+    if (args.includes('push')) pushSha=args.at(-1).split(':')[0];
+    const result=await command('git', rewritten, options); assert.equal(result.code,0,result.output); return result;
+  };
+  const authorizeRepo = async (_config, projectId, repo) => {
+    if (!repo.startsWith('owner/')) throw new Error('Unauthorized fixture repository.');
+    return {identity: {projectId,repo,appId:'1',installationId:'2',slug:'fixture-app'},base:'main',token:'sentinel-token',expiresAt:new Date(Date.now()+60000).toISOString(),api:async(path, options)=>{
+      if (path.includes('/git/ref/')) throw Object.assign(new Error('Missing fixture ref'),{status:404});
+      if (!options) return [];
+      return {number:123,html_url:`https://github.com/${repo}/pull/123`,state:'open',head:{sha:pushSha,ref:'pul/rjob-test',repo:{full_name:repo}},base:{ref:'main',repo:{full_name:repo}}};
+    }};
+  };
+  const run = (extra = {}) => runOnce(config, { readinessFor, authorizeRepo, appGit, publicationDeps: {appGit}, 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));
@@ -149,7 +168,7 @@ test('integration: invalid signed jobs never reach checkout', () => fixture('cod
 }));
 
 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 => {
+  test(`integration: ${cause} cancellation stops the CLI and descendants, skips publication and preserves interrupted work`, () => fixture('codex', async f => {
     f.settings.slow=true; await f.updateSettings();
     f.control.cancelWhenRunning=cause==='remote';
     f.control.disconnectWhenRunning=cause==='revoked';
@@ -165,7 +184,7 @@ for (const cause of ['remote', 'signal', 'revoked']) {
     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().worktrees,f.job.id)),true);
     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]) {
@@ -240,7 +259,7 @@ test('integration: a job expires during execution and is stopped before publicat
   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);
+  assert.equal(await exists(join(paths().worktrees,f.job.id)),true);
 }));
 
 for (const kind of ['codex','claude']) test(`integration: ${kind} QA reads all project snapshots without global Git auth and never publishes`,()=>fixture(kind,async f=>{
@@ -287,18 +306,18 @@ test('integration: committed job branches push to a local remote and report the
   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.equal(completion.publication.repositories[0].branch,'pul/rjob-test');
   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.notEqual(await git(['-C',f.source,'rev-parse','refs/heads/pul/rjob-test']),original);
+  assert.equal(await exists(join(f.root,'gh-calls.jsonl')),false);
+  assert(f.calls.some(c=>c.path==='/pulseRunnerLinkPr'));
   assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
 }));
 
 
-test('integration: v2 job uses its signed repos without a local allowlist',()=>fixture('codex',async f=>{
-  f.job.protocolVersion=2;f.job.projectId='project-fixture';f.signJob();
+test('integration: v3 job uses its signed repos without a local allowlist',()=>fixture('codex',async f=>{
+  f.job.protocolVersion=3;f.job.projectId='project-fixture';f.signJob();
   f.config.repos=[];
   const readinessFor=(config)=>inspectReadiness(config,(exe,args,options)=>command(exe,exe==='git'?['ls-remote','--exit-code',f.source,'HEAD']:args,options));
   await f.run({readinessFor});
@@ -309,14 +328,14 @@ test('integration: v2 job uses its signed repos without a local allowlist',()=>f
 test('integration: local profile worktree/model preserve source checkout and cancellation cleanup',()=>fixture('codex',async f=>{
   await git(['-C',f.source,'remote','add','origin','https://github.com/owner/repo.git']);
   await writeFile(paths().profiles,JSON.stringify({[`${f.config.workspaceId}:${f.job.agentId}`]:{model:'fixture-model',directories:{'owner/repo':f.source}}}));
-  f.job.protocolVersion=2;f.job.projectId='project-fixture';f.signJob();
+  f.job.protocolVersion=3;f.job.projectId='project-fixture';f.signJob();
   f.settings.slow=true;await f.updateSettings();f.control.cancelWhenRunning=true;
   await f.run();
   const trace=JSON.parse(await readFile(f.trace,'utf8'));
   assert.equal(trace.args[trace.args.indexOf('--model')+1],'fixture-model');
   assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.outcome,'canceled');
   assert.equal(await readFile(join(f.source,'source.txt'),'utf8'),'original');
-  assert.equal((await git(['-C',f.source,'worktree','list','--porcelain'])).split('worktree ').length-1,1);
+  assert.equal((await git(['-C',f.source,'worktree','list','--porcelain'])).split('worktree ').length-1,2);
 }));
 
 test('integration: profile origins reject lookalike hosts, foreign repos and unauthorized context',()=>fixture('codex', async f => {
@@ -341,7 +360,7 @@ test('integration: CLI init, pairing and diagnose need no per-agent repo configu
   const after=JSON.parse(await readFile(join(home,'config.json'),'utf8'));
   assert.equal(after.signingPublicKey,before.signingPublicKey);assert.deepEqual(after.repos,[]);
   const readiness=JSON.parse(await run(['diagnose']));
-  assert.equal(readiness.jobProtocolVersion,2);assert.deepEqual(readiness.repositories,[]);
+  assert.equal(readiness.jobProtocolVersion,3);assert.deepEqual(readiness.repositories,[]);
 }));
 
 for (const kind of ['codex','claude']) test(`integration: ${kind} QA access denial stops before provider execution and criteria`,()=>fixture(kind,async f=>{
@@ -351,3 +370,25 @@ for (const kind of ['codex','claude']) test(`integration: ${kind} QA access deni
   assert.equal(f.calls.find(c=>c.path==='/pulseRunnerComplete').body.failure.phase,'prepare-worktrees');
   assert.equal(f.calls.some(c=>c.path.includes('submit_review')),false);
 }));
+
+
+test('integration: publication failure retains commits and retry does not run the agent',()=>fixture('codex',async f=>{
+  f.settings.publish=true; await f.updateSettings();
+  let publishCalls=0;
+  await f.run({publicationDeps:{appGit:async()=>{publishCalls++;throw new Error('fixture push denied');}}});
+  const completion=f.calls.find(c=>c.path==='/pulseRunnerComplete').body;
+  assert.equal(completion.outcome,'failed');assert.equal(completion.publication.execution,'completed');
+  assert.equal(completion.publication.repositories[0].stage,'pending');
+  assert.equal(await exists(join(paths().worktrees,f.job.id)),false);
+  const manifest=JSON.parse(await readFile(join(paths().root,'publications',`${f.job.id}.json`),'utf8'));
+  const entry=manifest.repositories[0];
+  assert.equal(await git(['--git-dir',entry.storage,'rev-parse',entry.recoveryRef]),entry.sha);
+  const previousTrace=await readFile(f.trace,'utf8');
+  f.calls.length=0;f.job.recoveryOf=f.job.id;f.job.id='rjob-retry';
+  f.job.publicationTargets=[...f.job.publicationTargets.map(t=>({...t,sha:entry.sha}))];f.signJob();
+  await f.run();
+  assert.equal(await readFile(f.trace,'utf8'),previousTrace);
+  const retry=f.calls.find(c=>c.path==='/pulseRunnerComplete').body;
+  assert.equal(retry.outcome,'completed');assert.equal(retry.publication.repositories[0].sha,entry.sha);
+  assert.equal(retry.publication.repositories[0].stage,'linked');assert.equal(publishCalls,1);
+}));

package/test/publication.test.js

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {mkdtemp,writeFile,readFile,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {command} from '../src/process.js';
+import {paths} from '../src/config.js';
+import {preparePublication,resumePublication,publishManifest} from '../src/publication.js';
+async function git(args) {const r=await command('git',args);assert.equal(r.code,0,r.output);return r.output.trim();}
+test('partial multi-repo publication reconciles push/PR/link and preserves exact commits across restart',async()=>{
+  const root=await mkdtemp(join(tmpdir(),'pulse-publication-'));const saved=process.env.PULSE_RUNNER_HOME;process.env.PULSE_RUNNER_HOME=join(root,'runner');
+  try {
+    const targets=['owner/app','owner/backend'].map(repo=>({repo,branch:'pul/rjob-original',base:'main',appId:'1',installationId:'2',slug:'local-app'}));
+    const job={id:'rjob-original',protocolVersion:3,projectId:'project-1',workspaceId:'ws',runnerId:'runner',issueId:'issue',publicationTargets:targets};
+    const checkouts=[];
+    for(const target of targets) {
+      const source=join(root,target.repo.split('/')[1]);await git(['init','--initial-branch=main',source]);
+      await writeFile(join(source,'file.txt'),'base');await git(['-C',source,'add','.']);await git(['-C',source,'-c','user.name=Fixture','-c','user.email=fixture@example.invalid','commit','-m','base']);
+      const baseCommit=await git(['-C',source,'rev-parse','HEAD']);await git(['-C',source,'switch','-c',target.branch]);
+      await writeFile(join(source,'file.txt'),'changed');await git(['-C',source,'add','.']);await git(['-C',source,'-c','user.name=Fixture','-c','user.email=fixture@example.invalid','commit','-m','change']);
+      checkouts.push({repo:target.repo,worktree:source,sourceDirectory:source,baseCommit});
+    }
+    const manifest=await preparePublication(job,checkouts);
+    const refs=new Map(),prs=new Map();let pushes=0,created=0,links=0,denyLink=true;
+    const authorizeRepo=async(_config,projectId,repo)=>({identity:{projectId,repo,appId:'1',installationId:'2',slug:'local-app'},base:'main',token:'secret-sentinel',api:async(path,opts)=>{
+      if(path.includes('/git/ref/')) {if(refs.has(repo)) return {object:{sha:refs.get(repo)}};throw Object.assign(new Error('missing'),{status:404});}
+      if(!opts) return prs.has(repo)?[prs.get(repo)]:[];
+      created++;const pr={number:created,state:'open',draft:true,html_url:`https://github.com/${repo}/pull/${created}`,head:{sha:refs.get(repo),ref:targets[0].branch,repo:{full_name:repo}},base:{ref:'main',repo:{full_name:repo}}};prs.set(repo,pr);return pr;
+    }});
+    const appGit=async(_grant,repo,args)=>{pushes++;refs.set(repo,args.at(-1).split(':')[0]);};
+    const remote=async(_config,path,body)=>{assert.equal(path,'pulseRunnerLinkPr');links++;if(denyLink&&body.repo==='owner/backend')throw new Error('Pulse unavailable');};
+    const first=await publishManifest({},job,manifest,async()=>{},remote,null,{authorizeRepo,appGit});
+    assert.equal(first.failed.length,1);assert.equal(first.failed[0].phase,'link-pull-request');assert.equal(pushes,2);assert.equal(created,2);
+    assert(!JSON.stringify(manifest).includes('secret-sentinel'));
+    for(const entry of manifest.repositories) assert.equal(await git(['-C',entry.storage,'rev-parse',entry.recoveryRef]),entry.sha);
+    const retry={...job,id:'rjob-retry',recoveryOf:job.id,publicationTargets:manifest.repositories.map(e=>({...targets.find(t=>t.repo===e.repo),sha:e.sha}))};
+    denyLink=false;const recovered=await resumePublication(retry);
+    const second=await publishManifest({},retry,recovered,async()=>{},remote,null,{authorizeRepo,appGit});
+    assert.equal(second.failed.length,0);assert.equal(pushes,2,'push should not repeat');assert.equal(created,2,'PR should not duplicate');assert.equal(links,4);
+    assert(recovered.repositories.every(e=>e.stage==='linked'));
+    const durable=JSON.parse(await readFile(join(paths().root,'publications','rjob-retry.json'),'utf8'));assert.equal(durable.repositories[0].sha,manifest.repositories[0].sha);
+    refs.set('owner/backend','b'.repeat(40));const divergent=await publishManifest({},retry,recovered,async()=>{},remote,null,{authorizeRepo,appGit});
+    assert.equal(divergent.failed.length,1);assert.match(divergent.failed[0].error,/diverged/);assert.equal(pushes,2);
+  } finally {if(saved===undefined)delete process.env.PULSE_RUNNER_HOME;else process.env.PULSE_RUNNER_HOME=saved;await rm(root,{recursive:true,force:true});}
+});

package/test/readiness.test.js

@@ -2,7 +2,7 @@ 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 job = { agentId: 'agent-1', repoFullName: 'owner/repo', mode: 'task', protocolVersion: 3 };
 const agent = { kind: 'codex', role: 'dev' };
 test('readiness uses native status commands and reports only booleans', async () => {
   const calls = [];