atris 3.75.0 → 3.77.0

package/lib/task-db.js

@@ -27,6 +27,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { DatabaseSync } = require('node:sqlite');
 const reviewIntegrity = require('./review-integrity');
+const { pullRequestOfLink } = require('./pull-request-link');
 const { PROOF_NOT_SAVED, COULD_NOT_START, BUILD_STARTED } = require('./release-kind');
 const dailyLog = require('./daily-log');
 const { isGenericScratchRoot } = require('./scratch-root');
@@ -593,6 +594,19 @@ function workspaceHead(workspaceRoot) {
   }
 }
 
+// What belongs to one attempt at a job and goes when the next attempt starts: the pull request link
+// and any merge evidence. A new attempt starts when a job is claimed from open (claimTask, and the
+// claim a `do` stage makes), or when work is handed in on a job nobody holds (readyTask on an open
+// job), or when a `do` stage takes over a job nobody owns. A job sent back for changes that the
+// same builder still holds and fixes is the same attempt and keeps them, and so is a review pass.
+// The sent-back note and the approval mark stay: the next builder needs to read them. (The review
+// record, ATTEMPT_RECORD_KEYS, is a separate matter: a let-go claim and a reopen clear that.)
+const NEW_ATTEMPT_KEYS = ['pull_request', 'merge_commit'];
+// The same removal as one SQL expression over the metadata column, for a write that must not read the
+// row first. Metadata that is not JSON, or has neither key, comes through exactly as it was.
+const NEW_ATTEMPT_PATHS = NEW_ATTEMPT_KEYS.map((key) => `'$.${key}'`);
+const NEW_ATTEMPT_METADATA_SQL = `CASE WHEN json_valid(metadata) THEN CASE WHEN ${NEW_ATTEMPT_PATHS.map((jsonPath) => `json_type(metadata, ${jsonPath}) IS NOT NULL`).join(' OR ')} THEN json_remove(metadata, ${NEW_ATTEMPT_PATHS.join(', ')}) ELSE metadata END ELSE metadata END`;
+
 // One row change and its history entry are one transaction: both are in the store or neither is, so nobody can see,
 // or compare against, a job whose row says one thing and whose history says another, and a history write that fails
 // takes the row change back with it. BEGIN IMMEDIATE takes the write lock first, so what the writer read is still
