@juangcarmona/lighthouse-sdlc 0.17.1 → 0.18.0

package/src/stage-transition.mjs

@@ -1,17 +1,35 @@
 import { readActionsJson } from './actions-artifact.mjs';
 import { loadDispatch, checkDispatchClaim, stagePath, issueComments } from './stage-dispatch.mjs';
 import { validateStageEnvelope } from './host-contract.mjs';
+import { assessDecomposition } from './epic.mjs';
 
 // Explicit dispatch also works when GitHub suppresses follow-up token events.
 // This is a wake-up only; the router rechecks the completed run and owner intent.
 export async function signalRefinementContinuation(api, request, envelope) {
   if (request.stage !== 'refine' || !request.dispatch || request.autoImplement !== true || envelope.result?.status !== 'passed' || envelope.result?.gate !== 'ready') return false;
   if (validateStageEnvelope(envelope, request).length) throw Error('Invalid refinement result');
+  if (envelope.result.output?.estimate !== undefined && assessDecomposition(envelope.result.output).status === 'planned') return false;
   const repository = await api('');
   await api('actions/workflows/lighthouse-sdlc-router.yml/dispatches', 'POST', { ref: repository.default_branch, inputs: { issue: String(request.issue), stage: 'implement', after_run: String(request.workflowRunId) } });
   return true;
 }
 
+// Signal only after publication and cleanup; the router authenticates the completed run.
+export async function signalProductGap(api, request, envelope) {
+  if (!request.dispatch || !request.productChangeEnabled || !['triage', 'refine', 'propose', 'implement'].includes(request.stage) || envelope.result?.status !== 'blocked' || !envelope.result.output?.productGap) return false;
+  if (validateStageEnvelope(envelope, request).length) throw Error('Invalid product prerequisite result');
+  const repository = await api('');
+  await api('actions/workflows/lighthouse-sdlc-router.yml/dispatches', 'POST', { ref: repository.default_branch, inputs: { issue: String(request.issue), stage: request.stage, workflow: 'product-change', after_run: String(request.workflowRunId) } });
+  return true;
+}
+
+export async function signalProductApplyContinuation(api, issue, runId, checkpoint) {
+  if (!checkpoint.parent) return false;
+  const repository = await api('');
+  await api('actions/workflows/lighthouse-sdlc-router.yml/dispatches', 'POST', { ref: repository.default_branch, inputs: { issue: String(issue), stage: checkpoint.parent.stage, workflow: 'resume-product', after_run: String(runId) } });
+  return true;
+}
+
 // 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;
@@ -24,12 +42,143 @@ export async function refinementAfterRun(api, repository, owner, event, readArti
   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');
+  if (origin.request.stage !== 'refine' || origin.request.autoImplement !== true || origin.request.id !== request.dispatch.requestId || origin.request.sourceRevision !== (request.baseRevision ?? request.sourceRevision) || origin.request.workflowRevision !== request.workflowRevision || JSON.stringify(origin.request.productResume) !== JSON.stringify(request.productResume)) 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.output?.estimate !== undefined && assessDecomposition(envelope.result.output).status === 'planned') return null;
   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.' };
