@juangcarmona/lighthouse-sdlc 0.12.0 → 0.14.0

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 };
+}

package/src/worker-reports.mjs

@@ -0,0 +1,150 @@
+import { digest } from './host-contract.mjs';
+import { workers } from './stage-dispatch.mjs';
+
+export const causes = Object.freeze({
+  'worker-technical-failure': ['Technical execution failure', 'Inspect the failed step and retry budget; unresolved work needs an owner decision.'],
+  'worker-stalled': ['Execution has stopped updating', 'Inspect the runner and execution; do not duplicate active work.'],
+  'dispatch-unconfirmed': ['Dispatch confirmation is missing', 'Reconcile the recorded request with Actions before requesting more work.'],
+  'execution-rerun': ['Execution was rerun outside recovery', 'Inspect all attempts and the original claim.'],
+  'authority-changed': ['Source or owner intent changed', 'Request fresh work against the current source and intent.'],
+  'manual-recovery': ['Outcome requires operator recovery', 'Inspect actual effects and make a new owner decision.'],
+  'publication-uncertain': ['Publication effects are uncertain', 'Inspect the PR, issue and publication job before another request.'],
+  'execution-time-unknown': ['Execution timestamp is unavailable', 'Inspect the Actions execution timestamps.'],
+  'evidence-unavailable': ['Recovery evidence is unavailable', 'Inspect the maintenance run and original request artifacts.'],
+});
+const states = ['retryable', 'delayed', 'exhausted', 'uncertain', 'stalled', 'blocked', 'recovered'];
+const positive = x => Number.isSafeInteger(Number(x)) && /^[1-9][0-9]*$/.test(String(x));
+const hash = x => /^[a-f0-9]{64}$/.test(x ?? '');
+export const reportSignature = (repository, worker, code) => digest(`${repository}:${worker}:${code}`);
+const marker = 'lighthouse-worker-report';
+const indexStart = '<!-- lighthouse-worker-report-index:start -->';
+const indexEnd = '<!-- lighthouse-worker-report-index:end -->';
+
+function parseMarker(body, name) {
+  if (typeof body !== 'string' || Buffer.byteLength(body) > 128000) throw Error('Report body exceeds bounds');
+  const values = [...body.matchAll(new RegExp(`<!-- ${name}:(\\{[^\\n]*\\}) -->`, 'g'))];
+  if (values.length !== 1) throw Error('Missing or ambiguous report marker');
+  return JSON.parse(values[0][1]);
+}
+
+function validateEntry(entry) {
+  if (!positive(entry.issue) || !hash(entry.rootId) || !Number.isSafeInteger(entry.attempt) || entry.attempt < 0 || entry.attempt > 2 || !states.includes(entry.state) || (entry.runId !== null && !positive(entry.runId)) || entry.key !== (entry.runId ? `run:${entry.runId}` : `request:${entry.rootId}`)) throw Error('Invalid report occurrence');
+  if (Object.keys(entry).sort().join(',') !== 'attempt,issue,key,rootId,runId,state') throw Error('Unexpected report occurrence fields');
+}
+
+export function readReport(issue, repository, worker, code) {
+  if (issue.pull_request || issue.user?.login !== 'github-actions[bot]' || issue.user.type !== 'Bot') throw Error('Report is not bot-owned');
+  const report = parseMarker(issue.body, marker);
+  if (report.schemaVersion !== 1 || report.worker !== worker || report.code !== code || report.signature !== reportSignature(repository, worker, code) || !Array.isArray(report.entries) || report.entries.length > 200 || Object.keys(report).sort().join(',') !== 'code,entries,schemaVersion,signature,worker') throw Error('Invalid report identity');
+  report.entries.forEach(validateEntry);
+  if (new Set(report.entries.map(e => e.key)).size !== report.entries.length) throw Error('Duplicate report occurrences');
+  return report;
+}
+
+function normalizedObservation(repository, observation) {
+  if (!positive(observation.issue)) throw Error('Invalid observed issue');
+  const worker = observation.worker ?? 'maintenance';
+  if (![...workers, 'maintenance'].includes(worker)) throw Error('Unknown observed worker');
+  const rootId = observation.rootId ?? digest(`${repository}:${observation.issue}:unavailable`);
+  if (!hash(rootId)) throw Error('Invalid observed request');
+  if (observation.state === 'succeeded') return { worker, rootId, succeeded: true };
+  if (!Object.hasOwn(causes, observation.code) || !states.includes(observation.state) || observation.state === 'recovered') return null;
+  const runId = observation.runId ?? observation.observedRunId ?? null;
+  const entry = { key: runId ? `run:${runId}` : `request:${rootId}`, rootId, issue: observation.issue, runId: runId === null ? null : String(runId), attempt: observation.attempt ?? 0, state: observation.state };
+  validateEntry(entry);
+  return { worker, code: observation.code, entry };
+}
+
+export function mergeObservations(repository, previous, observations) {
+  const entries = new Map(previous.entries.map(e => [e.key, { ...e }]));
+  const recoveredRoots = new Set(previous.entries.filter(e => e.state === 'recovered').map(e => e.rootId));
+  const normalized = observations.map(o => normalizedObservation(repository, o)).filter(Boolean);
+  for (const o of normalized) if (o.worker === previous.worker && o.code === previous.code) entries.set(o.entry.key, { ...o.entry, ...(recoveredRoots.has(o.entry.rootId) ? { state: 'recovered' } : {}) });
+  for (const o of normalized) if (o.succeeded && o.worker === previous.worker) for (const entry of entries.values()) if (entry.rootId === o.rootId) entry.state = 'recovered';
+  if (entries.size > 200) throw Error('Report exceeds 200 distinct observations; operator archival is required');
+  return { ...previous, entries: [...entries.values()].sort((a, b) => a.key.localeCompare(b.key)) };
+}
+
+export function reportBody(repository, report) {
+  const active = report.entries.filter(e => e.state !== 'recovered').length;
+  const rows = report.entries.map(e => `| [#${e.issue}](https://github.com/${repository}/issues/${e.issue}) | ${e.runId ? `[Execution](https://github.com/${repository}/actions/runs/${e.runId})` : 'Unconfirmed request'} | ${e.attempt}/2 | ${e.state} |`);
+  const body = `## ${active ? '❌ Attention required' : '✅ Recovery confirmed'}\n\nWorker: \`${report.worker}\`. Cause: ${causes[report.code][0]}.\n\n${report.entries.length} distinct observed occurrence(s); ${active} unresolved. Counts cover retained observations, not all repository history.\n\nNext action: ${active ? causes[report.code][1] : 'No action for these occurrences. A new failure reuses this report.'}\n\n| Work item | Evidence | Retry | State |\n| --- | --- | --- | --- |\n${rows.join('\n')}\n\n<!-- ${marker}:${JSON.stringify(report)} -->`;
+  if (Buffer.byteLength(body) > 60000) throw Error('Report body exceeds issue bounds; operator archival is required');
+  return body;
+}
+
+function readIndex(issue, owner) {
+  if (issue.pull_request || issue.user?.login !== owner || issue.state !== 'open') throw Error('Report index must be an open owner-authored issue');
+  const body = issue.body ?? '';
+  if (!body.includes(indexStart) && !body.includes(indexEnd) && !body.includes('<!-- lighthouse-worker-report-index:')) return { schemaVersion: 1, reports: {} };
+  if (body.split(indexStart).length !== 2 || body.split(indexEnd).length !== 2 || body.indexOf(indexStart) > body.indexOf(indexEnd)) throw Error('Ambiguous index block');
+  const index = parseMarker(body, 'lighthouse-worker-report-index');
+  if (index.schemaVersion !== 1 || !index.reports || typeof index.reports !== 'object' || Array.isArray(index.reports) || Object.keys(index.reports).length > 100) throw Error('Invalid report index');
+  return index;
+}
+
+async function writeIndex(api, issue, index) {
+  const current = await api(`issues/${issue.number}`);
+  if (current.body !== issue.body || current.state !== 'open') throw Error('Report index changed; no overwrite');
+  const links = Object.values(index.reports).map(r => r.issue ? `- #${r.issue}: ${r.worker} / ${r.code}` : `- Pending confirmation: ${r.worker} / ${r.code}`);
+  const block = `${indexStart}\n## Worker error reports\n\n${links.join('\n')}\n\n<!-- lighthouse-worker-report-index:${JSON.stringify(index)} -->\n${indexEnd}`;
+  const body = (issue.body ?? '').includes(indexStart) ? issue.body.slice(0, issue.body.indexOf(indexStart)) + block + issue.body.slice(issue.body.indexOf(indexEnd) + indexEnd.length) : `${issue.body ?? ''}\n\n${block}`;
+  if (Buffer.byteLength(body) > 60000) throw Error('Report index exceeds issue bounds');
+  const updated = await api(`issues/${issue.number}`, 'PATCH', { body });
+  return updated;
+}
+
+async function reportIssues(api) {
+  const all = [];
+  for (let page = 1; page <= 5; page++) {
+    const rows = await api(`issues?state=all&per_page=100&page=${page}`);
+    all.push(...rows.filter(i => !i.pull_request && i.body?.includes(`<!-- ${marker}:`)));
+    if (rows.length < 100) return all;
+  }
+  throw Error('Report reconciliation exceeds 500 issue/PR entries');
+}
+
+// Caller serializes all report publication with the repository-wide report job.
+export async function publishReports(api, repository, owner, indexNumber, observations) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository) || !positive(indexNumber) || !Array.isArray(observations) || observations.length > 1000) throw Error('Invalid report publication input');
+  let indexIssue = await api(`issues/${indexNumber}`);
+  const index = readIndex(indexIssue, owner), existing = await reportIssues(api), desired = new Map();
+  for (const observation of observations) {
+    const o = normalizedObservation(repository, observation);
+    if (o?.entry) desired.set(reportSignature(repository, o.worker, o.code), { worker: o.worker, code: o.code });
+  }
+  for (const [signature, row] of Object.entries(index.reports)) {
+    if (![...workers, 'maintenance'].includes(row.worker) || !Object.hasOwn(causes, row.code) || signature !== reportSignature(repository, row.worker, row.code) || row.issue !== null && !positive(row.issue)) throw Error('Invalid indexed report');
+    desired.set(signature, row);
+  }
+  if (desired.size > 100) throw Error('Report index exceeds 100 causes');
+  const results = [];
+  for (const [signature, definition] of desired) {
+    const { worker, code } = definition;
+    const matches = existing.filter(i => { try { return parseMarker(i.body, marker).signature === signature; } catch { return false; } });
+    if (matches.length > 1) throw Error('Ambiguous report identity; inspect duplicates');
+    let issue = index.reports[signature]?.issue ? await api(`issues/${index.reports[signature].issue}`) : matches[0];
+    if (issue) readReport(issue, repository, worker, code);
+    if (!issue && Object.hasOwn(index.reports, signature)) throw Error('Report creation is unconfirmed; inspect the index before any resend');
+    if (!issue) {
+      const report = mergeObservations(repository, { schemaVersion: 1, signature, worker, code, entries: [] }, observations);
+      const body = reportBody(repository, report);
+      index.reports[signature] = { worker, code, issue: null };
+      indexIssue = await writeIndex(api, indexIssue, index); // Durable intent precedes the non-idempotent POST.
+      issue = await api('issues', 'POST', { title: `Worker ${worker}: ${causes[code][0]}`, body });
+      readReport(issue, repository, worker, code);
+      existing.push(issue);
+    }
+    if (index.reports[signature]?.issue !== issue.number) {
+      index.reports[signature] = { worker, code, issue: issue.number };
+      indexIssue = await writeIndex(api, indexIssue, index);
+    }
+    const previous = readReport(issue, repository, worker, code), report = mergeObservations(repository, previous, observations);
+    const body = reportBody(repository, report), active = report.entries.some(e => e.state !== 'recovered');
+    const newlyFailed = report.entries.some(e => e.state !== 'recovered' && !previous.entries.some(p => p.key === e.key && p.state !== 'recovered'));
+    const state = !active ? 'closed' : newlyFailed ? 'open' : issue.state;
+    if (issue.body !== body || issue.state !== state) await api(`issues/${issue.number}`, 'PATCH', { body, state });
+    results.push({ number: issue.number, signature, count: report.entries.length, state });
+  }
+  return results;
+}