atris 3.74.29 → 3.76.0

package/lib/task-db.js

@@ -27,7 +27,8 @@ const path = require('path');
 const crypto = require('crypto');
 const { DatabaseSync } = require('node:sqlite');
 const reviewIntegrity = require('./review-integrity');
-const { PROOF_NOT_SAVED } = require('./release-kind');
+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');
 const { isDecisionTask } = require('./task-decision');
@@ -593,45 +594,119 @@ function workspaceHead(workspaceRoot) {
   }
 }
 
-// Atomic claim. Returns { claimed: true, row } only if THIS call won the row.
-// Race-safe via single UPDATE with WHERE status='open' guard. SQLite serializes
-// writes; busy_timeout absorbs contention. Caller must check `.claimed`.
+// 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
+// true when it writes. A caller already inside a transaction of its own joins that one (db.isTransaction says so on
+// the Node versions that have it; on the others SQLite refuses to begin inside one, and that refusal says the same).
+function inWriteTransaction(db, write) {
+  if (db.isTransaction) return write();
+  try {
+    withBusyRetry(() => db.exec('BEGIN IMMEDIATE'));
+  } catch (err) {
+    if (/within a transaction/i.test(String(err && err.message))) return write();
+    throw err;
+  }
+  let result;
+  try {
+    result = write();
+    db.exec('COMMIT');
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch { /* the transaction is already gone */ }
+    throw err;
+  }
+  return result;
+}
+
+// The part of a write that holds it to one claim. The caller names a claim by its claimed event (bound twice, once
+// for the NULL test, which leaves a write that names none as it always was). The write goes through only when that
+// event is the job's latest claimed event and is no older than the row's own claim time, which is how an older CLI,
+// that saves the row first and its event a moment later, shows a claim that is not here yet. It sits inside the
+// write itself, one statement, so a claim that lands after the caller's last look is refused too, and it reads the
+// claim by its event, not by a time, which two claims can share.
+const NAMED_CLAIM_SQL = `AND (? IS NULL OR EXISTS (
+  SELECT 1 FROM task_events e
+   WHERE e.task_id = tasks.id
+     AND e.event_type = 'claimed'
+     AND e.event_id = ?
+     AND (tasks.claimed_at IS NULL OR e.created_at >= tasks.claimed_at)
+     AND e.version = (SELECT MAX(version) FROM task_events WHERE task_id = tasks.id AND event_type = 'claimed')))`;
+
+// Atomic claim. Returns { claimed: true, row, event } only if THIS call won the row; event is the claimed event
+// this claim wrote, the one name for it (see latestClaim). Race-safe via single UPDATE with WHERE status='open'
+// guard. SQLite serializes writes; busy_timeout absorbs contention. Caller must check `.claimed`.
+//
+// The row and its claimed event are written in one transaction. Before, the row was claimed first and the event
+// followed a git call later, and in that gap a late release naming the claim before could pass for the new one.
 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'
   `);
   const lease = leaseMinutes == null ? null : JSON.stringify({ until: new Date(now + leaseMinutes * 60000).toISOString(), minutes: leaseMinutes, holder: claimedBy, pid: leasePid });
-  const result = withBusyRetry(() => stmt.run(claimedBy, now, now, lease, lease, id));
-  if (result.changes === 1) {
+  const won = inWriteTransaction(db, () => {
+    const result = withBusyRetry(() => stmt.run(claimedBy, now, now, lease, lease, id));
+    if (result.changes !== 1) return null;
     let row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
-    // First claim wins: a re-claim after a revision keeps the original start.
+    // The commit the workspace sits on is read here, with the write lock held, and only for a claim that won. A claim
+    // that has to wait for the lock is made when it gets it, and a commit that landed in the checkout while it waited
+    // is part of what was there before the job began: read earlier, the start would name a commit older than the claim,
+    // and a job that made no commit could be credited with the one that landed (lib/landing-proof.js). A git that is
+    // slow to answer holds the lock for no longer than workspaceHead lets it wait.
     const startCommit = workspaceHead(row.workspace_root);
+    // First claim wins: a re-claim after a revision keeps the original start.
     const claimedMetadata = row.metadata ? safeJSON(row.metadata) || {} : {};
     if (startCommit && !claimedMetadata.start_commit) {
       claimedMetadata.start_commit = startCommit;
       withBusyRetry(() => db.prepare('UPDATE tasks SET metadata = ? WHERE id = ?').run(JSON.stringify(claimedMetadata), id));
       row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
     }
-    appendTaskEvent(db, {
+    const event = appendTaskEvent(db, {
       taskId: id,
       workspaceRoot: row.workspace_root,
       actor: claimedBy,
       eventType: 'claimed',
       payload: { claimed_by: claimedBy, ...(startCommit ? { start_commit: startCommit } : {}) },
     });
-    const enriched = { ...row, metadata: row.metadata ? safeJSON(row.metadata) : null };
-    appendTaskWorkLog(db, enriched, { actor: claimedBy, title: 'Task claimed' });
-    return { claimed: true, row: enriched };
+    return { row, event };
+  });
+  if (won) {
+    const enriched = { ...won.row, metadata: won.row.metadata ? safeJSON(won.row.metadata) : null };
+    // The work log is a note for people, written once the claim is saved. A note that cannot be written must not
+    // turn a claim that landed into an error: the caller would not learn which claim is its own.
+    try {
+      appendTaskWorkLog(db, enriched, { actor: claimedBy, title: 'Task claimed' });
+    } catch (err) {
+      if (process.env.ATRIS_DEBUG) process.stderr.write(`claim log failed: ${String(err?.message ?? err).replace(/[\r\n]+/g, ' ')}\n`);
+    }
+    return { claimed: true, row: enriched, event: won.event };
   }
   // Either id doesn't exist or status != 'open'. Tell the caller which.
   const row = db.prepare('SELECT id, status, claimed_by FROM tasks WHERE id = ?').get(id);
@@ -639,14 +714,19 @@ function claimTask(db, { id, claimedBy, leaseMinutes, leasePid }) {
   return { claimed: false, reason: 'already_' + row.status, claimed_by: row.claimed_by };
 }
 
-// Lease updates are guarded by the holder and do not create activity events.
-function setLease(db, { id, holder, minutes = 60, pid = process.pid, now = Date.now() }) {
+// Lease updates are guarded by the holder and do not create activity events. A flight also names the claim it
+// made (claimEventId, see NAMED_CLAIM_SQL): the lease is written, renewed, or cleared only while the job is
+// still held under that claim, in the same statement, so a flight that lost its job cannot replace or clear the
+// lease of the claim that came after it, even under the same builder name. One statement is one transaction,
+// and a lease has no history entry, so there is nothing more to keep together.
+function setLease(db, { id, holder, minutes = 60, pid = process.pid, now = Date.now(), claimEventId }) {
   const raw = db.prepare('SELECT metadata FROM tasks WHERE id = ?').get(id);
   const row = getTask(db, id);
   if (!row || row.metadata_unreadable || row.status !== 'claimed' || row.claimed_by !== holder) return false;
+  const named = claimEventId ? String(claimEventId) : null;
   const metadata = { ...(row.metadata || {}), lease: { until: new Date(Number(now) + minutes * 60000).toISOString(), minutes, holder, pid } };
-  return withBusyRetry(() => db.prepare("UPDATE tasks SET metadata = ? WHERE id = ? AND status = 'claimed' AND claimed_by = ? AND metadata IS ?")
-    .run(JSON.stringify(metadata), id, holder, raw.metadata)).changes === 1;
+  return withBusyRetry(() => db.prepare(`UPDATE tasks SET metadata = ? WHERE id = ? AND status = 'claimed' AND claimed_by = ? AND metadata IS ? ${NAMED_CLAIM_SQL}`)
+    .run(JSON.stringify(metadata), id, holder, raw.metadata, named, named)).changes === 1;
 }
 
 function renewLease(db, options) {
@@ -654,21 +734,23 @@ function renewLease(db, options) {
   const metadata = row && row.metadata ? safeJSON(row.metadata) : null;
   const lease = metadata && metadata.lease;
   if (!row || row.status !== 'claimed' || row.claimed_by !== options.holder || !lease || lease.holder !== options.holder || (options.pid != null && lease.pid !== options.pid)) return false;
+  const named = options.claimEventId ? String(options.claimEventId) : null;
   const minutes = options.minutes ?? lease.minutes;
   const now = options.now ?? Date.now();
   const updated = { ...metadata, lease: { until: new Date(Number(now) + minutes * 60000).toISOString(), minutes, holder: options.holder, pid: options.pid ?? lease.pid } };
-  return withBusyRetry(() => db.prepare("UPDATE tasks SET metadata = ? WHERE id = ? AND status = 'claimed' AND claimed_by = ? AND claimed_at IS ? AND metadata IS ?")
-    .run(JSON.stringify(updated), row.id, row.claimed_by, row.claimed_at, row.metadata)).changes === 1;
+  return withBusyRetry(() => db.prepare(`UPDATE tasks SET metadata = ? WHERE id = ? AND status = 'claimed' AND claimed_by = ? AND claimed_at IS ? AND metadata IS ? ${NAMED_CLAIM_SQL}`)
+    .run(JSON.stringify(updated), row.id, row.claimed_by, row.claimed_at, row.metadata, named, named)).changes === 1;
 }
 
-function clearLease(db, { id, holder }) {
+function clearLease(db, { id, holder, claimEventId }) {
   const raw = db.prepare('SELECT metadata FROM tasks WHERE id = ?').get(id);
   const row = getTask(db, id);
   if (!row || !row.metadata || !row.metadata.lease || row.metadata.lease.holder !== holder) return false;
+  const named = claimEventId ? String(claimEventId) : null;
   const metadata = { ...row.metadata };
   delete metadata.lease;
-  return withBusyRetry(() => db.prepare('UPDATE tasks SET metadata = ? WHERE id = ? AND metadata IS ?')
-    .run(JSON.stringify(metadata), id, raw.metadata)).changes === 1;
+  return withBusyRetry(() => db.prepare(`UPDATE tasks SET metadata = ? WHERE id = ? AND metadata IS ? ${NAMED_CLAIM_SQL}`)
+    .run(JSON.stringify(metadata), id, raw.metadata, named, named)).changes === 1;
 }
 
 function pidAlive(pid) {
@@ -705,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) {
@@ -743,23 +826,103 @@ function sweepExpiredLeases() {
 // line. A release that must not read as a drop (the work is done and its pull
 // request waits for a person, only the proof could not be saved) also carries a
 // kind and that pull request as fields, so the rating never has to read words.
-// Only the dispatch flight passes them, in its own process; `atris task release`
+// Only the flights pass them, in their own process; `atris task release`
 // takes neither, so a worker cannot excuse its own miss with a flag. The two go
-// together or not at all; half a marker leaves the claim held.
+// together or not at all; half a marker leaves the claim held. One kind goes
+// alone: could_not_start, for a claim let go before the engine ran, takes no
+// pull request and is refused with one.
 const RELEASE_REASON_MAX = 300;
 
 function releaseMarker(kind, pullRequest) {
   const named = kind !== undefined && kind !== null && String(kind).trim() !== '';
   if (!named && !pullRequest) return { marker: null };
+  if (named && String(kind).trim() === COULD_NOT_START && !pullRequest) return { marker: { kind: COULD_NOT_START } };
   const open = cleanOpenPullRequest(pullRequest);
   if (!named || String(kind).trim() !== PROOF_NOT_SAVED || !open) return { invalid: true };
   return { marker: { kind: PROOF_NOT_SAVED, pull_request: open } };
 }
 
-function releaseTask(db, { id, actor, expectedUpdatedAt, reason, kind, pullRequest }) {
+// The claim a job is held under now: its latest claimed event. The event id names that one claim, so a
+// flight that remembers it can tell later whether the job is still held under the claim it made, or was
+// let go and claimed again, even under the same builder name.
+function latestClaim(db, id) {
+  return db.prepare("SELECT event_id, version, actor, created_at FROM task_events WHERE task_id = ? AND event_type = 'claimed' ORDER BY version DESC LIMIT 1").get(id) || null;
+}
+
+// True when the claim event the caller names is the claim the job is held under now. claimTask writes the row and
+// its claimed event in one transaction, so here the two always agree. A claim saved by an older CLI wrote the row
+// first and its event a moment later, and in that gap the latest event is still the claim before it: an event
+// written before the row's own claim time is that older claim, not the one the row holds.
+function claimIsCurrent(row, claim, claimEventId) {
+  if (!claim || claim.event_id !== claimEventId) return false;
+  return row.claimed_at == null || Number(claim.created_at) >= Number(row.claimed_at);
+}
+
+// True when the engine was asked on the job's current claim: a build_started event sits after its latest
+// claimed event (see markBuildStarted).
+function claimMarkedStarted(db, id) {
+  const claim = latestClaim(db, id);
+  return Boolean(claim) && Boolean(db.prepare('SELECT 1 AS hit FROM task_events WHERE task_id = ? AND event_type = ? AND version > ? LIMIT 1').get(id, BUILD_STARTED, claim.version));
+}
+
+// A flight writes this right before it asks the assigned engine, on the claim it made. It is what lets the
+// store and the rating tell a claim let go before the engine ran from one let go after it: a release that
+// says could_not_start on a marked claim is an ordinary release (see releaseTask). Only the holder can mark,
+// and claimEventId, when given, names the one claim the caller made, so a run that lost its claim cannot mark
+// the next run's. Marking twice adds nothing. A refusal writes nothing.
+function markBuildStarted(db, { id, actor, claimEventId }) {
   if (!id) throw new Error('id required');
   if (!actor) throw new Error('actor required');
-  const { marker, invalid } = releaseMarker(kind, pullRequest);
+  withBusyRetry(() => db.exec('BEGIN IMMEDIATE'));
+  try {
+    const row = getTask(db, id);
+    let result;
+    if (!row) result = { marked: false, reason: 'not_found' };
+    else if (row.status !== 'claimed') result = { marked: false, reason: `already_${row.status}`, claimed_by: row.claimed_by || null };
+    else if (row.claimed_by !== actor) result = { marked: false, reason: 'held_by_other', claimed_by: row.claimed_by || null };
+    else {
+      const claim = latestClaim(db, id);
+      if (!claim) result = { marked: false, reason: 'no_claim_event' };
+      else if (claimEventId && !claimIsCurrent(row, claim, claimEventId)) result = { marked: false, reason: 'claim_changed', claimed_by: row.claimed_by || null };
+      else if (claimMarkedStarted(db, id)) result = { marked: true, already: true };
+      else {
+        result = {
+          marked: true,
+          event: appendTaskEvent(db, {
+            taskId: id,
+            workspaceRoot: row.workspace_root,
+            actor,
+            eventType: BUILD_STARTED,
+            payload: { claimed_by: actor, claim_event_id: claim.event_id },
+          }),
+        };
+      }
+    }
+    db.exec('COMMIT');
+    return result;
+  } catch (err) { db.exec('ROLLBACK'); throw err; }
+}
+
+// claimEventId, when given, names the one claim the caller made (see latestClaim). A job that was let go
+// and claimed again since, by anyone, is not the caller's to release: nothing is written. The check is part of
+// the write itself, one statement (see NAMED_CLAIM_SQL), so a claim that lands between the caller's last look and
+// the release is refused too, and it reads the claim by its event, not by a time, which two claims can share.
+//
+// The look, the row write, and the claim_released entry are one transaction (see inWriteTransaction): a history
+// entry that cannot be written takes the release back with it, so a job is never left open with no record of how,
+// and the check cannot pass against a claim whose own entry is not in the store yet.
+//
+// The could-not-start kind checks itself. It is taken only for a claim whose engine was never asked. On a
+// claim marked started (see markBuildStarted) the release goes through as an ordinary release with no kind,
+// and is not refused, so the claim is never left held.
+function releaseTask(db, release) {
+  return inWriteTransaction(db, () => releaseTaskInTransaction(db, release));
+}
+
+function releaseTaskInTransaction(db, { id, actor, expectedUpdatedAt, reason, kind, pullRequest, claimEventId }) {
+  if (!id) throw new Error('id required');
+  if (!actor) throw new Error('actor required');
+  const { marker: asked, invalid } = releaseMarker(kind, pullRequest);
   if (invalid) return { released: false, reason: 'invalid_release_marker' };
   const row = getTask(db, id);
   if (!row) return { released: false, reason: 'not_found' };
@@ -769,21 +932,37 @@ function releaseTask(db, { id, actor, expectedUpdatedAt, reason, kind, pullReque
   if (row.claimed_by !== actor) {
     return { released: false, reason: 'held_by_other', claimed_by: row.claimed_by || null };
   }
+  const marker = asked && asked.kind === COULD_NOT_START && claimMarkedStarted(db, id) ? null : asked;
   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 = ?)
-  `).run(now, id, actor, expectedUpdatedAt ?? null, expectedUpdatedAt ?? null));
-  if (result.changes !== 1) return { released: false, reason: 'stale_task_state', claimed_by: row.claimed_by || null };
+       ${NAMED_CLAIM_SQL}
+  `).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) {
+      const current = getTask(db, id);
+      if (!current) return { released: false, reason: 'not_found' };
+      if (current.status !== 'claimed') return { released: false, reason: `already_${current.status}`, claimed_by: current.claimed_by || null };
+      if (current.claimed_by !== actor) return { released: false, reason: 'held_by_other', claimed_by: current.claimed_by || null };
+      if (!claimIsCurrent(current, latestClaim(db, id), named)) return { released: false, reason: 'claim_changed', claimed_by: current.claimed_by || null };
+    }
+    return { released: false, reason: 'stale_task_state', claimed_by: row.claimed_by || null };
+  }
   const updated = getTask(db, id);
   const event = appendTaskEvent(db, {
     taskId: id,
@@ -800,6 +979,40 @@ function releaseTask(db, { id, actor, expectedUpdatedAt, reason, kind, pullReque
   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);
@@ -822,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
@@ -1090,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
@@ -1121,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;
 }
 
@@ -1136,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 };
+  });
+  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 };
   });
-  return { ready: true, event, row: updated };
+  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 }) {
@@ -1520,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,
@@ -1640,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 = ?
@@ -1713,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,
@@ -1980,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);
@@ -2043,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();
@@ -2584,6 +3120,8 @@ module.exports = {
   previewExpiredLeases,
   sweepExpiredLeases,
   releaseTask,
+  latestClaim,
+  markBuildStarted,
   reopenTask,
   backlogTask,
   clearPlanTasks,
@@ -2593,6 +3131,11 @@ module.exports = {
   archiveNotNeeded,
   relabelArchivedTasks,
   readyTask,
+  authorsOfTask,
+  heldPullRequestOf,
+  pullRequestTakenBy,
+  landHeldMerge,
+  releaseClosedPullRequest,
   setTaskResult,
   reviseTask,
   stageTask,