@juangcarmona/lighthouse-sdlc 0.13.0 → 0.14.0

package/src/proposal-review.mjs

@@ -0,0 +1,91 @@
+import { digest } from './host-contract.mjs';
+import { proposalRoot, validateProposalFiles } from './proposal.mjs';
+
+export const feedbackKey = review => digest(`${review.number}:${review.kind}:${review.id}:${review.feedbackDigest}`);
+export const feedbackWorker = review => review && !review.approved ? 'apply-review' : undefined;
+
+export function reviewTarget(event, eventName) {
+  if (eventName === 'issue_comment' && event.issue?.pull_request) return event.issue.number;
+  if (['pull_request_review', 'pull_request_review_comment'].includes(eventName)) return event.pull_request?.number;
+  return null;
+}
+
+export function checkProposal(pr, repo, expected) {
+  const match = pr.head?.ref?.match(/^lighthouse\/propose-([1-9][0-9]*)-([a-f0-9]{12})$/);
+  const marker = pr.body?.match(/<!-- lighthouse-proposal:([a-f0-9]{64}) -->/)?.[1];
+  if (!match || !marker?.startsWith(match[2]) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned Lighthouse proposal');
+  if (expected && (pr.head.sha !== expected.head || pr.head.ref !== expected.branch || Number(match[1]) !== expected.issue || pr.base.ref !== expected.base)) throw Error('Proposal changed during review; no update published');
+  return { number: pr.number, issue: Number(match[1]), head: pr.head.sha, branch: pr.head.ref, base: pr.base.ref, url: pr.html_url };
+}
+
+export function checkImplementationPullRequest(pr, repo, expected) {
+  const match = pr.head?.ref?.match(/^lighthouse\/implement-([1-9][0-9]*)-([a-f0-9]{12})$/);
+  const marker = pr.body?.match(/<!-- lighthouse-implementation:([a-f0-9]{64}) -->/)?.[1];
+  if (!match || !marker?.startsWith(match[2]) || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.state !== 'open' || pr.merged || pr.head.repo?.full_name !== repo || pr.base.repo?.full_name !== repo) throw Error('Not an open repository-owned implementation PR');
+  if (expected && (pr.head.sha !== expected.head || pr.head.ref !== expected.branch || Number(match[1]) !== expected.issue || pr.base.ref !== expected.base)) throw Error('Implementation changed during review');
+  return { number: pr.number, issue: Number(match[1]), head: pr.head.sha, branch: pr.head.ref, base: pr.base.ref, url: pr.html_url };
+}
+
+export async function loadProposalReview(api, repo, owner, event, eventName, implementation = false) {
+  const number = reviewTarget(event, eventName);
+  if (!number) return null;
+  const pr = await api(`pulls/${number}`), target = (implementation ? checkImplementationPullRequest : checkProposal)(pr, repo);
+  const kind = eventName === 'pull_request_review' ? 'review' : eventName === 'pull_request_review_comment' ? 'inline' : 'comment';
+  const id = kind === 'review' ? event.review?.id : event.comment?.id;
+  if (!Number.isSafeInteger(id) || id < 1) throw Error('Missing feedback identity');
+  const path = kind === 'review' ? `pulls/${number}/reviews/${id}` : kind === 'inline' ? `pulls/comments/${id}` : `issues/comments/${id}`;
+  const feedback = await api(path);
+  if (feedback.user?.login !== owner || feedback.user.type === 'Bot') throw Error('Feedback is not from the repository owner');
+  if (kind === 'comment' && feedback.issue_url !== `https://api.github.com/repos/${repo}/issues/${number}` || kind === 'inline' && feedback.pull_request_url !== `https://api.github.com/repos/${repo}/pulls/${number}`) throw Error('Feedback belongs to another PR');
+  if (kind !== 'comment' && feedback.commit_id !== target.head) throw Error('Feedback targets an older proposal commit; review the current diff');
+  const approved = kind === 'review' && feedback.state?.toLowerCase() === 'approved';
+  if (kind === 'review' && !['approved', 'commented', 'changes_requested'].includes(feedback.state?.toLowerCase())) throw Error('Review is not submitted feedback');
+  const inline = kind === 'review' ? await api(`pulls/${number}/reviews/${id}/comments?per_page=100`) : [];
+  if (inline.length >= 100) throw Error('Review exceeds bounded feedback collection');
+  const body = [feedback.body, ...inline.map(c => `${c.path}:${c.line ?? c.original_line}\n${c.body}`)].filter(Boolean).join('\n\n');
+  if (!approved && !body.trim()) throw Error('No review feedback to apply');
+  return { ...target, kind, id, path, feedback: body, feedbackDigest: digest(JSON.stringify(feedback)), receipt: `<!-- lighthouse-review:${kind}:${id}:${digest(JSON.stringify(feedback))} -->`, url: pr.html_url, feedbackUrl: feedback.html_url, approved };
+}
+
+export async function reviewThread(api, number, owner) {
+  const messages = [];
+  for (const path of [`issues/${number}/comments`, `pulls/${number}/comments`, `pulls/${number}/reviews`]) {
+    const rows = await api(`${path}?per_page=100`);
+    if (rows.length >= 100) throw Error('Proposal discussion exceeds bounded collection');
+    for (const c of rows) if (c.user?.login === owner && c.user.type !== 'Bot' && (!c.state || ['commented', 'changes_requested'].includes(c.state.toLowerCase()))) messages.push({ id: c.id, body: c.body, path: c.path, url: c.html_url, updated: c.updated_at, submitted: c.submitted_at });
+  }
+  return messages;
+}
+
+export async function loadProposalFiles(api, review) {
+  const changed = await api(`pulls/${review.number}/files?per_page=100`);
+  const root = proposalRoot(review.issue);
+  if (changed.length >= 100 || changed.some(f => !f.filename.startsWith(`${root}/`) || f.status === 'removed' || f.status === 'renamed')) throw Error('Proposal PR includes changes outside the proposal');
+  const files = [];
+  for (const f of changed) {
+    if (f.filename === `${root}/.openspec.yaml`) continue;
+    const value = await api(`contents/${f.filename}?ref=${review.head}`);
+    if (value.type !== 'file' || value.encoding !== 'base64' || value.size > 96000) throw Error('Unsupported proposal file');
+    files.push({ path: f.filename, content: Buffer.from(value.content, 'base64').toString('utf8') });
+  }
+  return validateProposalFiles(files, review.issue);
+}
+
+export async function checkReviewCurrent(api, repo, review, implementation = false) {
+  (implementation ? checkImplementationPullRequest : checkProposal)(await api(`pulls/${review.number}`), repo, review);
+  if (digest(JSON.stringify(await api(review.path))) !== review.feedbackDigest) throw Error('Review feedback changed; no update published');
+}
+
+export async function updateProposal(api, repo, snapshot, files, beforeWrite) {
+  const review = snapshot.proposalReview;
+  const commit = await api(`git/commits/${review.head}`);
+  const old = await loadProposalFiles(api, review);
+  const removed = old.filter(f => !files.some(n => n.path === f.path)).map(f => ({ path: f.path, mode: '100644', type: 'blob', sha: null }));
+  const tree = await api('git/trees', 'POST', { base_tree: commit.tree.sha, tree: [...files.map(f => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })), ...removed] });
+  const created = await api('git/commits', 'POST', { message: `docs: address proposal review for #${snapshot.issue}`, tree: tree.sha, parents: [review.head] });
+  await beforeWrite();
+  await checkReviewCurrent(api, repo, review);
+  // Non-forced update rejects a concurrent writer after the final head check.
+  await api(`git/refs/heads/${review.branch}`, 'PATCH', { sha: created.sha, force: false });
+  return { number: review.number, html_url: review.url };
+}