+  return { run: true, stage: 'implement', issue: request.issue, predecessor: { runId: String(run.id), attempt: run.run_attempt }, ...(request.productResume ? { productResume: request.productResume } : {}), reason: 'Verified refinement completed; implementation requested by the installed policy.' };
+}
+
+// A completed worker can identify a prerequisite, but cannot authorize product work.
+// The retained dispatch and published result bind the observation to the owner's request.
+export async function productGapAfterRun(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}`);
+  const directStage = ['triage', 'refine', 'propose', 'implement'].find(name => run.path === stagePath(name));
+  const reviewWorker = run.path === stagePath('apply-review');
+  if ((!directStage && !reviewWorker) || 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('Product prerequisite artifacts exceed bounds');
+  const inputs = artifacts.artifacts.filter(a => new RegExp(`^lighthouse-(?:implement-)?input-[1-9][0-9]*-${run.run_attempt}$`).test(a.name) && !a.expired);
+  if (inputs.length !== 1) return null;
+  const request = await readArtifact(api, repository, run.id, inputs[0].name, 'request.json');
+  const stage = request.stage;
+  if ((!reviewWorker && stage !== directStage) || (reviewWorker && (!['propose', 'implement'].includes(stage) || request.worker !== 'apply-review')) || !request.dispatch || String(request.workflowRunId) !== String(run.id) || !reviewWorker && request.worker && request.worker !== stage || inputs[0].name !== `${stage === 'implement' ? 'lighthouse-implement-input-' : 'lighthouse-input-'}${request.issue}-${run.run_attempt}`) return null;
+  const origin = await loadDispatch(api, repository, owner, request.issue, request.dispatch.commentId, run, readArtifact);
+  if (origin.request.stage !== stage || origin.request.id !== request.dispatch.requestId || origin.request.sourceRevision !== (request.baseRevision ?? request.sourceRevision) || origin.request.workflowRevision !== request.workflowRevision || origin.request.taskDigest !== request.taskDigest) throw Error('Product prerequisite parent identity mismatch');
+  await checkDispatchClaim(api, repository, request.issue, request.dispatch, run.id);
+  const resultName = `${stage === 'implement' ? 'lighthouse-implement-result-' : 'lighthouse-result-'}${request.issue}-${run.run_attempt}`;
+  const envelope = await readArtifact(api, repository, run.id, resultName, 'envelope.json');
+  if (validateStageEnvelope(envelope, request).length) throw Error('Invalid product prerequisite result');
+  if (envelope.result.status !== 'blocked' || !envelope.result.output?.productGap) return null;
+  const reports = await issueComments(api, request.issue);
+  const matches = reports.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && c.body.includes(`<!-- lighthouse-actions:${request.runId} -->`) && c.body.includes(`<!-- lighthouse-stage:${stage}:blocked -->`));
+  if (matches.length !== 1) return null;
+  const proofs = [...matches[0].body.matchAll(/<!-- lighthouse-pr-state:(\{[^\n]*\}) -->/g)];
+  if (proofs.length > 1) throw Error('Product prerequisite has ambiguous existing PR evidence');
+  const proof = proofs.length ? JSON.parse(proofs[0][1]) : null;
+  if (proof && (proof.run !== run.id || proof.complete !== false)) throw Error('Product prerequisite PR evidence does not match the blocked parent');
+  const review = request.implementationReview ?? request.proposalReview;
+  if (proof && review && proof.pr !== review.number) throw Error('Product prerequisite references a different issue PR');
+  let reviewEvidence;
+  if (review) {
+    const { reviewThread } = await import('./proposal-review.mjs');
+    const { digest } = await import('./host-contract.mjs');
+    const relevant = rows => rows.filter(row => !/^\/product-change (?:approve|request-changes|answer) [a-z0-9]+(?:-[a-z0-9]+)* [a-f0-9]{64}(?:\n|$)/.test((row.body ?? '').trim()));
+    if (!Array.isArray(review.thread) || !/^[a-f0-9]{64}$/.test(review.feedbackDigest ?? '') || !/^[a-f0-9]{64}$/.test(review.threadDigest ?? '') || digest(JSON.stringify(review.thread)) !== review.threadDigest) throw Error('Parent PR review evidence is invalid');
+    const currentFeedback = await api(review.path);
+    const currentThread = await reviewThread(api, review.number, owner);
+    const threadDigest = digest(JSON.stringify(relevant(review.thread)));
+    if (digest(JSON.stringify(currentFeedback)) !== review.feedbackDigest || digest(JSON.stringify(relevant(currentThread))) !== threadDigest) throw Error('Parent PR feedback changed');
+    reviewEvidence = { number: review.number, path: review.path, feedbackDigest: review.feedbackDigest, threadDigest };
+  }
+  let pullRequest;
+  if (proof || review) {
+    const number = proof?.pr ?? review.number, head = proof?.head ?? review.head;
+    const pr = await api(`pulls/${number}`);
+    if (!Number.isSafeInteger(number) || number < 1 || !/^[a-f0-9]{40}$/.test(head ?? '') || pr.number !== number || pr.state !== 'open' || pr.merged || pr.user?.login !== 'github-actions[bot]' || pr.user.type !== 'Bot' || pr.head?.repo?.full_name !== repository || pr.base?.repo?.full_name !== repository || !new RegExp(`^lighthouse/(?:implement|propose)-${request.issue}-[a-f0-9]{12}$`).test(pr.head.ref)) throw Error('Existing issue PR is not an eligible parent');
+    pullRequest = { number, head, branch: pr.head.ref };
+  }
+  return { issue: request.issue, stage, predecessor: { runId: String(run.id), attempt: run.run_attempt }, gap: envelope.result.output.productGap, sourceRevision: request.sourceRevision, baseRevision: request.baseRevision ?? request.sourceRevision, taskDigest: request.taskDigest, autoImplement: request.autoImplement === true, ...(pullRequest ? { pullRequest } : {}), ...(reviewEvidence ? { review: reviewEvidence } : {}) };
+}
+
+// Recheck the original parent and, when present, the authenticated answer to a
+// product question. The answer changes context; it does not approve product intent.
+export async function verifyProductParent(api, repository, owner, parent, issue, reports, currentBase, readArtifact = readActionsJson) {
+  const { feedback, ...original } = parent;
+  const parentRun = await api(`actions/runs/${original.predecessor.runId}`);
+  const observed = await productGapAfterRun(api, repository, owner, { action: 'completed', workflow_run: { id: parentRun.id, head_sha: parentRun.head_sha } }, readArtifact);
+  if (JSON.stringify(observed) !== JSON.stringify(original) || currentBase !== original.baseRevision) throw Error('Product prerequisite parent or base changed');
+  let expectedDigest = original.taskDigest;
+  if (feedback) {
+    const run = await api(`actions/runs/${feedback.runId}`);
+    if (run.path !== stagePath('product-change') || run.status !== 'completed' || run.conclusion !== 'success' || run.run_attempt !== feedback.attempt) throw Error('Product answer execution is unavailable');
+    const snapshot = await readArtifact(api, repository, run.id, `lighthouse-input-${issue.number}-${run.run_attempt}`, 'request.json');
+    const envelope = await readArtifact(api, repository, run.id, `lighthouse-result-${issue.number}-${run.run_attempt}`, 'envelope.json');
+    if (!snapshot.dispatch || snapshot.issue !== issue.number || String(snapshot.workflowRunId) !== String(run.id) || snapshot.taskDigest !== feedback.taskDigest || snapshot.replyTo !== feedback.replyTo || snapshot.commentId !== feedback.commentId || JSON.stringify(snapshot.productParent) !== JSON.stringify(original) || validateStageEnvelope(envelope, snapshot).length || envelope.result.status !== 'passed' || envelope.result.output?.productChange?.outcome !== 'candidate') throw Error('Product answer execution does not bind the parent and candidate');
+    const origin = await loadDispatch(api, repository, owner, issue.number, snapshot.dispatch.commentId, run, readArtifact);
+    await checkDispatchClaim(api, repository, issue.number, snapshot.dispatch, run.id);
+    const answer = origin.request.event?.comment;
+    if (origin.request.worker !== 'product-change' || origin.request.id !== snapshot.dispatch.requestId || origin.request.taskDigest !== snapshot.taskDigest || origin.request.productFeedback?.action !== 'answer' || Number(origin.request.productFeedback.sourceCommentId) !== feedback.commentId || answer?.id !== feedback.commentId || answer.user?.login !== owner || answer.user?.type !== 'User' || !reports.some(c => c.id === feedback.commentId && c.user?.login === owner && c.body === answer.body)) throw Error('Product answer is not the authenticated owner reply');
+    const priorReports = reports.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && c.body.includes(`<!-- lighthouse-actions:${feedback.replyTo} -->`) && c.body.includes('<!-- lighthouse-question -->'));
+    if (priorReports.length !== 1) throw Error('Product question evidence is unavailable or ambiguous');
+    const prior = priorReports[0];
+    const priorRunId = prior?.body.match(/\[Workflow run\]\(https:\/\/github\.com\/[^/]+\/[^/]+\/actions\/runs\/(\d+)\)/)?.[1];
+    if (!priorRunId) throw Error('Product question evidence is unavailable');
+    const priorRun = await api(`actions/runs/${priorRunId}`);
+    const priorSnapshot = await readArtifact(api, repository, priorRun.id, `lighthouse-input-${issue.number}-${priorRun.run_attempt}`, 'request.json');
+    const priorEnvelope = await readArtifact(api, repository, priorRun.id, `lighthouse-result-${issue.number}-${priorRun.run_attempt}`, 'envelope.json');
+    if (priorRun.path !== stagePath('product-change') || priorRun.status !== 'completed' || priorRun.conclusion !== 'success' || priorSnapshot.runId !== feedback.replyTo || String(priorSnapshot.workflowRunId) !== String(priorRun.id) || priorSnapshot.issue !== issue.number || JSON.stringify(priorSnapshot.productParent) !== JSON.stringify(original) || validateStageEnvelope(priorEnvelope, priorSnapshot).length || priorEnvelope.result.status !== 'blocked' || priorEnvelope.result.output?.productChange?.question !== snapshot.answerHistory?.at(-1)?.question || snapshot.answerHistory?.at(-1)?.answer?.body !== answer.body) throw Error('Product answer no longer matches the pending question');
+    const priorOrigin = await loadDispatch(api, repository, owner, issue.number, priorSnapshot.dispatch.commentId, priorRun, readArtifact);
+    if (priorOrigin.request.id !== priorSnapshot.dispatch.requestId || priorOrigin.request.worker !== 'product-change' || !(priorOrigin.request.productParent || priorOrigin.request.productFeedback || priorOrigin.request.productReview?.parent)) throw Error('Product question dispatch changed');
+    await checkDispatchClaim(api, repository, issue.number, priorSnapshot.dispatch, priorRun.id);
+    if (reports.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && c.body.includes(`<!-- lighthouse-actions:${snapshot.runId} -->`) && c.body.includes(`<!-- lighthouse-stage:${snapshot.stage}:passed -->`)).length !== 1) throw Error('Product answer publication is unavailable or ambiguous');
+    expectedDigest = feedback.taskDigest;
+  }
+  const { createHash } = await import('node:crypto');
+  const answers = reports.filter(c => c.user?.login === owner && !c.body.includes('<!-- lighthouse-run:') && !c.body.includes('<!-- lighthouse-actions:'));
+  const intent = createHash('sha256').update(JSON.stringify({ title: issue.title, body: issue.body, comments: answers.map(c => ({ id: c.id, body: c.body, updated_at: c.updated_at })) })).digest('hex');
+  if (intent !== expectedDigest) throw Error('Product parent owner intent changed');
+  return true;
+}
+
+// A product apply is usable by a parent only when its original approval, provider
+// result, published receipt, current PR head and retained parent still agree.
+export async function productApplyAfterRun(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('apply-product-change') || 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('Product apply artifacts exceed bounds');
+  const inputs = artifacts.artifacts.filter(a => new RegExp(`^lighthouse-product-apply-input-[1-9][0-9]*-${run.run_attempt}$`).test(a.name) && !a.expired);
+  if (inputs.length !== 1) return null;
+  const input = await readArtifact(api, repository, run.id, inputs[0].name, 'product-apply.json');
+  if (!input.checkpoint?.parent || input.repository !== repository || input.owner !== owner || !input.dispatch || input.issue !== input.checkpoint.parent.issue) return null;
+  const dispatch = await loadDispatch(api, repository, owner, input.issue, input.dispatch.commentId, run, readArtifact);
+  if (dispatch.request.worker !== 'apply-product-change' || dispatch.request.id !== input.dispatch.requestId || dispatch.request.productApproval?.reviewKey !== input.approval?.reviewKey || dispatch.request.productApproval?.head !== input.head || input.binding?.key !== input.approval?.reviewKey) throw Error('Product apply dispatch or approval identity changed');
+  await checkDispatchClaim(api, repository, input.issue, input.dispatch, run.id);
+  const output = await readArtifact(api, repository, run.id, `lighthouse-product-apply-proof-${input.issue}-${run.run_attempt}`, 'apply-proof.json');
+  if (output.head !== input.head || output.receipt?.headBefore !== input.head || output.receipt?.validated !== true || output.receipt?.proposalDigest !== input.checkpoint.proposalDigest || output.receipt?.baselineDigest !== input.checkpoint.baselineDigest || output.receipt?.resultingModelDigest !== output.resultingModelDigest) throw Error('Product apply provider result does not match its approval');
+  const pr = await api(`pulls/${input.pullRequest}`);
+  if (pr.state !== 'open' || pr.merged || !pr.draft || pr.user?.login !== 'github-actions[bot]' || pr.user?.type !== 'Bot' || pr.head?.repo?.full_name !== repository || pr.base?.repo?.full_name !== repository) throw Error('Applied product PR is no longer eligible for continuation');
+  const matches = [...(pr.body ?? '').matchAll(/<!-- lighthouse-product-change(?:-checkpoint|:checkpoint):(\{[^\n]*\}) -->/g)];
+  if (matches.length !== 1) throw Error('Applied product checkpoint is unavailable or ambiguous');
+  const checkpoint = JSON.parse(matches[0][1]);
+  const { validateProductCheckpoint, productReviewBinding } = await import('./product-change.mjs');
+  const { createHash } = await import('node:crypto');
+  const hash = value => createHash('sha256').update(value).digest('hex');
+  const { key, ...bindingFields } = input.binding;
+  if (validateProductCheckpoint(checkpoint).length || checkpoint.state !== 'applied' || checkpoint.identity.head !== pr.head.sha || JSON.stringify(checkpoint.parent) !== JSON.stringify(input.checkpoint.parent) || input.binding.parentDigest !== hash(JSON.stringify(checkpoint.parent)) || productReviewBinding(bindingFields).key !== key) throw Error('Applied product checkpoint or parent binding changed');
+  const reports = await issueComments(api, input.issue);
+  const receipts = reports.filter(c => c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot').flatMap(c => [...(c.body ?? '').matchAll(/<!-- lighthouse-product-apply:(\{[^\n]*\}) -->/g)].map(m => JSON.parse(m[1]))).filter(r => r.intentId === output.receipt.intentId);
+  if (receipts.length !== 1 || receipts[0].headBefore !== input.head || receipts[0].headAfter !== pr.head.sha || receipts[0].resultingModelDigest !== output.resultingModelDigest || !checkpoint.effectIds.includes(`apply:${receipts[0].intentId}:${pr.head.sha}`)) throw Error('Applied product publication is missing, stale or ambiguous');
+  const info = await api(''), currentBase = (await api(`commits/${info.default_branch}`)).sha;
+  const issue = await api(`issues/${input.issue}`);
+  await verifyProductParent(api, repository, owner, checkpoint.parent, issue, reports, currentBase, readArtifact);
+  if (issue.state !== 'open' || issue.labels?.some(l => ['future', 'human-working', 'agent-working'].includes(l.name)) || pr.base.ref !== info.default_branch) throw Error('Product parent authorization, base or issue changed before continuation');
+  return { issue: input.issue, stage: checkpoint.parent.stage, parent: checkpoint.parent, applyRun: { runId: String(run.id), attempt: run.run_attempt }, pullRequest: pr.number, head: pr.head.sha, branch: pr.head.ref, baseRevision: currentBase, receiptIntent: receipts[0].intentId };
 }

package/src/triage.mjs

@@ -223,7 +223,8 @@ export function buildTriageReport(input) {
   validateAssessment(input.assessment, errors);
 
   const state = currentState(currentLabels, configuration);
-  if (state.states.length > 1) addIssue(errors, 'state.ambiguous', `work item has multiple workflow state labels: ${state.states.join(', ')}`, 'currentLabels');
+  const proposalReview = state.states.length === 2 && state.states.includes('ready') && state.states.includes('waiting-review');
+  if (state.states.length > 1 && !proposalReview) addIssue(errors, 'state.ambiguous', `work item has multiple workflow state labels: ${state.states.join(', ')}`, 'currentLabels');
   if (state.states.length === 0) addIssue(errors, 'state.missing', 'work item needs one configured workflow state label', 'currentLabels');
   const assessment = isRecord(input.assessment) ? input.assessment : {};
   if (state.value && typeof assessment.nextState === 'string' && configuration.stateLabels.has(assessment.nextState)) {
@@ -244,11 +245,12 @@ export function buildTriageReport(input) {
   const unavailableChecks = evidence.filter((item) => isRecord(item) && item.status === 'unavailable').map((item) => item.field);
   const pendingReview = evidence.filter((item) => isRecord(item) && item.status === 'pending-review').map((item) => item.field);
   const warnings = [
+    ...(proposalReview ? [issue('state.review-pending', 'A native proposal review retains ready as a revocable gate. Complete or resolve that review before applying generic triage.', 'currentLabels')] : []),
     ...missingEvidence.map((field) => issue('evidence.missing', `${field} has no evidence record`, field)),
     ...unavailableChecks.map((field) => issue('evidence.unavailable', `${field} could not be checked`, field)),
     ...pendingReview.map((field) => issue('evidence.pending-review', `${field} is waiting for judgement`, field)),
   ];
-  const proposed = proposedLabels(currentLabels, assessment, configuration);
+  const proposed = proposalReview ? currentLabels : proposedLabels(currentLabels, assessment, configuration);
   const status = errors.length ? 'invalid' : warnings.length ? 'blocked' : 'ready';
   return {
     schemaVersion: 1,

package/src/unattended-actions.mjs

@@ -11,7 +11,8 @@ import { taskDigest } from './issue-actions.mjs';
 import { list, inspectCompletion, assertChecks, mergeAccepted, postMergeRuns } from './completion.mjs';
 import { completionBundle, publishProcessBundle } from './process-publication.mjs';
 import { dispatchDeliveryChecks } from './delivery-events.mjs';
-import { setPullRequestDraft } from './pr-state.mjs';
+import { setPullRequestDraft, projectImplementationPrState } from './pr-state.mjs';
+import { handoff, pendingQuestion } from './handoff.mjs';
 
 const harness = fileURLToPath(new URL('../', import.meta.url));
 const readJson = async path => JSON.parse(await readFile(path, 'utf8'));
@@ -60,7 +61,9 @@ export async function runGithubUnattended({ env = process.env, api = (...args) =
   const issue = await api('issues/' + issueNumber);
   if (issue.state !== 'open' || issue.pull_request || issue.user?.login !== owner || issue.labels.some(l => ['future', 'needs-info', 'waiting-review', 'human-working', 'agent-working'].includes(l.name))) throw Error('Issue is closed, reserved, paused or requires owner admission');
   const comments = () => list(api, 'issues/' + issueNumber + '/comments');
-  const ownerAnswers = owners(await comments(), owner);
+  const initialComments = await comments();
+  const initialCommentId = Math.max(0, ...initialComments.map(comment => Number.isSafeInteger(comment.id) ? comment.id : 0));
+  const ownerAnswers = owners(initialComments, owner);
   const intent = taskDigest(issue, ownerAnswers);
   const issueContext = { ...issue, ownerAnswers };
   const runId = unattendedDigest({ repository, issue: issueNumber, route, run: env.GITHUB_RUN_ID });
@@ -99,7 +102,23 @@ export async function runGithubUnattended({ env = process.env, api = (...args) =
       await assertUnattendedPullRequest(api, await comments(), current, owner);
     }
   };
-  const notify = body => api('issues/' + issueNumber + '/comments', 'POST', { body: body + '\n\n[Execution](' + runUrl + ').\n\n' + marker });
+  const newerAttempt = async () => {
+    const latest = (await comments()).filter(c => c.id > initialCommentId && c.user?.login === 'github-actions[bot]' && c.user.type === 'Bot' && /<!-- lighthouse-(?:unattended|dispatch|actions|stop):/.test(c.body ?? '')).at(-1);
+    return !!latest && !latest.body.includes(marker);
+  };
+  const notify = async body => {
+    if (await newerAttempt()) throw Error('A newer workflow attempt has taken over');
+    return api('issues/' + issueNumber + '/comments', 'POST', { body: body + '\n\n[Execution](' + runUrl + ').\n\n' + marker });
+  };
+  const releaseReservation = async () => {
+    if (await newerAttempt()) { reserved = false; return 'stale'; }
+    if (!reserved) return 'released';
+    const fresh = await api('issues/' + issueNumber);
+    if (fresh.labels.some(label => label.name === 'human-working')) { reserved = false; return 'held'; }
+    if (fresh.labels.some(label => label.name === 'agent-working')) await api('issues/' + issueNumber + '/labels/agent-working', 'DELETE', undefined, true);
+    reserved = false;
+    return 'released';
+  };
   const publicationApi = async (path, method, ...args) => {
     if (method === 'POST' && ['git/refs', 'pulls'].includes(path)) {
       await recheck();
@@ -121,6 +140,8 @@ export async function runGithubUnattended({ env = process.env, api = (...args) =
       prompt: text, ...(worker === 'independent-review' ? { modelProfile: policy.reviewerProfile } : {}), signal: controller.signal });
     if (result.runtime.execution?.status !== 'passed') throw Error('Host cannot verify completed model execution');
     if (worker === 'independent-review' && result.runtime.model !== reviewer.model || stage === 'implement' && result.runtime.model !== producer.model) throw Error('Operator model selection changed during delivery');
+    const question = result.envelope.result.status === 'blocked' ? pendingQuestion(result.envelope.result.output?.handoff?.question) : null;
+    if (question) { const error = Error(result.envelope.effect.body); error.question = question; throw error; }
     if (stage !== 'implement' && worker !== 'independent-review' && result.envelope.result.status !== 'passed') throw Error(result.envelope.effect.body);
     return result;
   };
@@ -146,8 +167,8 @@ export async function runGithubUnattended({ env = process.env, api = (...args) =
   };
   try {
     await recheck();
-    await notify('Requested · ' + route + '\n\nAuthorized bounded delivery is starting. Your next action: none unless a product decision or blocker is reported.');
     await api('issues/' + issueNumber + '/labels', 'POST', { labels: ['agent-working'] }); reserved = true;
+    await notify(handoff({ status: 'working', stage: route, happened: 'The authorized bounded delivery has started.', action: 'None. Wait for the result or a specific blocker.', next: 'The workflow will publish its actual outcome and any required decision.' }));
     const outcome = await runUnattended({ route, policy, signal: controller.signal, host: {
       recheck,
       refine: async () => {
@@ -205,10 +226,10 @@ export async function runGithubUnattended({ env = process.env, api = (...args) =
         const snapshot = { issue: issueNumber, sourceRevision: revision, defaultBranch: metadata.default_branch, runId, title: issue.title, implementation };
         published = await createImplementationPullRequest(publicationApi, snapshot, candidate.changes, 'Bounded ' + route + ' delivery with independent review. ' + candidate.envelope.effect.body, runUrl, true, recheck);
         await recheck();
-        await notify('Candidate checks and independent review passed.\n\n<!-- lighthouse-pr-state:' + JSON.stringify({ pr: published.number, head: published.head.sha, complete: true, run: Number(env.GITHUB_RUN_ID) }) + ' -->');
-        await api('issues/' + issueNumber + '/labels/agent-working', 'DELETE', undefined, true); reserved = false;
+        await projectImplementationPrState(api, issueNumber, true);
+        if (await releaseReservation() !== 'released') throw Error('The execution reservation changed before PR handoff; inspect the current issue and PR.');
+        await notify(handoff({ status: policy.merge ? 'queued' : 'review', stage: route, happened: 'The candidate passed its executed checks and independent review.', action: policy.merge ? 'None. Wait for the required CI and integration check.' : 'Owner: review the linked PR and authorize integration if appropriate.', next: policy.merge ? 'The workflow will recheck the PR head, CI and delegated merge authority.' : 'Integration waits for separate authorization.', link: `[Candidate PR #${published.number}](${published.html_url})`, details: '<!-- lighthouse-pr-state:' + JSON.stringify({ pr: published.number, head: published.head.sha, complete: true, run: Number(env.GITHUB_RUN_ID) }) + ' -->' }));
         await dispatchDeliveryChecks(dispatchApi, revision, published);
-        await notify('Ready for integration · ' + route + '\n\n[PR #' + published.number + '](' + published.html_url + ') contains the independently reviewed candidate. Required CI and current merge authority are checked before integration.');
         return published;
       },
       integrate: async (candidate, pr) => {
@@ -265,22 +286,28 @@ export async function runGithubUnattended({ env = process.env, api = (...args) =
           try { await notify(body); }
           catch (error) { notifications.push({ status: 'unavailable', reason: error.message.slice(0, 3000) }); }
         };
-        let postMerge;
+        let postMerge, postMergeError;
         try { postMerge = await postMergeRuns(dispatchApi, observation, result.sha, !controller.signal.aborted); }
         catch (error) {
+          postMergeError = error;
           postMerge = observation.profile.completion.postMergeWorkflows.map(workflow => ({ workflow, revision: result.sha, state: 'missing', status: 'unavailable', reason: error.message.slice(0, 3000) }));
-          await notifyIntegrated('Post-merge verification needs attention. The merge at ' + result.sha + ' and its retained receipt are confirmed; inspect current CI runs before requesting verification again. ' + error.message.slice(0, 3000));
         }
-        await notifyIntegrated('Integrated · ' + route + '\n\n[PR #' + pr.number + '](' + pr.html_url + ') was merged at ' + result.sha + '. Post-merge review follows the existing CI/completion policy. Release and deployment have not been established by this integration result.');
+        await notifyIntegrated(handoff({ status: postMergeError ? 'blocked' : 'completed', stage: route, happened: `PR #${pr.number} was merged at ${result.sha}.${postMergeError ? ' Post-merge verification could not be requested.' : ''}`, action: postMergeError ? 'Workflow maintainer: inspect the execution and current CI before requesting verification again.' : 'None.', next: postMergeError ? 'Post-merge verification remains unconfirmed.' : 'Post-merge review follows the configured CI and completion policy; release and deployment remain separate.', link: `[Merged PR #${pr.number}](${pr.html_url})` }));
         return { ...result, postMerge, notifications };
       },
-      stop: async reason => { await notify('Blocked · ' + route + '\n\n' + reason + '\n\nYour next action: inspect the linked execution logs and retained artifacts, then resolve this blocker before a new request. No automatic retry is scheduled.' + (published ? '\n\n[Candidate PR](' + published.html_url + ')' : '')); },
+      stop: async (reason, _evidence, error) => {
+        const released = await releaseReservation();
+        if (released === 'stale') return;
+        const question = released === 'released' ? pendingQuestion(error?.question) : null;
+        if (question) await api('issues/' + issueNumber + '/labels', 'POST', { labels: ['needs-info'] });
+        await notify(handoff({ status: released === 'held' ? 'unknown' : question ? 'question' : 'blocked', stage: route, happened: String(reason).slice(0, 4000).replace(/<!--\s*lighthouse-/gi, '&lt;!-- lighthouse-'), action: released === 'held' ? 'Workflow maintainer: inspect the human hold and existing execution reservation before releasing it.' : question ? `Owner: ${question} Reply here.` : 'Workflow maintainer: inspect the execution and retained artifacts, then resolve the blocker.', next: question ? 'The reply is retained. The maintainer must clear needs-info, then the owner can request a new bounded run; the reply does not approve another gate.' : 'No automatic retry is scheduled.', ...(published ? { link: `[Candidate PR #${published.number}](${published.html_url})` } : {}) }));
+      },
     } });
     await writeFile(join(root, 'report.json'), JSON.stringify(outcome, null, 2));
     return outcome;
   } finally {
     clearTimeout(timer); process.removeListener('SIGTERM', onSignal); process.removeListener('SIGINT', onSignal);
-    if (reserved) await api('issues/' + issueNumber + '/labels/agent-working', 'DELETE', undefined, true);
+    if (reserved) await releaseReservation();
   }
 }
 