@@ -641,13 +655,18 @@ function claimTask(db, { id, claimedBy, leaseMinutes, leasePid }) {
   if (!id) throw new Error('id required');
   if (!claimedBy) throw new Error('claimedBy required');
   const now = Date.now();
+  // A claim from open starts a new attempt, and a new attempt starts with no pull request link and
+  // no merge commit: they belong to the attempt that wrote them, and a hand-in that names no pull
+  // request must not carry the last attempt's forward (see NEW_ATTEMPT_KEYS). The same single
+  // write that takes the claim drops them, so no reader sees a claimed row with the old link.
   const stmt = db.prepare(`
     UPDATE tasks
        SET status = 'claimed',
            claimed_by = ?,
            claimed_at = ?,
            updated_at = ?,
-           metadata = CASE WHEN ? IS NULL THEN metadata ELSE json_set(COALESCE(metadata, '{}'), '$.lease', json(?)) END
+           metadata = CASE WHEN ? IS NULL THEN ${NEW_ATTEMPT_METADATA_SQL}
+                      ELSE json_set(COALESCE(${NEW_ATTEMPT_METADATA_SQL}, '{}'), '$.lease', json(?)) END
      WHERE id = ?
        AND status = 'open'
   `);
@@ -768,6 +787,7 @@ function expireLeases(db, { now = Date.now(), staleDays, claimer, dryRun = false
     try {
       const nextMetadata = metadata && typeof metadata === 'object' ? { ...metadata } : {};
       delete nextMetadata.lease;
+      for (const key of LET_GO_RESET_KEYS) delete nextMetadata[key];
       const changed = db.prepare(`UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, updated_at = ?, metadata = ? WHERE id = ? AND status = 'claimed' AND claimed_by = ? AND updated_at = ? AND metadata IS ? AND (SELECT MAX(created_at) FROM task_events WHERE task_id = tasks.id) IS ?`)
         .run(Date.now(), JSON.stringify(nextMetadata), row.id, row.claimed_by, row.updated_at, row.metadata, row.last_seen_at);
       if (changed.changes === 1) {
@@ -916,20 +936,22 @@ function releaseTaskInTransaction(db, { id, actor, expectedUpdatedAt, reason, ki
   const releaseReason = compactEpisodeText(reason, RELEASE_REASON_MAX);
   const now = Date.now();
   const named = claimEventId ? String(claimEventId) : null;
+  // The lease, and the last attempt's record (see LET_GO_RESET_KEYS), are removed in the one write.
+  const dropped = ['$.lease', ...LET_GO_RESET_KEYS.map((key) => `$.${key}`)];
   const result = withBusyRetry(() => db.prepare(`
     UPDATE tasks
        SET status = 'open',
            claimed_by = NULL,
            claimed_at = NULL,
            updated_at = ?,
-           metadata = CASE WHEN json_valid(metadata) THEN json_remove(metadata, '$.lease') ELSE metadata END
+           metadata = CASE WHEN json_valid(metadata) THEN json_remove(metadata, ${dropped.map(() => '?').join(', ')}) ELSE metadata END
      WHERE id = ?
        AND status = 'claimed'
        AND claimed_by = ?
        AND claimed_at IS ?
        AND (? IS NULL OR updated_at = ?)
        ${NAMED_CLAIM_SQL}
-  `).run(now, id, actor, row.claimed_at ?? null, expectedUpdatedAt ?? null, expectedUpdatedAt ?? null, named, named));
+  `).run(now, ...dropped, id, actor, row.claimed_at ?? null, expectedUpdatedAt ?? null, expectedUpdatedAt ?? null, named, named));
   if (result.changes !== 1) {
     // The job changed between the look and the write. A caller that named its claim is told what the job is now.
     if (named) {
@@ -957,6 +979,40 @@ function releaseTaskInTransaction(db, { id, actor, expectedUpdatedAt, reason, ki
   return { released: true, row: updated, event };
 }
 
+// What a finished attempt leaves on a row: its builder, its review record, its certification, its
+// accepted and archived marks. A job sent back to open starts its next attempt without them, so a
+// pass the last builder earned never counts toward the next builder's certification, and the last
+// builder's name is not the one the next builder's passes are judged against (a pass by anyone but
+// the builder on file certifies, so a stale name lets the next builder certify its own work).
+const ATTEMPT_RECORD_KEYS = [
+  'accepted_at',
+  'accepted_by',
+  'agent_certification_policy',
+  'agent_certified',
+  'agent_certified_at',
+  'agent_certified_by',
+  'agent_review_actors',
+  'agent_review_pass_count',
+  'agent_reviewed_at',
+  'agent_reviewed_by',
+  'approval_status',
+  'archived_at',
+  'archived_by',
+  'archived_from',
+  'archived_reason',
+  'built_by',
+  'independent_review_by',
+  'latest_agent_lesson',
+  'latest_agent_next_task',
+  'latest_agent_proof',
+];
+
+// A claim let go, by its holder or because its lease ran out, leaves the job open for the next
+// builder, so the attempt's record goes too. The one mark kept is that a person sent the job back
+// for changes, which the next builder needs to see; the sent-back job keeps its builder and review
+// record only while the same builder holds it and fixes it.
+const LET_GO_RESET_KEYS = ATTEMPT_RECORD_KEYS.filter((key) => key !== 'approval_status');
+
 function reopenTask(db, { id, actor, reason, metadata: metadataPatch, fromReview = false } = {}) {
   if (!id) throw new Error('id required');
   const row = getTask(db, id);
@@ -979,28 +1035,7 @@ function reopenTask(db, { id, actor, reason, metadata: metadataPatch, fromReview
     reopened_from: row.status,
     reopen_reason: reasonText,
   };
-  for (const key of [
-    'accepted_at',
-    'accepted_by',
-    'agent_certification_policy',
-    'agent_certified',
-    'agent_certified_at',
-    'agent_certified_by',
-    'agent_review_actors',
-    'agent_review_pass_count',
-    'agent_reviewed_at',
-    'agent_reviewed_by',
-    'approval_status',
-    'archived_at',
-    'archived_by',
-    'archived_from',
-    'archived_reason',
-    'independent_review_by',
-    'latest_agent_lesson',
-    'latest_agent_next_task',
-    'latest_agent_proof',
-    'pull_request',
-  ]) delete metadata[key];
+  for (const key of [...ATTEMPT_RECORD_KEYS, 'pull_request']) delete metadata[key];
 
   const result = withBusyRetry(() => db.prepare(`
     UPDATE tasks
@@ -1247,22 +1282,56 @@ function cleanLandingText(value) {
   return text || null;
 }
 
-// Record who delivered this review pass and answer whether certification is
-// allowed: at least one recorded pass actor must differ from the builder.
-// The first pass actor stamps built_by; judge != worker from then on.
-function recordReviewPassActor(metadata, claimedBy, rawActor) {
-  const actorNorm = reviewIntegrity.normalizeActor(
-    rawActor || process.env.ATRIS_AGENT_ID || process.env.USER || ''
-  );
-  if (!metadata.built_by && actorNorm) metadata.built_by = actorNorm;
+// Record who delivered this pass and answer whether certification is allowed: at least one
+// recorded pass actor must be someone who never built the job. `authors` is everyone on file as
+// having built it (authorsOfTask), and it is cumulative: sending the job back, letting the claim go
+// or reopening it never takes a past builder out of it. `handIn` says the call is a builder's own
+// hand-in (the job was open or claimed) and not a review pass (the job was in review); only the
+// store, which knows the job's status at the moment of the call, can tell them apart.
+//
+// built_by names a builder and nobody else: whoever handed the work in, else whoever holds the
+// claim, else the first author on file. A review pass never stamps its own actor, because the
+// reviewer did not build the job, and a machine's name (reserved) is never stamped by a hand-in
+// either, because it records passes and checks, not builds.
+function recordReviewPassActor(metadata, claimedBy, rawActor, { authors = [], handIn = false } = {}) {
+  const normalize = reviewIntegrity.normalizeActor;
+  const actorNorm = normalize(rawActor || process.env.ATRIS_AGENT_ID || process.env.USER || '');
+  const claimant = normalize(claimedBy || '');
+  const handedInBy = handIn && actorNorm && !reviewIntegrity.isReservedActor(actorNorm) ? actorNorm : '';
+  const built = new Set();
+  for (const author of authors) {
+    const name = normalize(author);
+    if (name) built.add(name);
+  }
+  if (claimant) built.add(claimant);
+  if (handedInBy) built.add(handedInBy);
+  if (!metadata.built_by) {
+    const stamp = handedInBy || claimant || [...built][0] || '';
+    if (stamp) metadata.built_by = stamp;
+  }
+  const stamped = normalize(metadata.built_by);
+  if (stamped) built.add(stamped);
   const actors = Array.isArray(metadata.agent_review_actors) ? [...metadata.agent_review_actors] : [];
   if (actorNorm && !actors.includes(actorNorm)) actors.push(actorNorm);
   metadata.agent_review_actors = actors;
-  const builder = reviewIntegrity.normalizeActor(metadata.built_by || claimedBy || '');
-  const independent = builder
-    ? (actors.find((a) => a && a !== builder) || null)
+  // With nobody on record as a builder, independence cannot be proven from one name: it takes two.
+  const independent = built.size
+    ? (actors.find((a) => a && !built.has(a)) || null)
     : (actors.length >= 2 ? actors[1] : null);
-  return { builder: builder || null, independent };
+  return { builder: stamped || claimant || null, independent };
+}
+
+// Everyone who ever built the job, from the whole history the store holds: the stamp, the claimant,
+// every claim on file and every hand-in (see reviewIntegrity.taskAuthors). A Set of normalized
+// names, empty for a row that is not there.
+function authorsOfTask(db, row) {
+  if (!row || typeof row !== 'object') return new Set();
+  const events = row.id
+    ? db.prepare("SELECT event_type, actor, payload FROM task_events WHERE task_id = ? AND event_type IN ('claimed', 'proof_ready') ORDER BY version")
+      .all(row.id)
+      .map((event) => ({ event_type: event.event_type, actor: event.actor, payload: safeJSON(event.payload) }))
+    : [];
+  return reviewIntegrity.taskAuthors({ metadata: row.metadata, claimed_by: row.claimed_by, events });
 }
 
 // A merge the caller confirmed. The commit id is required; the other fields
@@ -1278,6 +1347,9 @@ function cleanMergeRecord(merge) {
   if (/^https?:\/\//i.test(url)) record.url = url;
   const mergedAt = String(merge.merged_at || '').trim();
   if (mergedAt && Number.isFinite(Date.parse(mergedAt))) record.merged_at = mergedAt;
+  // Who merged it, as GitHub names them: a login or a bot name, one word.
+  const mergedBy = String(merge.merged_by || '').trim();
+  if (/^[A-Za-z0-9][A-Za-z0-9_.\-\[\]/]{0,63}$/.test(mergedBy)) record.merged_by = mergedBy;
   return record;
 }
 
@@ -1293,107 +1365,395 @@ function cleanOpenPullRequest(pr) {
   return record.number || record.url ? record : null;
 }
 
-function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, merge = null, resultTrace, result: resultSentence, reason, workRoot }) {
+// The names a hand-in gives for the others who built the work with its actor: a list of names, each
+// written the one way names are compared, with the actor's own name, a machine's name (they record
+// passes and checks, never builds), blanks, repeats and anything that is not a name left out. Not a
+// list means no names: a string is not split.
+function cleanBuiltWith(builtWith, handedInBy) {
+  const names = [];
+  for (const value of Array.isArray(builtWith) ? builtWith : []) {
+    if (typeof value !== 'string') continue;
+    const name = reviewIntegrity.normalizeActor(value);
+    if (name && name !== handedInBy && !reviewIntegrity.isReservedActor(name) && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+// Why a job cannot be handed in or given a pass: it is not there, or it has left the board. Null when it can.
+function readyRefusal(row) {
+  if (!row) return { ready: false, reason: 'not_found' };
+  if (!['open', 'claimed', 'review'].includes(row.status)) return { ready: false, reason: `already_${row.status}` };
+  return null;
+}
+
+// How many times a person has sent the job back. A job sent back and handed in again is in the same state with the
+// same holder, so this is what tells it from the job a caller looked at before the send-back.
+function sentBackCount(row) {
+  const count = Number(row && row.metadata && row.metadata.human_revision_count || 0);
+  return Number.isFinite(count) ? count : 0;
+}
+
+// A hand-in (the job was open or claimed) or a review pass (it was in review), written as one transaction with its
+// history entry. A call that has to wait for the write lock waits while the world goes on: a person sends the job
+// back, its builder hands it in again, another pass lands. So the look taken before the lock only turns away a job
+// that is plainly not ready-able without a wait, and notes the claim the caller saw. It is never what is written.
+// Once the lock is held the job and everyone on record as having built it are read again, and every decision is made
+// from those reads: hand-in or pass, a new attempt or not, the pass count, who is independent, and which pull request
+// and commit stay on the job. A job that is not the one the caller saw is refused: its status, its holder, the time
+// of its claim and the number of times a person sent it back must all be the same. So a call made as a pass is never
+// turned into a hand-in by the wait, nor a hand-in into a pass, and a pass that looked at work a person has since
+// sent back for changes is not counted on the work that came after. Only the git head is read before the lock,
+// because a slow git must not hold it.
+function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, merge = null, resultTrace, result: resultSentence, reason, workRoot, builtWith }) {
   if (!id) throw new Error('id required');
   const text = String(proof || '').trim();
   if (!text) throw new Error('proof required');
-  const row = getTask(db, id);
-  if (!row) return { ready: false, reason: 'not_found' };
-  if (!['open', 'claimed', 'review'].includes(row.status)) {
-    return { ready: false, reason: `already_${row.status}` };
-  }
-  const now = Date.now();
-  const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
-  delete metadata.lease;
-  const reviewPassCount = Number(metadata.agent_review_pass_count || 0) + 1;
-  metadata.approval_status = 'pending';
-  metadata.agent_review_pass_count = reviewPassCount;
-  metadata.agent_reviewed_at = new Date(now).toISOString();
-  metadata.agent_reviewed_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
-  metadata.latest_agent_proof = text;
-  metadata.latest_agent_lesson = String(lesson || '').trim() || null;
-  metadata.latest_agent_next_task = String(nextTask || '').trim() || null;
-  const resultText = cleanLandingText(resultSentence);
-  if (resultText) metadata.result = resultText;
-  const reasonText = cleanLandingText(reason);
-  if (reasonText) metadata.result_reason = reasonText;
-  const landingInput = landing && typeof landing === 'object' ? landing : {};
-  for (const key of ['happened', 'checked', 'tested', 'decision']) {
-    const cleaned = cleanLandingText(landingInput[key]);
-    if (cleaned) metadata[`landing_${key}`] = cleaned;
-  }
-  const mergeRecord = cleanMergeRecord(merge);
-  if (mergeRecord) metadata.merge_commit = mergeRecord.merge_commit;
-  const openPullRequest = mergeRecord ? null : cleanOpenPullRequest(merge);
-  // The row keeps the newest word on its pull request, so a reader that sees only
-  // the row (auto-accept, a compact list) can tell a job waiting on a person from
-  // one that landed. A review pass that names no pull request leaves it as it was.
-  if (mergeRecord) metadata.pull_request = { state: 'merged', ...mergeRecord };
-  else if (openPullRequest) metadata.pull_request = openPullRequest;
+  const seen = getTask(db, id);
+  const turnedAway = readyRefusal(seen);
+  if (turnedAway) return turnedAway;
   // Only the builder's own ready names the work's commit. A reviewer or the
   // autoland verifier re-runs the check from its own checkout; stamping that
   // checkout's HEAD would name a commit the builder never made. No actor, or
   // no builder on record, means nobody can vouch for HEAD, so nothing is stamped.
-  // A builder working in its own copy passes that copy as workRoot.
-  if (actor && row.claimed_by && actor === row.claimed_by && !reviewIntegrity.isReservedActor(actor)) {
-    const head = workspaceHead(workRoot || row.workspace_root);
-    if (head) metadata.work_commit = head;
-  }
-  const passRecord = recordReviewPassActor(metadata, row.claimed_by, actor);
-  if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES && passRecord.independent) {
-    metadata.agent_certified = true;
-    metadata.agent_certified_at = new Date(now).toISOString();
-    metadata.agent_certified_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
-    metadata.agent_certification_policy = `${AGENT_CERTIFICATION_REVIEW_PASSES}_agent_review_passes`;
-    metadata.independent_review_by = passRecord.independent;
-  }
-  const result = withBusyRetry(() => db.prepare(`
-    UPDATE tasks
-       SET status = 'review',
-           done_at = NULL,
-           updated_at = ?,
-           metadata = ?
-     WHERE id = ?
-       AND status = ? AND claimed_by IS ? AND claimed_at IS ?
-  `).run(now, JSON.stringify(metadata), id, row.status, row.claimed_by, row.claimed_at));
-  if (result.changes !== 1) return { ready: false, reason: 'claim changed hands' };
-  const updated = getTask(db, id);
-  const payload = {
-    proof: text,
-    lesson: metadata.latest_agent_lesson,
-    next_task: metadata.latest_agent_next_task,
-    approval_status: 'pending',
-    review_pass_count: reviewPassCount,
-    agent_certified: metadata.agent_certified === true,
-    agent_certification_policy: metadata.agent_certification_policy || null,
-    result: metadata.result || null,
+  // A builder working in its own copy passes that copy as workRoot. The head is
+  // asked for here, and whether it is stamped is settled below, once the lock is held.
+  const head = actor && seen.claimed_by && actor === seen.claimed_by && !reviewIntegrity.isReservedActor(actor)
+    ? workspaceHead(workRoot || seen.workspace_root)
+    : null;
+  return inWriteTransaction(db, () => {
+    const row = getTask(db, id);
+    const gone = readyRefusal(row);
+    if (gone) return gone;
+    if (row.status !== seen.status || row.claimed_by !== seen.claimed_by || row.claimed_at !== seen.claimed_at || sentBackCount(row) !== sentBackCount(seen)) {
+      return { ready: false, reason: 'claim changed hands' };
+    }
+    const now = Date.now();
+    const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
+    delete metadata.lease;
+    // A job in review is getting a review pass; an open or claimed one is getting its builder's hand-in.
+    const handIn = row.status !== 'review';
+    // A hand-in may also name the others who built the work with its actor: a flight that ran for a
+    // member hands in under the member's name, and the engines that actually built it are named here.
+    // Only a hand-in names builders, a review pass names none.
+    const handedInBy = handIn ? reviewIntegrity.normalizeActor(actor || process.env.ATRIS_AGENT_ID || process.env.USER || '') : '';
+    const builtWithNames = handIn ? cleanBuiltWith(builtWith, handedInBy) : [];
+    // Work handed in on a job nobody holds is a new attempt: the last attempt's pull request link and
+    // merge commit are not this one's, so a hand-in that names no pull request carries none forward.
+    if (row.status === 'open' || (row.status === 'claimed' && !row.claimed_by)) {
+      for (const key of NEW_ATTEMPT_KEYS) delete metadata[key];
+    }
+    const reviewPassCount = Number(metadata.agent_review_pass_count || 0) + 1;
+    metadata.approval_status = 'pending';
+    metadata.agent_review_pass_count = reviewPassCount;
+    metadata.agent_reviewed_at = new Date(now).toISOString();
+    metadata.agent_reviewed_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+    metadata.latest_agent_proof = text;
+    metadata.latest_agent_lesson = String(lesson || '').trim() || null;
+    metadata.latest_agent_next_task = String(nextTask || '').trim() || null;
+    const resultText = cleanLandingText(resultSentence);
+    if (resultText) metadata.result = resultText;
+    const reasonText = cleanLandingText(reason);
+    if (reasonText) metadata.result_reason = reasonText;
+    const landingInput = landing && typeof landing === 'object' ? landing : {};
+    for (const key of ['happened', 'checked', 'tested', 'decision']) {
+      const cleaned = cleanLandingText(landingInput[key]);
+      if (cleaned) metadata[`landing_${key}`] = cleaned;
+    }
+    const mergeRecord = cleanMergeRecord(merge);
+    if (mergeRecord) metadata.merge_commit = mergeRecord.merge_commit;
+    const openPullRequest = mergeRecord ? null : cleanOpenPullRequest(merge);
+    // The row keeps the newest word on its pull request, so a reader that sees only
+    // the row (auto-accept, a compact list) can tell a job waiting on a person from
+    // one that landed. A review pass that names no pull request leaves it as it was.
+    if (mergeRecord) metadata.pull_request = { state: 'merged', ...mergeRecord };
+    else if (openPullRequest) metadata.pull_request = openPullRequest;
+    if (head && actor && row.claimed_by && actor === row.claimed_by && !reviewIntegrity.isReservedActor(actor)) {
+      metadata.work_commit = head;
+    }
+    const passRecord = recordReviewPassActor(metadata, row.claimed_by, actor, { authors: new Set([...authorsOfTask(db, row), ...builtWithNames]), handIn });
+    if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES && passRecord.independent) {
+      metadata.agent_certified = true;
+      metadata.agent_certified_at = new Date(now).toISOString();
+      metadata.agent_certified_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+      metadata.agent_certification_policy = `${AGENT_CERTIFICATION_REVIEW_PASSES}_agent_review_passes`;
+      metadata.independent_review_by = passRecord.independent;
+    }
+    const payload = {
+      proof: text,
+      lesson: metadata.latest_agent_lesson,
+      next_task: metadata.latest_agent_next_task,
+      approval_status: 'pending',
+      review_pass_count: reviewPassCount,
+      agent_certified: metadata.agent_certified === true,
+      agent_certification_policy: metadata.agent_certification_policy || null,
+      result: metadata.result || null,
+    };
+    if (resultTrace && typeof resultTrace === 'object') {
+      payload.result_trace = resultTrace;
+      payload.result_packet = `TASK_RESULT_TRACE ${JSON.stringify(resultTrace)}`;
+    }
+    payload.landing = {
+      happened: metadata.landing_happened || null,
+      checked: metadata.landing_checked || null,
+      tested: metadata.landing_tested || null,
+      decision: metadata.landing_decision || null,
+    };
+    if (mergeRecord) {
+      payload.landing.merge_commit = mergeRecord.merge_commit;
+      payload.pull_request = { state: 'merged', ...mergeRecord };
+      // Landed by the flight with no person in the loop.
+      if (merge.self_landed === true) payload.self_landed = true;
+    } else if (openPullRequest) {
+      payload.pull_request = openPullRequest;
+    }
+    // The hand-in is written down as one, so the job's history says who built it for good, whatever
+    // happens to the row after (a send-back, a let-go claim, a reopen). A review pass leaves no such
+    // mark, and neither does a machine's name: it records passes and checks, never builds.
+    if (handIn) {
+      if (handedInBy && !reviewIntegrity.isReservedActor(handedInBy)) payload.handed_in_by = handedInBy;
+      if (builtWithNames.length) payload.built_with = builtWithNames;
+    }
+    // The row and its entry are one write, so the entry is in the store the moment the job shows as handed in, with
+    // the engines that built it. Saved one after the other, a stop between the two lost those names for good, and a
+    // look landing in the gap could count one of the engines as an independent check. The guard in the statement
+    // holds the write to the row that was read: a row that changed since is refused.
+    const result = withBusyRetry(() => db.prepare(`
+      UPDATE tasks
+         SET status = 'review',
+             done_at = NULL,
+             updated_at = ?,
+             metadata = ?
+       WHERE id = ?
+         AND status = ? AND claimed_by IS ? AND claimed_at IS ?
+    `).run(now, JSON.stringify(metadata), id, row.status, row.claimed_by, row.claimed_at));
+    if (result.changes !== 1) return { ready: false, reason: 'claim changed hands' };
+    const updated = getTask(db, id);
+    const event = appendTaskEvent(db, {
+      taskId: id,
+      workspaceRoot: updated.workspace_root,
+      actor: actor || null,
+      eventType: 'proof_ready',
+      payload,
+    });
+    return { ready: true, event, row: updated };
+  });
+}
+
+// A held job: done and handed in (status review), still under its builder's name, with the
+// pull request it opened still open and waiting for a person to land it. The row names that
+// pull request by number, by link, or both. Null for any other row.
+function heldPullRequestOf(row) {
+  if (!row || row.status !== 'review' || !row.claimed_by) return null;
+  const metadata = row.metadata && typeof row.metadata === 'object' ? row.metadata : null;
+  const pullRequest = metadata && metadata.pull_request;
+  if (!pullRequest || typeof pullRequest !== 'object' || pullRequest.merge_commit || pullRequest.merged_at) return null;
+  if (String(pullRequest.state || '').toLowerCase() !== 'open') return null;
+  const number = Number(pullRequest.number);
+  const url = String(pullRequest.url || '').trim();
+  const held = {
+    number: Number.isInteger(number) && number > 0 ? number : null,
+    url: /^https?:\/\//i.test(url) ? url : null,
   };
-  if (resultTrace && typeof resultTrace === 'object') {
-    payload.result_trace = resultTrace;
-    payload.result_packet = `TASK_RESULT_TRACE ${JSON.stringify(resultTrace)}`;
-  }
-  payload.landing = {
-    happened: metadata.landing_happened || null,
-    checked: metadata.landing_checked || null,
-    tested: metadata.landing_tested || null,
-    decision: metadata.landing_decision || null,
+  return held.number || held.url ? held : null;
+}
+
+// Which pull request a caller means: the repository as owner/name (any case) and the number (a
+// whole number, or digits). Anything else is a caller's mistake, not a pull request.
+function pullRequestIdentity(pullRequest) {
+  const repo = String((pullRequest && pullRequest.repo) || '').trim().toLowerCase();
+  const raw = pullRequest && pullRequest.number;
+  const number = typeof raw === 'number' || (typeof raw === 'string' && /^\d+$/.test(raw.trim())) ? Number(raw) : NaN;
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repo) || !Number.isSafeInteger(number) || number <= 0) {
+    throw new Error('pullRequest required: the repository as owner/name and the pull request number');
+  }
+  return { repo, number };
+}
+
+// One pull request, one landing. Whether some other job has this pull request, as { id, how }, or
+// null when none does:
+//   landed  a job already landed with it: its row says the pull request merged (in any status, so a
+//           job accepted or archived since still counts), or its history does (a hand-in or a landing
+//           that recorded the merge, which a reopen no longer shows on the row). This counts for every
+//           job, `exceptId` included: a job cannot land with one pull request twice.
+//   live    a job still on the board (open, claimed or in review) names it on its row, however the
+//           link is decorated, in whatever state the link says. `exceptId` is the job asking.
+// The search spans every workspace, because a pull request is one thing on GitHub whichever folder
+// the job came from. A row that names only a number names no repository, so it is not matched.
+// What is compared is what each link names (repository and number, read the one way every link is
+// read), never how its text is spelled: the candidates are every job and every hand-in or landing
+// mark that records a pull request at all, and each link is parsed before it is compared. Looking
+// for the text `/pull/4707` would miss the same pull request written `/pull/0004707`.
+function pullRequestTakenBy(db, { repo, number, exceptId = null } = {}) {
+  const wanted = pullRequestIdentity({ repo, number });
+  const isWanted = (link) => {
+    const named = pullRequestOfLink(link);
+    return Boolean(named) && named.repo === wanted.repo && named.number === wanted.number;
   };
-  if (mergeRecord) {
-    payload.landing.merge_commit = mergeRecord.merge_commit;
-    payload.pull_request = { state: 'merged', ...mergeRecord };
-    // Landed by the flight with no person in the loop.
-    if (merge.self_landed === true) payload.self_landed = true;
-  } else if (openPullRequest) {
-    payload.pull_request = openPullRequest;
+  const merged = (record) => Boolean(record) && typeof record === 'object'
+    && (String(record.state || '').toLowerCase() === 'merged' || Boolean(record.merge_commit) || Boolean(record.merged_at));
+  // Broad on purpose: whatever records a pull request, read by SQLite as JSON (so escapes and
+  // spacing do not matter), then read exactly below. Rows that are not JSON record nothing.
+  const recordsPullRequest = (column) => `CASE WHEN json_valid(${column}) THEN json_type(${column}, '$.pull_request') END = 'object'`;
+  let live = null;
+  const rows = db.prepare(`SELECT id, status, metadata FROM tasks WHERE ${recordsPullRequest('metadata')} ORDER BY created_at, id`).all();
+  for (const row of rows) {
+    const metadata = safeJSON(row.metadata);
+    const record = metadata && typeof metadata === 'object' ? metadata.pull_request : null;
+    if (!record || typeof record !== 'object' || !isWanted(record.url)) continue;
+    if (merged(record)) return { id: row.id, how: 'landed' };
+    if (!live && row.id !== exceptId && OPEN_TASK_STATUSES.has(row.status)) live = { id: row.id, how: 'live' };
+  }
+  const events = db.prepare(`SELECT task_id, payload FROM task_events WHERE event_type IN ('proof_ready', 'completed') AND ${recordsPullRequest('payload')} ORDER BY created_at, version`).all();
+  for (const event of events) {
+    const payload = safeJSON(event.payload);
+    const record = payload && typeof payload === 'object' ? payload.pull_request : null;
+    if (record && typeof record === 'object' && isWanted(record.url) && merged(record)) return { id: event.task_id, how: 'landed' };
+  }
+  return live;
+}
+
+// The two writers below settle a held job from what GitHub said. Each takes `expected`, what the
+// caller read before it asked GitHub (when the row last changed, who holds it, which pull request
+// it names), and writes only if the row is still exactly that: GitHub answers slowly, and a job
+// someone archived, accepted or re-sent with a new pull request in the meantime is not the one
+// that was asked about. The check and the write share one transaction, so nothing slips between.
+function heldRowToSettle(db, { id, ws, expected }) {
+  const row = getTask(db, id);
+  if (!row) return { reason: 'not_found' };
+  if (!rowInWorkspace(row, ws)) return { reason: 'not_in_workspace' };
+  if (row.status !== 'review') return { reason: `already_${row.status}` };
+  const held = heldPullRequestOf(row);
+  if (!held) return { reason: 'not_held' };
+  const sameUpdate = Number(expected.updatedAt) === Number(row.updated_at);
+  const sameHolder = (expected.claimedBy ?? null) === row.claimed_by;
+  const samePullRequest = (expected.pullRequestUrl ?? null) === held.url;
+  if (!sameUpdate || !sameHolder || !samePullRequest) return { reason: 'stale_task_state' };
+  return { row, held };
+}
+
+function requireSettleArguments({ id, actor, ws, expected, pullRequest }) {
+  if (!id) throw new Error('id required');
+  if (!actor) throw new Error('actor required');
+  if (!ws) throw new Error('workspaceRoot required');
+  if (!expected || typeof expected !== 'object') {
+    throw new Error('expected required: what the caller read about the job before it asked GitHub');
   }
-  const event = appendTaskEvent(db, {
-    taskId: id,
-    workspaceRoot: updated.workspace_root,
-    actor: actor || null,
-    eventType: 'proof_ready',
-    payload,
+  return pullRequestIdentity(pullRequest);
+}
+
+// What a settle that stopped because another job has the pull request tells its caller.
+const takenDetail = (taken) => ({ taken_by: taken.id, taken_how: taken.how });
+
+// Inside one transaction: check the row, check that no other job has the pull request (the same
+// look the caller made before it asked GitHub, made again where nothing can slip in after it), then
+// let the caller write. Rolls back on any error.
+function settleHeldJob(db, { id, ws, expected, pullRequest }, write) {
+  withBusyRetry(() => db.exec('BEGIN IMMEDIATE'));
+  try {
+    const found = heldRowToSettle(db, { id, ws, expected });
+    let out;
+    if (!found.row) {
+      out = { refused: found.reason };
+    } else {
+      const taken = pullRequestTakenBy(db, { ...pullRequest, exceptId: id });
+      out = taken ? { refused: 'pull_request_taken', taken } : write(found);
+    }
+    db.exec('COMMIT');
+    return out;
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch { /* the transaction is already gone */ }
+    throw err;
+  }
+}
+
+// A person merged the held job's pull request. Record the merge the way any landed merge is
+// recorded (merge commit, pull request merged, merged at, who merged it) and close the job as
+// done with the action "merged", which the rating reads as landed by whoever held the claim.
+// A person's merge is the acceptance, so this is not a review pass: it adds no pass, certifies
+// nothing and stamps no accepted mark, and the review record stays exactly as the builder left it.
+// The event carries landed_at, the time of the merge, which the rating dates the landing by.
+// `pullRequest` ({ repo, number }) is the pull request GitHub answered for. One pull request, one
+// landing: if another job already landed with it, or another live job also points at it, nothing is
+// written and the answer is { landed: false, reason: 'pull_request_taken', taken_by, taken_how }.
+function landHeldMerge(db, { id, actor, workspaceRoot: ws, expected, pullRequest, merge, proof } = {}) {
+  const identity = requireSettleArguments({ id, actor, ws, expected, pullRequest });
+  const mergeRecord = cleanMergeRecord(merge);
+  // The landing is dated when the merge happened, so a merge with no usable time cannot be recorded.
+  if (!mergeRecord || !mergeRecord.merged_at) return { landed: false, reason: 'invalid_merge_record' };
+  const out = settleHeldJob(db, { id, ws, expected, pullRequest: identity }, ({ row }) => {
+    const now = Math.max(Date.now(), Number(row.updated_at || 0) + 1);
+    const metadata = { ...row.metadata };
+    delete metadata.lease;
+    metadata.merge_commit = mergeRecord.merge_commit;
+    metadata.pull_request = { state: 'merged', ...mergeRecord };
+    const changed = db.prepare(`
+      UPDATE tasks
+         SET status = 'done', done_at = ?, updated_at = ?, metadata = ?
+       WHERE id = ? AND status = 'review' AND claimed_by IS ? AND updated_at = ?
+    `).run(now, now, JSON.stringify(metadata), id, row.claimed_by, row.updated_at);
+    if (changed.changes !== 1) return { refused: 'stale_task_state' };
+    const event = appendTaskEvent(db, {
+      taskId: id,
+      workspaceRoot: row.workspace_root,
+      actor,
+      eventType: 'completed',
+      // landed_at is when the merge happened: the rating dates the landing by it, not by the day
+      // this was written down, so sweeping an old merge in later does not make it count as new.
+      payload: { status: 'done', action: 'merged', pull_request: metadata.pull_request, landed_at: mergeRecord.merged_at },
+    });
+    return { row: getTask(db, id), event };
   });
-  return { ready: true, event, row: updated };
+  if (out.refused) return { landed: false, reason: out.refused, ...(out.taken ? takenDetail(out.taken) : {}) };
+  // The landing is on file. The journal line is a courtesy, and a failure to write it must not
+  // undo or hide a landing that already counts.
+  let logs = {};
+  try {
+    logs = appendTaskCompletionLogs(db, out.row, {
+      status: 'done',
+      actor,
+      action: 'merged',
+      proof: proof || `pull request ${mergeRecord.number || ''} was merged${mergeRecord.merged_by ? ` by ${mergeRecord.merged_by}` : ''}`.replace(/\s+/g, ' '),
+    });
+  } catch { logs = {}; }
+  return { landed: true, row: out.row, event: out.event, logs };
+}
+
+// The held job's pull request was closed without merging, so the work did not land. Record the
+// pull request as closed and let the claim go with the reason, which the rating counts as a
+// miss for the builder (and a person can still mark the job not needed). The closed pull request
+// stays on the row, so nothing mistakes the dead attempt's open one for the next attempt's. The
+// dead attempt's review record is cleared, as a reopen clears it, so a pass the last builder
+// earned never counts toward the next builder's certification. `pullRequest` ({ repo, number }) is
+// the pull request GitHub answered for; if another job has it (see pullRequestTakenBy), nothing is
+// written and the answer is { released: false, reason: 'pull_request_taken', taken_by, taken_how }.
+function releaseClosedPullRequest(db, { id, actor, workspaceRoot: ws, expected, pullRequest, reason } = {}) {
+  const identity = requireSettleArguments({ id, actor, ws, expected, pullRequest });
+  const releaseReason = compactEpisodeText(reason, RELEASE_REASON_MAX);
+  if (!releaseReason) throw new Error('reason required');
+  const out = settleHeldJob(db, { id, ws, expected, pullRequest: identity }, ({ row, held }) => {
+    const now = Math.max(Date.now(), Number(row.updated_at || 0) + 1);
+    const closed = { state: 'closed', ...(held.number ? { number: held.number } : {}), ...(held.url ? { url: held.url } : {}) };
+    const metadata = { ...row.metadata };
+    delete metadata.lease;
+    for (const key of ATTEMPT_RECORD_KEYS) delete metadata[key];
+    metadata.pull_request = closed;
+    const changed = db.prepare(`
+      UPDATE tasks
+         SET status = 'open', claimed_by = NULL, claimed_at = NULL, done_at = NULL, updated_at = ?, metadata = ?
+       WHERE id = ? AND status = 'review' AND claimed_by IS ? AND updated_at = ?
+    `).run(now, JSON.stringify(metadata), id, row.claimed_by, row.updated_at);
+    if (changed.changes !== 1) return { refused: 'stale_task_state' };
+    const event = appendTaskEvent(db, {
+      taskId: id,
+      workspaceRoot: row.workspace_root,
+      actor,
+      eventType: 'claim_released',
+      payload: { released_by: actor, previous_claimed_by: row.claimed_by, reason: releaseReason, pull_request: closed },
+    });
+    return { row: getTask(db, id), event };
+  });
+  if (out.refused) return { released: false, reason: out.refused, ...(out.taken ? takenDetail(out.taken) : {}) };
+  return { released: true, row: out.row, event: out.event };
 }
 
 function setTaskResult(db, { id, actor, result }) {
@@ -1677,7 +2037,19 @@ function backlogPacketFromPayload(payload) {
   return lines.filter(Boolean).join('\n');
 }
 
-function stageTask(db, {
+// A `do` stage takes the claim (from open, or over a claimed job nobody holds), drops the last attempt's link and
+// merge commit, writes the stage, and writes the history entries for them: a claimed entry when this call took the
+// claim, then work_started. All of it is one transaction. Nobody sees the claim before its entry, a hand-in cannot
+// land between the two and leave a claim with no entry (the rating would tie the landing to the claim before it),
+// and an entry that cannot be saved takes the claim and the stage back with it. The job is read inside the
+// transaction too, so what `do` decides on is still true when it writes. The plan stage claims nothing and is not
+// wrapped.
+function stageTask(db, options) {
+  if (cleanStageText(options && options.stage).toLowerCase() !== 'do') return stageTaskSteps(db, options);
+  return inWriteTransaction(db, () => stageTaskSteps(db, options));
+}
+
+function stageTaskSteps(db, {
   id,
   actor,
   stage,
@@ -1797,12 +2169,16 @@ function stageTask(db, {
   if (targetStage === 'do' && workingRow.status === 'open') {
     claimedWorker = stageOwner || cleanStageText(actor) || process.env.ATRIS_AGENT_ID || process.env.USER || 'unknown';
     const claimTime = Math.max(Date.now(), Number(workingRow.updated_at || 0) + 1);
+    // Starting work on an open job is a new attempt: the last one's pull request link and merge
+    // commit are not this attempt's. The write that takes the claim drops them, so no hand-in can
+    // land between the claim and the drop and keep them (see claimTask).
     const claimed = withBusyRetry(() => db.prepare(`
       UPDATE tasks
          SET status = 'claimed',
              claimed_by = ?,
              claimed_at = ?,
-             updated_at = ?
+             updated_at = ?,
+             metadata = ${NEW_ATTEMPT_METADATA_SQL}
        WHERE id = ?
          AND status = 'open'
          AND updated_at = ?
@@ -1870,6 +2246,8 @@ function stageTask(db, {
   } else {
     const worker = workingRow && workingRow.claimed_by || stageOwner || cleanStageText(actor) || null;
     if (workingRow && workingRow.status === 'claimed' && !workingRow.claimed_by && worker) {
+      // Taking over a job nobody owns is a new attempt too.
+      for (const key of NEW_ATTEMPT_KEYS) delete metadata[key];
       result = withBusyRetry(() => db.prepare(`
         UPDATE tasks
            SET done_at = NULL,
@@ -2137,12 +2515,13 @@ function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, ca
   const reviewer = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
   const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
   const reviewerNorm = reviewIntegrity.normalizeActor(reviewer);
-  const builderNorm = reviewIntegrity.taskBuilder(row);
-  // judge != worker applies pre-acceptance only: a builder cannot positive-
-  // reward their own row while it still sits in review. Done rows are past
+  // judge != worker applies pre-acceptance only: nobody who ever built a row can positive-reward
+  // it while it still sits in review, whoever built it last (the stamped builder, the claimant, and
+  // everyone who ever claimed it or handed work in on it: see authorsOfTask). Done rows are past
   // the human gate; finish and post-acceptance XP bookkeeping stay open.
-  if (numericReward > 0 && row.status === 'review' && builderNorm && reviewerNorm && reviewerNorm === builderNorm) {
-    return { reviewed: false, reason: 'judge_equals_worker', builder: builderNorm };
+  const authors = numericReward > 0 && row.status === 'review' && reviewerNorm ? authorsOfTask(db, row) : null;
+  if (authors && authors.has(reviewerNorm)) {
+    return { reviewed: false, reason: 'judge_equals_worker', builder: reviewerNorm };
   }
   const proofText = String(proof || '').trim();
   const verifyText = cleanStageText(verify);
@@ -2200,7 +2579,7 @@ function reviewTask(db, { id, actor, reward, lesson, nextTask, proof, verify, ca
   if (reviewingPendingProof) {
     reviewPassCount += 1;
     metadata.agent_review_pass_count = reviewPassCount;
-    const passRecord = recordReviewPassActor(metadata, row.claimed_by, reviewer);
+    const passRecord = recordReviewPassActor(metadata, row.claimed_by, reviewer, { authors: authorsOfTask(db, row), handIn: false });
     if (reviewPassCount >= AGENT_CERTIFICATION_REVIEW_PASSES && passRecord.independent) {
       metadata.agent_certified = true;
       metadata.agent_certified_at = new Date(now).toISOString();
@@ -2752,6 +3131,11 @@ module.exports = {
   archiveNotNeeded,
   relabelArchivedTasks,
   readyTask,
+  authorsOfTask,
+  heldPullRequestOf,
+  pullRequestTakenBy,
+  landHeldMerge,
+  releaseClosedPullRequest,
   setTaskResult,
   reviseTask,
   stageTask,