package/src/proposal.mjs

@@ -1,3 +1,4 @@
+import { loadDispatch, checkDispatchClaim } from './stage-dispatch.mjs';
 import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -54,14 +55,13 @@ export async function prepareProposal(issue, files, provider = openspec) {
   } finally { await rm(dir, { recursive: true, force: true }); }
 }
 
-export function checkRefinement(predecessor, envelope, run, current, marker) {
-  if (run.status !== 'completed' || run.conclusion !== 'success' || run.event !== 'issues' && run.event !== 'issue_comment' && run.event !== 'workflow_dispatch' || run.path !== '.github/workflows/lighthouse-sdlc-router.yml' || run.actor?.login !== current.owner) throw Error('Predecessor is not a successful owner workflow');
-  if (String(run.id) !== String(predecessor.workflowRunId) || run.head_sha !== predecessor.sourceRevision || predecessor.stage !== 'refine' || predecessor.issue !== current.issue || envelope.result?.stage !== 'refine' || envelope.result?.status !== 'passed' || envelope.result?.gate !== 'ready' || envelope.result?.runId !== predecessor.runId || marker !== predecessor.runId) throw Error('Refinement evidence identity mismatch');
+export function checkRefinement(predecessor, envelope, run, current, marker, dispatched = false) {
+  if (run.status !== 'completed' || run.conclusion !== 'success' || (dispatched ? run.path !== '.github/workflows/lighthouse-sdlc-refine.lock.yml' : run.event !== 'issues' && run.event !== 'issue_comment' && run.event !== 'workflow_dispatch' || run.path !== '.github/workflows/lighthouse-sdlc-router.yml' || run.actor?.login !== current.owner)) throw Error('Predecessor is not a successful owner workflow');
+  if (String(run.id) !== String(predecessor.workflowRunId) || run.head_sha !== (dispatched ? predecessor.workflowRevision : predecessor.sourceRevision) || predecessor.stage !== 'refine' || predecessor.issue !== current.issue || envelope.result?.stage !== 'refine' || envelope.result?.status !== 'passed' || envelope.result?.gate !== 'ready' || envelope.result?.runId !== predecessor.runId || marker !== predecessor.runId) throw Error('Refinement evidence identity mismatch');
   if (predecessor.sourceRevision !== current.sourceRevision || predecessor.taskDigest !== current.taskDigest) throw Error('Refinement is stale; run refine against the current source and owner intent first');
 }
 
-export async function loadRefinement(api, repo, reports, current) {
-  const report = [...reports].reverse().find(c => c.user.login === 'github-actions[bot]' && /<!-- lighthouse-actions:[a-f0-9]{64} -->/.test(c.body));
+export async function loadStageReport(api, repo, report, current) {
   const marker = report?.body.match(/<!-- lighthouse-actions:([a-f0-9]{64}) -->/)?.[1];
   const runId = report?.body.match(/\[Workflow run\]\(https:\/\/github\.com\/[^/]+\/[^/]+\/actions\/runs\/(\d+)\)/)?.[1];
   if (!marker || !runId) throw Error('No authenticated refinement report; run refine first');
@@ -71,18 +71,32 @@ export async function loadRefinement(api, repo, reports, current) {
   try {
     const values = {};
     for (const [kind, file] of [['input', 'request.json'], ['result', 'envelope.json']]) {
-      const artifact = artifacts.artifacts.find(a => a.name === `lighthouse-${kind}-${current.issue}-${run.run_attempt}` && !a.expired);
+      const artifact = artifacts.artifacts.find(a => a.name === `lighthouse-${/<!-- lighthouse-stage:implement:/.test(report.body) ? 'implement-' : ''}${kind}-${current.issue}-${run.run_attempt}` && !a.expired);
       if (!artifact || artifact.size_in_bytes > 2 * 1024 * 1024) throw Error('Refinement artifact unavailable or too large; run refine first');
       const archive = join(dir, `${kind}.zip`);
       const bytes = execFileSync('gh', ['api', `repos/${repo}/actions/artifacts/${artifact.id}/zip`], { maxBuffer: 2 * 1024 * 1024, timeout: 30000 });
       await writeFile(archive, bytes);
       values[kind] = JSON.parse(execFileSync('python3', ['-c', 'import sys,zipfile; z=zipfile.ZipFile(sys.argv[1]); matches=[i for i in z.infolist() if i.filename==sys.argv[2]]; assert len(matches)==1 and matches[0].file_size<=128000, "Invalid artifact member"; data=z.open(matches[0]).read(128001); assert len(data)<=128000; sys.stdout.buffer.write(data)', archive, file], { encoding: 'utf8', maxBuffer: 128000, timeout: 10000 }));
     }
-    checkRefinement(values.input, values.result, run, current, marker);
-    return { request: values.input, envelope: values.result, report: report.html_url };
+    const request = values.input;
+    if (request.dispatch) {
+      if (!['refine', 'propose', 'implement'].includes(request.stage) || !report.body.includes(`<!-- lighthouse-stage:${request.stage}:`)) throw Error('Unexpected dispatched stage');
+      const dispatch = await loadDispatch(api, repo, current.owner, current.issue, request.dispatch.commentId, run);
+      if (dispatch.request.stage !== request.stage || dispatch.request.id !== request.dispatch.requestId || dispatch.request.sourceRevision !== request.sourceRevision || dispatch.request.workflowRevision !== request.workflowRevision) throw Error('Dispatched report identity mismatch');
+      await checkDispatchClaim(api, repo, current.issue, request.dispatch, run.id);
+    } else if (!['issues', 'issue_comment', 'workflow_dispatch'].includes(run.event) || run.path !== '.github/workflows/lighthouse-sdlc-router.yml' || run.actor?.login !== current.owner || run.head_sha !== request.sourceRevision) throw Error('Stage report identity mismatch');
+    if (run.status !== 'completed' || run.conclusion !== 'success' || String(run.id) !== String(request.workflowRunId) || request.issue !== current.issue || marker !== request.runId) throw Error('Stage report identity mismatch');
+    return { request: values.input, envelope: values.result, report: report.html_url, run, marker };
   } finally { await rm(dir, { recursive: true, force: true }); }
 }
 
+export async function loadRefinement(api, repo, reports, current) {
+  const report = [...reports].reverse().find(c => c.user.login === 'github-actions[bot]' && (/<!-- lighthouse-stage:refine:passed -->/.test(c.body) || /^## Refinement:/m.test(c.body)) && /<!-- lighthouse-actions:[a-f0-9]{64} -->/.test(c.body));
+  const evidence = await loadStageReport(api, repo, report, current);
+  checkRefinement(evidence.request, evidence.envelope, evidence.run, current, evidence.marker, !!evidence.request.dispatch);
+  return { request: evidence.request, envelope: evidence.envelope, report: evidence.report };
+}
+
 export async function createProposalPullRequest(api, snapshot, files, body, runUrl, beforeWrite) {
   const branch = `lighthouse/propose-${snapshot.issue}-${snapshot.runId.slice(0, 12)}`;
   // A fresh immutable branch per run avoids updating a human's or another run's work.

package/src/stage-dispatch.mjs

@@ -0,0 +1,148 @@
+import { digest } from './host-contract.mjs';
+import { readActionsJson } from './actions-artifact.mjs';
+
+const routerPath = '.github/workflows/lighthouse-sdlc-router.yml';
+export const stages = ['refine', 'propose', 'implement', 'integrate', 'review'];
+export const workers = [...stages, 'apply-review'];
+export const workerFor = request => request.worker ?? request.stage ?? 'implement';
+export const stagePath = stage => { if (!workers.includes(stage)) throw Error('Unknown dispatch worker'); return `.github/workflows/lighthouse-sdlc-${stage}.lock.yml`; };
+export const implementPath = stagePath('implement');
+export const statusText = (stage, status) => `${({ requested: '📥 Requested', running: '▶️ Execution admitted', completed: '✅ Completed', waiting: '⏸️ Waiting for your response', failed: '❌ Failed or cancelled' })[status]} · ${stage}`;
+const positive = value => /^[1-9][0-9]*$/.test(String(value));
+const sha = value => /^[a-f0-9]{40}$/.test(value ?? '');
+const hash = value => /^[a-f0-9]{64}$/.test(value ?? '');
+export const dispatchId = (repository, runId, stage = 'implement') => digest(`${repository}:${runId}:${stage}`);
+export const receiptId = (repository, receipt) => receipt.recovery ? digest(`${repository}:${receipt.recovery.rootId}:retry:${receipt.recovery.attempt}`) : dispatchId(repository, receipt.feedbackKey ?? receipt.eventRunId ?? receipt.routerRunId, receipt.stage ?? 'implement');
+export const dispatchArtifact = request => `lighthouse-dispatch-${request.id}`;
+
+export function readDispatchReceipt(comment, repository, issue) {
+  if (comment?.user?.login !== 'github-actions[bot]' || comment.user.type !== 'Bot' || comment.issue_url !== `https://api.github.com/repos/${repository}/issues/${issue}`) throw Error('Untrusted dispatch receipt');
+  const matches = [...comment.body.matchAll(/<!-- lighthouse-dispatch:(\{[^\n]*\}) -->/g)];
+  if (matches.length !== 1) throw Error('Missing or ambiguous dispatch receipt');
+  const receipt = JSON.parse(matches[0][1]);
+  if (receipt.recovery && (!hash(receipt.recovery.rootId) || !positive(receipt.recovery.previousComment) || !Number.isSafeInteger(receipt.recovery.attempt) || receipt.recovery.attempt < 1 || receipt.recovery.attempt > 2)) throw Error('Invalid recovery receipt');
+  if (receipt.schemaVersion !== 1 || !hash(receipt.id) || !hash(receipt.digest) || !positive(receipt.routerRunId) || !positive(receipt.routerAttempt) || !stages.includes(receipt.stage ?? 'implement') || !workers.includes(workerFor(receipt)) || (receipt.feedbackKey !== undefined && !hash(receipt.feedbackKey)) || (receipt.eventRunId !== undefined && !positive(receipt.eventRunId)) || receipt.id !== receiptId(repository, receipt) || (receipt.workerRunId !== null && !positive(receipt.workerRunId))) throw Error('Invalid dispatch receipt');
+  return receipt;
+}
+
+export function dispatchReceiptBody(repository, receipt) {
+  const root = `https://github.com/${repository}/actions/runs/`;
+  const heading = statusText(workerFor(receipt), receipt.status ?? (receipt.workerRunId ? 'running' : 'requested'));
+  const status = receipt.workerRunId ? `[Execution](${root}${receipt.workerRunId}). Open the execution for its current status and result.` : 'Execution requested; execution is not yet confirmed. Do not resend while confirmation is pending.';
+  const recovery = receipt.recovery ? `\n\nRetry ${receipt.recovery.attempt}/2 · [Previous request](https://github.com/${repository}/issues/${receipt.issue ?? ''}#issuecomment-${receipt.recovery.previousComment})` : '';
+  return `${heading}\n\n${status}${recovery}\n\n[Dispatch origin](${root}${receipt.routerRunId})\n\n<!-- lighthouse-dispatch:${JSON.stringify(receipt)} -->`;
+}
+
+export async function issueComments(api, issue) {
+  const all = [];
+  for (let page = 1; page <= 10; page++) {
+    const batch = await api(`issues/${issue}/comments?per_page=100&page=${page}`);
+    all.push(...batch);
+    if (batch.length < 100) return all;
+  }
+  throw Error('Comment history exceeds bounded intake');
+}
+
+// The router dispatch job serializes receipt creation per issue. Workers acquire
+// the existing issue concurrency group before claiming a receipt.
+export async function recordDispatch(api, repository, request) {
+  if (Buffer.byteLength(JSON.stringify(request)) > 128000) throw Error('Dispatch request exceeds its artifact bound');
+  const comments = await issueComments(api, request.issue);
+  for (const comment of comments) {
+    if (comment.user?.login !== 'github-actions[bot]' || !comment.body.includes('<!-- lighthouse-dispatch:')) continue;
+    const receipt = readDispatchReceipt(comment, repository, request.issue);
+    if (receipt.id === request.id) return { send: false, comment, receipt };
+    if (!receipt.workerRunId) throw Error('An earlier stage dispatch is unconfirmed; reconcile it before requesting another');
+    const run = await api(`actions/runs/${receipt.workerRunId}`);
+    if (run.path !== stagePath(workerFor(receipt)) || run.status !== 'completed' && request.queue !== true) throw Error('A stage execution is still pending or running');
+  }
+  const receipt = { schemaVersion: 1, stage: request.stage, ...(request.recovery ? { recovery: request.recovery, issue: request.issue } : {}), ...(request.worker ? { worker: request.worker } : {}), ...(request.feedbackKey ? { feedbackKey: request.feedbackKey } : {}), status: 'requested', ...(request.eventRunId ? { eventRunId: request.eventRunId } : {}), id: request.id, digest: digest(JSON.stringify(request)), routerRunId: request.routerRunId, routerAttempt: request.routerAttempt, workerRunId: null };
+  const comment = await api(`issues/${request.issue}/comments`, 'POST', { body: dispatchReceiptBody(repository, receipt) });
+  return { send: true, comment, receipt };
+}
+
+export async function sendDispatch(api, repository, request, commentId) {
+  const receipt = readDispatchReceipt(await api(`issues/comments/${commentId}`), repository, request.issue);
+  if (receipt.id !== request.id || receipt.digest !== digest(JSON.stringify(request))) throw Error('Dispatch request changed');
+  if (receipt.workerRunId) return;
+  // Never retry this POST automatically: its response can be lost after admission.
+  return api(`actions/workflows/lighthouse-sdlc-${workerFor(request)}.lock.yml/dispatches`, 'POST', { ref: request.ref, inputs: { issue: String(request.issue), 'dispatch-request': String(commentId) } });
+}
+
+export function verifyDispatchOrigin(request, receipt, parent, worker, repository, owner, issue) {
+  if (workerFor(request) !== workerFor(receipt) || request.feedbackKey !== receipt.feedbackKey || workerFor(request) !== request.stage && !(workerFor(request) === 'apply-review' && ['propose', 'implement'].includes(request.stage))) throw Error('Dispatch worker responsibility mismatch');
+  if (JSON.stringify(request.recovery) !== JSON.stringify(receipt.recovery)) throw Error('Recovery receipt identity mismatch');
+  const events = ['issues', 'issue_comment', 'pull_request_review', 'pull_request_review_comment', 'workflow_dispatch', 'workflow_run'];
+  if (request.schemaVersion !== 1 || request.id !== receipt.id || request.repository !== repository || request.issue !== issue || request.stage !== (receipt.stage ?? 'implement') || !stages.includes(request.stage) || !sha(request.sourceRevision) || !sha(request.workflowRevision) || !hash(request.taskDigest) || typeof request.handoff !== 'boolean' || digest(JSON.stringify(request)) !== receipt.digest) throw Error('Dispatch artifact identity mismatch');
+  const recovery = !!request.recovery;
+  const originPath = recovery ? '.github/workflows/lighthouse-worker-maintenance.yml' : routerPath;
+  const originEvent = recovery ? request.routerEventName : request.eventName;
+  if (String(parent.id) !== String(receipt.routerRunId) || parent.run_attempt !== receipt.routerAttempt || request.routerRunId !== receipt.routerRunId || request.routerAttempt !== receipt.routerAttempt || parent.path !== originPath || (parent.event !== 'workflow_run' && (parent.actor?.login !== owner || parent.triggering_actor?.login !== owner)) || !(recovery ? ['schedule', 'workflow_dispatch'] : events).includes(parent.event) || parent.event !== originEvent || parent.head_sha !== (request.routerRevision ?? request.workflowRevision) || parent.head_branch !== (request.routerRef ?? request.ref) || parent.repository?.full_name !== repository) throw Error('Dispatch origin is not an authorized router execution');
+  const eventRunId = request.eventName === 'workflow_run' ? request.event?.workflow_run?.id : request.event?.inputs?.after_run;
+  if (String(eventRunId ?? '') !== String(receipt.eventRunId ?? '') || String(request.eventRunId ?? '') !== String(receipt.eventRunId ?? '')) throw Error('Completion event identity mismatch');
+  if (worker.path !== stagePath(workerFor(request)) || worker.event !== 'workflow_dispatch' || worker.head_sha !== request.workflowRevision || worker.head_branch !== request.ref || worker.repository?.full_name !== repository || ![owner, 'github-actions[bot]'].includes(worker.actor?.login) || ![owner, 'github-actions[bot]'].includes(worker.triggering_actor?.login)) throw Error('Dispatch worker identity mismatch');
+}
+
+export async function loadDispatch(api, repository, owner, issue, commentId, worker, readArtifact = readActionsJson, depth = 0) {
+  if (depth > 2) throw Error('Recovery chain exceeds its bound');
+  if (!positive(commentId)) throw Error('Invalid dispatch receipt identifier');
+  const comment = await api(`issues/comments/${commentId}`);
+  const receipt = readDispatchReceipt(comment, repository, issue);
+  const parent = await api(`actions/runs/${receipt.routerRunId}/attempts/${receipt.routerAttempt}`);
+  const request = await readArtifact(api, repository, receipt.routerRunId, dispatchArtifact(receipt), 'dispatch.json');
+  verifyDispatchOrigin(request, receipt, parent, worker, repository, owner, issue);
+  const dispatch = { request, receipt, commentId: Number(commentId) };
+  if (request.recovery) await (await import('./worker-recovery.mjs')).verifyRecoveryOrigin(api, repository, owner, dispatch, parent, readArtifact, depth);
+  return dispatch;
+}
+
+export async function claimDispatch(api, repository, dispatch, workerId) {
+  const fresh = readDispatchReceipt(await api(`issues/comments/${dispatch.commentId}`), repository, dispatch.request.issue);
+  if (fresh.id !== dispatch.receipt.id || fresh.digest !== dispatch.receipt.digest) throw Error('Dispatch receipt changed before admission');
+  if (fresh.workerRunId) return false;
+  fresh.workerRunId = String(workerId); fresh.status = 'running';
+  await api(`issues/comments/${dispatch.commentId}`, 'PATCH', { body: dispatchReceiptBody(repository, fresh) });
+  dispatch.receipt = fresh;
+  return true;
+}
+
+export async function checkDispatchClaim(api, repository, issue, dispatch, workerId) {
+  const receipt = readDispatchReceipt(await api(`issues/comments/${dispatch.commentId}`), repository, issue);
+  if (receipt.id !== dispatch.requestId || receipt.digest !== dispatch.digest || String(receipt.workerRunId) !== String(workerId)) throw Error('Dispatch admission receipt revoked or changed');
+}
+
+
+// Every dispatched worker shares the literal issue concurrency key before this call.
+export async function admitDispatch(api, repository, owner, env, event) {
+  const issue = Number(env.LIGHTHOUSE_ISSUE);
+  if (!Number.isSafeInteger(issue) || issue < 1 || String(issue) !== env.LIGHTHOUSE_ISSUE) throw Error('Dispatch issue must be a canonical positive integer');
+  const worker = await api(`actions/runs/${env.GITHUB_RUN_ID}/attempts/${env.GITHUB_RUN_ATTEMPT}`);
+  const dispatch = await loadDispatch(api, repository, owner, issue, event.inputs?.['dispatch-request'], worker);
+  if (env.LIGHTHOUSE_WORKER ? workerFor(dispatch.request) !== env.LIGHTHOUSE_WORKER : dispatch.request.stage !== env.LIGHTHOUSE_STAGE) throw Error('Dispatch targets a different stage or worker');
+  if (dispatch.request.recovery) {
+    if (env.LIGHTHOUSE_RECOVERY_ENABLED !== 'true') throw Error('Automatic recovery has been disabled');
+    const parent = await api(`actions/runs/${dispatch.receipt.routerRunId}/attempts/${dispatch.receipt.routerAttempt}`);
+    await (await import('./worker-recovery.mjs')).verifyRecoveryOrigin(api, repository, owner, dispatch, parent, readActionsJson, 0, true);
+  }
+  const admitted = await claimDispatch(api, repository, dispatch, env.GITHUB_RUN_ID);
+  return { ...dispatch, admitted };
+}
+
+export async function finishDispatch(api, repository, issue, commentId, workerId, outcome) {
+  if (!positive(commentId)) return;
+  const receipt = readDispatchReceipt(await api(`issues/comments/${commentId}`), repository, issue);
+  if (String(receipt.workerRunId) !== String(workerId)) return;
+  receipt.status = outcome === 'passed' ? 'completed' : outcome === 'blocked' ? 'waiting' : 'failed';
+  await api(`issues/comments/${commentId}`, 'PATCH', { body: dispatchReceiptBody(repository, receipt) });
+}
+
+// An owner can replay a completed run on a reviewed workflow branch for acceptance.
+// Automated events and manual replays use the same fresh GitHub observation.
+export async function completedEvent(api, event, env) {
+  if (env.GITHUB_EVENT_NAME === 'workflow_run') return event;
+  const id = event.inputs?.after_run;
+  if (!id) return null;
+  if (env.GITHUB_EVENT_NAME !== 'workflow_dispatch' || env.GITHUB_ACTOR !== env.GITHUB_REPOSITORY_OWNER || env.GITHUB_TRIGGERING_ACTOR !== env.GITHUB_REPOSITORY_OWNER || !positive(id)) throw Error('Completion replay requires an owner and a run ID');
+  const run = await api(`actions/runs/${id}`);
+  return { action: 'completed', workflow_run: { id: run.id, head_sha: run.head_sha } };
+}

package/src/stage-transition.mjs

@@ -0,0 +1,25 @@
+import { readActionsJson } from './actions-artifact.mjs';
+import { loadDispatch, checkDispatchClaim, stagePath, issueComments } from './stage-dispatch.mjs';
+import { validateStageEnvelope } from './host-contract.mjs';
+
+// The completed execution is an observation. Its retained owner request grants the handoff.
+export async function refinementAfterRun(api, repository, owner, event, readArtifact = readActionsJson) {
+  if (event.action !== 'completed' || !Number.isSafeInteger(event.workflow_run?.id)) return null;
+  const run = await api(`actions/runs/${event.workflow_run.id}`);
+  if (run.path !== stagePath('refine') || run.status !== 'completed' || run.conclusion !== 'success' || run.head_sha !== event.workflow_run.head_sha) return null;
+  const artifacts = await api(`actions/runs/${run.id}/artifacts?per_page=100`);
+  if (artifacts.total_count > 100) throw Error('Refinement artifacts exceed bounds');
+  const inputs = artifacts.artifacts.filter(a => new RegExp(`^lighthouse-input-[1-9][0-9]*-${run.run_attempt}$`).test(a.name) && !a.expired);
+  if (inputs.length !== 1) return null; // Duplicate/no-op executions have no stage input.
+  const request = await readArtifact(api, repository, run.id, inputs[0].name, 'request.json');
+  if (request.stage !== 'refine' || !request.dispatch || !request.autoImplement || String(request.workflowRunId) !== String(run.id)) return null;
+  const origin = await loadDispatch(api, repository, owner, request.issue, request.dispatch.commentId, run, readArtifact);
+  if (origin.request.stage !== 'refine' || origin.request.autoImplement !== true || origin.request.id !== request.dispatch.requestId || origin.request.sourceRevision !== request.sourceRevision || origin.request.workflowRevision !== request.workflowRevision) throw Error('Refinement continuation identity mismatch');
+  await checkDispatchClaim(api, repository, request.issue, request.dispatch, run.id);
+  const envelope = await readArtifact(api, repository, run.id, `lighthouse-result-${request.issue}-${run.run_attempt}`, 'envelope.json');
+  if (validateStageEnvelope(envelope, request).length) throw Error('Invalid refinement result');
+  if (envelope.result.status !== 'passed' || envelope.result.gate !== 'ready') return null;
+  const reports = await issueComments(api, request.issue);
+  if (!reports.some(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && c.body.includes(`<!-- lighthouse-actions:${request.runId} -->`) && c.body.includes('<!-- lighthouse-stage:refine:passed -->'))) return null;
+  return { run: true, stage: 'implement', issue: request.issue, predecessor: { runId: String(run.id), attempt: run.run_attempt }, reason: 'Verified refinement completed; implementation requested by the installed policy.' };
+}

package/src/worker-maintenance.mjs

@@ -0,0 +1,83 @@
+import { readFile, writeFile, mkdir, appendFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { dispatchArtifact, sendDispatch } from './stage-dispatch.mjs';
+import { maintenancePath, prepareRecovery } from './worker-recovery.mjs';
+import { publishReports } from './worker-reports.mjs';
+
+export async function ownerIssues(api, owner) {
+  const issues = [];
+  for (let page = 1; page <= 5; page++) {
+    const rows = await api(`issues?state=open&per_page=100&page=${page}`);
+    issues.push(...rows.filter(i => !i.pull_request && i.user?.login === owner).map(i => i.number));
+    if (rows.length < 100) {
+      if (issues.length > 100) throw Error('Maintenance exceeds 100 open owner issues');
+      return issues;
+    }
+  }
+  throw Error('Issue inventory exceeds maintenance bounds');
+}
+
+async function main(command) {
+  const env = process.env, repository = env.GITHUB_REPOSITORY, owner = env.GITHUB_REPOSITORY_OWNER;
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository ?? '')) throw Error('Invalid repository');
+  const api = async (path, method = 'GET', body) => {
+    const response = await fetch(`https://api.github.com/repos/${repository}${path ? '/' + path : ''}`, { method, headers: { authorization: `Bearer ${env.GH_TOKEN}`, accept: 'application/vnd.github+json', 'content-type': 'application/json' }, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(30000) });
+    if (!response.ok) throw Error(`GitHub ${method} ${path}: ${response.status}`);
+    return response.status === 204 ? null : response.json();
+  };
+  const output = async (name, value) => { if (env.GITHUB_OUTPUT) await appendFile(env.GITHUB_OUTPUT, `${name}=${value}\n`); };
+  const parent = await api(`actions/runs/${env.GITHUB_RUN_ID}/attempts/${env.GITHUB_RUN_ATTEMPT}`);
+  if (parent.path !== maintenancePath || parent.repository?.full_name !== repository || !['schedule', 'workflow_dispatch'].includes(parent.event) || parent.actor?.login !== owner || parent.triggering_actor?.login !== owner) throw Error('Maintenance is not an authorized execution');
+  if (env.LIGHTHOUSE_MAINTENANCE_ENABLED !== 'true') throw Error('Maintenance is not enabled');
+  if (command === 'report') {
+    const root = join(env.RUNNER_TEMP, 'worker-observations'), observations = [], seen = [];
+    const directories = await readdir(root);
+    if (directories.length > 100) throw Error('Observation inventory exceeds bounds');
+    for (const directory of directories) {
+      const match = directory.match(/^lighthouse-maintenance-([1-9][0-9]*)$/);
+      if (!match) throw Error('Unexpected observation artifact');
+      const source = await readFile(join(root, directory, 'observations.json'), 'utf8');
+      if (Buffer.byteLength(source) > 256000) throw Error('Observation artifact exceeds bounds');
+      const rows = JSON.parse(source);
+      if (!Array.isArray(rows) || rows.some(r => r.issue !== Number(match[1]))) throw Error('Observation issue differs from its artifact');
+      observations.push(...rows); seen.push(Number(match[1]));
+    }
+    const expected = JSON.parse(env.LIGHTHOUSE_OBSERVED_ISSUES ?? '[]');
+    if (JSON.stringify(seen.sort((a, b) => a - b)) !== JSON.stringify(expected.sort((a, b) => a - b))) throw Error('Incomplete maintenance observations');
+    const reports = await publishReports(api, repository, owner, env.LIGHTHOUSE_REPORT_INDEX_ISSUE, observations);
+    if (env.GITHUB_STEP_SUMMARY) await appendFile(env.GITHUB_STEP_SUMMARY, reports.map(r => `- [Report #${r.number}](https://github.com/${repository}/issues/${r.number}): ${r.count} distinct observation(s), ${r.state}.`).join('\n') + '\n');
+    return;
+  }
+  if (command === 'scan') {
+    const event = JSON.parse(await readFile(env.GITHUB_EVENT_PATH, 'utf8'));
+    const requested = event.inputs?.issue;
+    if (requested && !/^[1-9][0-9]*$/.test(requested)) throw Error('Issue must be a canonical positive integer');
+    const issues = requested ? [Number(requested)] : await ownerIssues(api, owner);
+    await output('issues', JSON.stringify(issues)); return;
+  }
+  const issue = Number(env.LIGHTHOUSE_ISSUE);
+  if (!Number.isSafeInteger(issue) || issue < 1) throw Error('Invalid issue');
+  const dir = join(env.RUNNER_TEMP, `lighthouse-maintenance-${env.GITHUB_RUN_ID}-${issue}`);
+  if (command === 'send') {
+    if (env.LIGHTHOUSE_RECOVERY_ENABLED !== 'true') throw Error('Automatic recovery is disabled');
+    await sendDispatch(api, repository, JSON.parse(await readFile(join(dir, 'dispatch.json'), 'utf8')), env.LIGHTHOUSE_DISPATCH_COMMENT); return;
+  }
+  if (command !== 'prepare') throw Error('Unknown maintenance command');
+  await mkdir(dir, { recursive: true });
+  try {
+    const result = await prepareRecovery(api, repository, owner, issue, parent, env.LIGHTHOUSE_RECOVERY_ENABLED === 'true');
+    await writeFile(join(dir, 'observations.json'), JSON.stringify(result.observations));
+    if (env.GITHUB_STEP_SUMMARY) await appendFile(env.GITHUB_STEP_SUMMARY, result.observations.map(o => `- Issue #${o.issue}, ${o.worker}: ${o.state}. ${o.nextAction}`).join('\n') + '\n');
+    await output('send', String(!!result.request));
+    if (result.request) {
+      await writeFile(join(dir, 'dispatch.json'), JSON.stringify(result.request));
+      await output('artifact', dispatchArtifact(result.request)); await output('comment', result.commentId);
+    }
+  } catch (error) {
+    await writeFile(join(dir, 'observations.json'), JSON.stringify([{ issue, state: 'uncertain', code: 'evidence-unavailable', nextAction: 'Inspect maintenance evidence before requesting another execution.' }]));
+    throw error;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main(process.argv[2]).catch(error => { console.error(error.message); process.exitCode = 1; });

package/src/worker-recovery.mjs

@@ -0,0 +1,106 @@
+import { digest } from './host-contract.mjs';
+import { issueComments, readDispatchReceipt, loadDispatch, workerFor, stagePath, recordDispatch } from './stage-dispatch.mjs';
+import { readActionsJson } from './actions-artifact.mjs';
+
+export const maintenancePath = '.github/workflows/lighthouse-worker-maintenance.yml';
+export const retryLimit = 2;
+export const retryDelayMs = 30 * 60 * 1000;
+export const recoveryId = (repository, rootId, attempt) => digest(`${repository}:${rootId}:retry:${attempt}`);
+const identity = r => ({ issue: r.request.issue, worker: workerFor(r.request), runId: String(r.run.id), rootId: r.request.recovery?.rootId ?? r.request.id, attempt: r.request.recovery?.attempt ?? 0 });
+const ownerAnswers = comments => comments.filter(c => c.user?.login === c.owner && !c.body.includes('<!-- lighthouse-run:') && !c.body.includes('<!-- lighthouse-actions:'));
+const intent = (issue, comments, owner) => digest(JSON.stringify({ title: issue.title, body: issue.body, comments: ownerAnswers(comments.map(c => ({ ...c, owner }))).map(c => ({ id: c.id, body: c.body, updated_at: c.updated_at })) }));
+
+export function recoveryDecision({ request, receipt, run, jobs, issue, comments, owner, revision, workflowRevision, now = Date.now() }) {
+  const base = identity({ request, run });
+  const result = (state, code, nextAction, extra = {}) => ({ ...base, state, code, nextAction, ...extra });
+  if (run.status !== 'completed') {
+    const updated = Date.parse(run.updated_at);
+    if (Number.isFinite(updated) && now - updated >= 2 * 60 * 60 * 1000) return result('stalled', 'worker-stalled', 'Inspect the runner and current execution; maintenance never cancels or duplicates active work.');
+    return result('active', 'worker-active', 'Inspect the current Actions execution; do not start another.');
+  }
+  if (run.run_attempt !== 1) return result('uncertain', 'execution-rerun', 'Inspect all attempts; a rerun does not reclaim the original request.');
+  if (String(receipt.workerRunId) !== String(run.id)) return result('uncertain', 'dispatch-unconfirmed', 'Reconcile the request with the observed execution.');
+  if (receipt.status === 'waiting') return result('waiting-human', 'human-decision', 'Answer the recorded question; no automatic retry.');
+  if (receipt.status === 'completed' && run.conclusion === 'success') return result('succeeded', 'worker-completed', 'No recovery needed.');
+  if (issue.state !== 'open' || issue.user?.login !== owner || issue.pull_request || issue.labels.some(l => ['future', 'needs-info', 'waiting-review', 'human-working', 'agent-working'].includes(l.name))) return result('blocked', 'issue-paused', 'Inspect the issue decision or reservation before requesting work.');
+  if (request.sourceRevision !== revision || request.workflowRevision !== workflowRevision || request.taskDigest !== intent(issue, comments, owner)) return result('blocked', 'authority-changed', 'Request fresh work against the current source and owner intent.');
+  if (!['refine', 'propose', 'implement'].includes(request.stage) || !['failure', 'timed_out'].includes(run.conclusion)) return result('uncertain', 'manual-recovery', 'Inspect the outcome and request a new authorized execution if needed.');
+  const preparation = jobs.find(j => j.name === 'Authorize and reserve issue');
+  const publication = jobs.find(j => j.name === 'Validate, publish and release');
+  const publishStep = publication?.steps?.find(s => s.name === 'Recheck authority and publish the validated result');
+  const failedExecution = jobs.some(j => ['pre_activation', 'activation', 'agent'].includes(j.name) && ['failure', 'timed_out'].includes(j.conclusion));
+  if (preparation?.conclusion !== 'success' || !failedExecution || publishStep?.conclusion !== 'skipped') return result('uncertain', 'publication-uncertain', 'Inspect publication and remote effects before creating another request.');
+  if (base.attempt >= retryLimit) return result('exhausted', 'worker-technical-failure', 'Retry budget exhausted. Inspect the failure and make a new owner decision.');
+  const ended = Date.parse(run.updated_at);
+  if (!Number.isFinite(ended) || !Number.isFinite(now)) return result('uncertain', 'execution-time-unknown', 'Inspect the execution timestamps.');
+  const retryAt = new Date(ended + retryDelayMs).toISOString();
+  if (now < ended + retryDelayMs) return result('delayed', 'worker-technical-failure', 'Wait until the recovery delay has elapsed.', { retryAt });
+  return result('retryable', 'worker-technical-failure', 'Record one linked retry under the adopted policy.', { retryAt });
+}
+
+export async function observeDispatch(api, repository, owner, comment, issue, comments, now = Date.now(), readArtifact = readActionsJson) {
+  const receipt = readDispatchReceipt(comment, repository, issue.number);
+  if (!receipt.workerRunId) {
+    // A visible matching run helps the operator reconcile; absence is never permission to resend.
+    const found = await api(`actions/workflows/${stagePath(workerFor(receipt)).split('/').at(-1)}/runs?event=workflow_dispatch&per_page=100`);
+    const matches = found.workflow_runs.filter(r => r.display_title === `${workerFor(receipt)} #${issue.number} · request ${comment.id}`);
+    let observedRunId;
+    if (matches.length === 1 && found.total_count <= 100) {
+      const run = await api(`actions/runs/${matches[0].id}`);
+      await loadDispatch(api, repository, owner, issue.number, comment.id, run, readArtifact);
+      observedRunId = String(run.id);
+    }
+    return { issue: issue.number, worker: workerFor(receipt), rootId: receipt.recovery?.rootId ?? receipt.id, attempt: receipt.recovery?.attempt ?? 0, state: 'uncertain', code: 'dispatch-unconfirmed', nextAction: 'Inspect the request and matching Actions execution; never resend an unconfirmed dispatch.', ...(observedRunId ? { observedRunId } : {}) };
+  }
+  const run = await api(`actions/runs/${receipt.workerRunId}`);
+  const dispatch = await loadDispatch(api, repository, owner, issue.number, comment.id, run, readArtifact);
+  const jobs = await api(`actions/runs/${run.id}/attempts/${run.run_attempt}/jobs?per_page=100`);
+  if (jobs.total_count > 100) throw Error('Execution job inventory exceeds recovery bounds');
+  const repo = await api('');
+  const revision = (await api(`commits/${encodeURIComponent(repo.default_branch)}`)).sha;
+  const workflowRevision = (await api(`commits/${encodeURIComponent(dispatch.request.ref)}`)).sha;
+  return { ...recoveryDecision({ ...dispatch, run, jobs: jobs.jobs, issue, comments, owner, revision, workflowRevision, now }), dispatch };
+}
+
+// Called again by the worker, before claiming a maintenance-created retry.
+export async function verifyRecoveryOrigin(api, repository, owner, dispatch, parent, readArtifact, depth, revalidate = false) {
+  const r = dispatch.request, retry = r.recovery;
+  if (parent.path !== maintenancePath || !retry || !Number.isSafeInteger(retry.attempt) || retry.attempt < 1 || retry.attempt > retryLimit || !/^[1-9][0-9]*$/.test(String(retry.previousComment))) throw Error('Invalid recovery origin');
+  const comment = await api(`issues/comments/${retry.previousComment}`);
+  const receipt = readDispatchReceipt(comment, repository, r.issue);
+  if (!receipt.workerRunId) throw Error('Cannot recover unconfirmed dispatch');
+  const priorRun = await api(`actions/runs/${receipt.workerRunId}`);
+  const prior = await loadDispatch(api, repository, owner, r.issue, comment.id, priorRun, readArtifact, depth + 1);
+  if (retry.rootId !== (prior.request.recovery?.rootId ?? prior.request.id) || retry.attempt !== (prior.request.recovery?.attempt ?? 0) + 1) throw Error('Recovery chain or budget changed');
+  const originalFields = value => Object.fromEntries(Object.entries(value).filter(([key]) => !['id', 'routerRunId', 'routerAttempt', 'routerRevision', 'routerRef', 'routerEventName', 'recovery'].includes(key)).sort(([a], [b]) => a.localeCompare(b)));
+  if (JSON.stringify(originalFields(r)) !== JSON.stringify(originalFields(prior.request))) throw Error('Recovery changed the original authorization');
+  if (!revalidate) return;
+  const jobs = await api(`actions/runs/${priorRun.id}/attempts/${priorRun.run_attempt}/jobs?per_page=100`);
+  if (jobs.total_count > 100) throw Error('Execution job inventory exceeds recovery bounds');
+  const issue = await api(`issues/${r.issue}`), comments = await issueComments(api, r.issue), repo = await api('');
+  const revision = (await api(`commits/${encodeURIComponent(repo.default_branch)}`)).sha;
+  const workflowRevision = (await api(`commits/${encodeURIComponent(r.ref)}`)).sha;
+  const decision = recoveryDecision({ ...prior, run: priorRun, jobs: jobs.jobs, issue, comments, owner, revision, workflowRevision });
+  if (decision.state !== 'retryable') throw Error(`Recovery no longer authorized: ${decision.code}`);
+}
+
+export async function prepareRecovery(api, repository, owner, issueNumber, parent, enabled, now = Date.now(), readArtifact = readActionsJson) {
+  const issue = await api(`issues/${issueNumber}`), comments = await issueComments(api, issueNumber);
+  const entries = comments.filter(c => c.user?.login === 'github-actions[bot]' && c.body.includes('<!-- lighthouse-dispatch:')).map(comment => ({ comment, receipt: readDispatchReceipt(comment, repository, issueNumber) }));
+  const latest = new Map();
+  for (const entry of entries) latest.set(entry.receipt.recovery?.rootId ?? entry.receipt.id, entry);
+  const observations = [];
+  const currentRoot = entries.at(-1)?.receipt.recovery?.rootId ?? entries.at(-1)?.receipt.id;
+  for (const { comment } of latest.values()) {
+    const observation = await observeDispatch(api, repository, owner, comment, issue, comments, now, readArtifact);
+    const { dispatch, ...publicObservation } = observation;
+    observations.push(publicObservation);
+    if (observation.state !== 'retryable' || enabled !== true || observation.rootId !== currentRoot) continue;
+    const attempt = observation.attempt + 1;
+    const request = { ...dispatch.request, id: recoveryId(repository, observation.rootId, attempt), routerRunId: String(parent.id), routerAttempt: parent.run_attempt, routerRevision: parent.head_sha, routerRef: parent.head_branch, routerEventName: parent.event, recovery: { rootId: observation.rootId, previousComment: comment.id, attempt } };
+    const recorded = await recordDispatch(api, repository, request);
+    // One new retry per issue per maintenance execution, even if several historical roots failed.
+    return { observations, ...(recorded.send ? { request, commentId: recorded.comment.id } : {}) };
+  }
+  return { observations };
+}