package/src/unattended.mjs

@@ -155,7 +155,7 @@ export async function runUnattended({ route, policy, host, signal }) {
     evidence.push({ kind: 'integration', result: integrated });
     return { status: 'passed', published, integrated, evidence, durationMs: Date.now() - started, nextAction: 'Follow existing post-merge review and release policy' };
   } catch (error) {
-    await host.stop(error.message, evidence);
+    await host.stop(error.message, evidence, error);
     return { status: 'blocked', evidence, reason: error.message, nextAction: 'Inspect execution evidence and resolve the identified blocker' };
   }
 }

package/src/worker-maintenance.mjs

@@ -2,7 +2,7 @@ import { readFile, writeFile, mkdir, appendFile, readdir } from 'node:fs/promise
 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 { maintenancePath, prepareRecovery, observeRecovery } from './worker-recovery.mjs';
 import { publishReports } from './worker-reports.mjs';
 
 export async function ownerIssues(api, owner) {
@@ -21,8 +21,9 @@ export async function ownerIssues(api, owner) {
 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 api = async (path, method = 'GET', body, optional = false) => {
     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 (optional && response.status === 404) return null;
     if (!response.ok) throw Error(`GitHub ${method} ${path}: ${response.status}`);
     return response.status === 204 ? null : response.json();
   };
@@ -35,7 +36,7 @@ async function main(command) {
     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]*)$/);
+      const match = directory.match(/^lighthouse-(?:maintenance|observation)-([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');
@@ -59,6 +60,17 @@ async function main(command) {
   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 === 'observe') {
+    await mkdir(dir, { recursive: true });
+    try {
+      const observations = await observeRecovery(api, repository, owner, issue);
+      await writeFile(join(dir, 'observations.json'), JSON.stringify(observations));
+    } 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;
+    }
+    return;
+  }
   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;