atris 3.74.27 → 3.74.28

package/lib/fleet.js

@@ -44,6 +44,7 @@ const { buildVerifiedScoutPack, appendVerifiedScoutPack } = require('./dispatch-
 const { runPrepPass, withPrepBrief, prepRecordFields } = require('./roster-prep');
 const { mapNotesPath } = require('./map-refs');
 const { SHARED_BRIEF_RULES } = require('./brief-rules');
+const { PROOF_NOT_SAVED } = require('./release-kind');
 const {
   applySecretGrantEnvironment,
   buildGatewaySupervisorScript,
@@ -57,6 +58,16 @@ const { recordEngineResource } = require('./engine-resource');
 // calls. Mirrors the autoland denied lanes.
 const DENIED_TAGS = ['billing', 'money', 'payments', 'deploy', 'security', 'customer', 'external', 'feedback'];
 
+// The protected lane a task sits in (a denied tag on the task or its todo
+// tags), or null. The ship gate and the dispatch flight both ask this, so they
+// cannot disagree about which work a person must land.
+function protectedLaneOfTask(task) {
+  if (!task || typeof task !== 'object') return null;
+  const todoTags = task.metadata && Array.isArray(task.metadata.todo_tags) ? task.metadata.todo_tags : [];
+  const tags = [task.tag, ...todoTags].filter(Boolean).map((tag) => String(tag).toLowerCase());
+  return tags.find((tag) => DENIED_TAGS.includes(tag)) || null;
+}
+
 // ---------------------------------------------------------------------------
 // T1: dispatch primitive
 
@@ -844,9 +855,11 @@ function rosterAttemptRecord(engineName, pin, startedMs, endedMs, result, prep =
   };
 }
 
-// After landing: the last attempt landed only when its task is in the landed
-// or proof-ready rows; otherwise it failed at the stage that paused it. Every
-// earlier attempt keeps its own outcome and names who took over.
+// After landing: the last attempt landed only when its task is in the landed or
+// proof-ready rows. A task whose pull request waits for a person is held: not a
+// landing until someone lands it, and not a failure either. Otherwise it failed
+// at the stage that paused it. Every earlier attempt keeps its own outcome and
+// names who took over.
 function recordFlightRosterRuns(root, flight, results, { job = 'build', member = '', source = '' } = {}) {
   for (const { entry, result } of results || []) {
     const attempts = (result && Array.isArray(result.attempts) ? result.attempts : []).map((attempt) => ({ ...attempt }));
@@ -855,9 +868,15 @@ function recordFlightRosterRuns(root, flight, results, { job = 'build', member =
     const sameTask = (row) => row && String(row.task) === taskId;
     const last = attempts[attempts.length - 1];
     if (last.outcome === 'landed') {
+      const held = (flight.held_for_review || []).find(sameTask);
       const landed = (flight.landed || []).some(sameTask) || (flight.ready || []).some(sameTask);
       const paused = (flight.paused || []).find(sameTask);
-      if (!landed) {
+      if (held) {
+        last.outcome = 'held';
+        last.detail = held.review_recorded === false
+          ? `pull request ${held.pull_request.url} is open but its proof could not be saved`
+          : `waiting for a person to land ${held.pull_request.url}`;
+      } else if (!landed) {
         last.outcome = 'failed';
         last.detail = paused
           ? `paused at ${String(paused.stage || 'landing').replace(/_/g, ' ')}${paused.detail ? `: ${String(paused.detail).split('\n')[0]}` : ''}`
@@ -1505,16 +1524,37 @@ function landedMergeFlags(merge) {
   return flags;
 }
 
-function fleetShipArgs(entry, check, targetRef = resolveDispatchLandTarget(entry.worktreePath || process.cwd())) {
+// task ready flags that name the pull request left open for a person to land.
+// No merge commit, so the job record shows it as waiting, not landed.
+function openPullRequestFlags(pullRequest) {
+  if (!pullRequest) return [];
+  const flags = [];
+  if (pullRequest.number) flags.push('--pr-number', String(pullRequest.number));
+  if (pullRequest.url) flags.push('--pr-url', pullRequest.url);
+  return flags;
+}
+
+// merge=false pushes the branch and opens the pull request without merging it.
+function fleetShipArgs(entry, check, targetRef = resolveDispatchLandTarget(entry.worktreePath || process.cwd()), { merge = true } = {}) {
   return [
     'worktree', 'ship',
     '--message', `${String(entry.task.title || '').split(/[.:]/)[0].slice(0, 90)} (${entry.task.display_id}, built by ${entry.engine})`,
     '--verify', check,
     '--target', targetRef,
-    '--merge',
+    ...(merge ? ['--merge'] : []),
   ];
 }
 
+// The open pull request worktree ship printed when it was not asked to merge:
+// `pr: <url>` for a new one, `pr: <number> <url>` for one that was already open.
+function shipPullRequest(stdout) {
+  const line = String(stdout || '').match(/^pr: (?:(\d+) )?(https?:\/\/\S+)\s*$/m);
+  if (!line) return null;
+  const url = line[2];
+  const number = Number(line[1] || (url.match(/\/pull\/(\d+)/) || [])[1]);
+  return { url, ...(Number.isInteger(number) && number > 0 ? { number } : {}) };
+}
+
 // A fleet build worktree is ephemeral. If any process inside one runs
 // `npm link` (which repoints the global `atris` package symlink at that
 // worktree), then removing the worktree at teardown leaves the global `atris`
@@ -1645,6 +1685,8 @@ function landArrival({ worktreePath, targetRef = resolveDispatchLandTarget(workt
 
 module.exports = {
   DENIED_TAGS,
+  protectedLaneOfTask,
+  shipPullRequest,
   DEAD_ENGINE_OUTPUT_PATTERNS,
   releasePausedClaimsWithoutWork,
   reviewOnlyEngineEnvironment,
@@ -1653,6 +1695,7 @@ module.exports = {
   shipFailureDetail,
   shipMergeRecord,
   landedMergeFlags,
+  openPullRequestFlags,
   get FLEET_CAPABLE() { return FLEET_CAPABLE; },
   get DISPATCH_CAPABLE() { return DISPATCH_CAPABLE; },
   get runFleetFlight() { return runFleetFlight; },
@@ -2820,7 +2863,9 @@ async function validateWithAttempts({
 
 function dispatchReceiptResult(flight, { ids, reviewOnly, enforceRemoteBoundary }) {
   const validatorResult = flight.validator_result || flight.result?.validator_result;
-  const successfulRows = reviewOnly ? flight.ready : flight.landed;
+  // Work on a pull request waiting for a person is neither landed nor failed.
+  const held = flight.held_for_review || [];
+  const successfulRows = reviewOnly ? flight.ready : [...flight.landed, ...held];
   const successfulVerifierRows = successfulRows
     .map((row) => row.verifier_result)
     .filter((row) => row && typeof row === 'object');
@@ -2842,12 +2887,13 @@ function dispatchReceiptResult(flight, { ids, reviewOnly, enforceRemoteBoundary
     && validatorResult.engine !== validatorResult.executor_engine;
   const passed = basePassed && (!oneLapReview || validatorPassed === true);
   const result = {
-    kind: reviewOnly ? 'dispatch_review_ready' : 'dispatch_landed',
+    kind: reviewOnly ? 'dispatch_review_ready' : (held.length && !flight.landed.length ? 'dispatch_held_for_review' : 'dispatch_landed'),
     passed,
     verifier_result: verifierRows.length === 1
       ? verifierRows[0]
       : { passed, checks: verifierRows },
   };
+  if (!reviewOnly && held.length) result.held_for_review = held.length;
   if (reviewOnly) {
     result.master_boundary_enforced = enforceRemoteBoundary;
     result.master_unchanged = enforceRemoteBoundary
@@ -2914,7 +2960,10 @@ function defaultOwnCli(root) {
 
 // A merge and its task handoff are separate writes. Keep the merge on disk
 // before attempting the handoff, and never report success if that write fails.
-function recordLandedTaskReview(cli, args, { flight, landedRow, worktree, save }) {
+// heldForReview is the same handoff for a pull request left open for a person:
+// if it fails, the paused row carries the pull request so the caller can let the
+// claim go with its link as the reason.
+function recordLandedTaskReview(cli, args, { flight, landedRow, worktree, save, heldForReview = false }) {
   landedRow.review_recorded = false;
   save();
   let result;
@@ -2926,10 +2975,12 @@ function recordLandedTaskReview(cli, args, { flight, landedRow, worktree, save }
       task: landedRow.task,
       engine: landedRow.engine,
       stage: 'task_ready',
-      landed: true,
+      ...(heldForReview ? { held_for_review: true, pull_request: landedRow.pull_request } : { landed: true }),
       worktree,
       detail: headTail(String(result && (result.stderr || result.stdout) || 'task ready failed')),
-      next_action: 'record fresh task proof with task ready; do not rebuild or merge again',
+      next_action: heldForReview
+        ? 'record fresh task proof with task ready; do not rebuild, and leave the pull request open'
+        : 'record fresh task proof with task ready; do not rebuild or merge again',
     });
     save();
     return false;
@@ -3234,22 +3285,40 @@ async function runFleetFlight({
   const prepared = [];
   const leaseDb = require('./task-db');
   const leaseConnection = leaseDb.open();
+  const workspace = leaseDb.workspaceRoot(root);
   const leased = new Map();
+  // What each claimed job is called to the task command, and who holds it, by display id. Only
+  // jobs this flight claimed are in them, so a listed job it refused cannot be mistaken for one.
+  const claimedRefs = new Map();
+  const claimedActors = new Map();
   const leaseTimer = setInterval(() => {
     for (const [id, holder] of leased) leaseDb.renewLease(leaseConnection, { id, holder, pid: process.pid });
   }, 5 * 60000);
   leaseTimer.unref();
   try {
   for (const entry of staffed) {
-    const claimed = cli(['task', 'claim', String(entry.task.display_id), '--as', `fleet-${entry.engine}`, '--lease-minutes', '60', '--lease-pid', String(process.pid)]);
+    // Only this workspace's own jobs. The list can name a job in another workspace, and the store
+    // takes its row id as readily as one of ours, so the entry's row is asked before anything is claimed.
+    if (jobOutsideWorkspace(leaseDb, entry.task, workspace)) {
+      const detail = namesAnotherWorkspace(entry.task.display_id);
+      flight.paused.push({ task: entry.task.display_id, engine: entry.engine, stage: 'other_workspace', detail });
+      log(`    ${entry.engine.padEnd(8)} ✗ ${detail}`);
+      continue;
+    }
+    // The row the list named is the row this claims, leases, proves and lets go of: named once,
+    // by its row id, at every step (see jobRef).
+    const rowRef = jobRef(entry.task, entry.task.display_id);
+    const claimed = cli(['task', 'claim', rowRef, '--as', `fleet-${entry.engine}`, '--lease-minutes', '60', '--lease-pid', String(process.pid)]);
     if (!claimed || claimed.status !== 0) {
       const detail = String(claimed && (claimed.stderr || claimed.stdout) || 'claim failed').trim().slice(0, 300);
       flight.paused.push({ task: entry.task.display_id, engine: entry.engine, stage: 'claim', detail });
       log(`    ${entry.engine.padEnd(8)} ⏸ paused ${entry.task.display_id} at claim${detail ? `, ${detail}` : ''}`);
       continue;
     }
-    const leaseId = entry.task.id || entry.task.display_id;
+    const leaseId = rowRef;
     const holder = `fleet-${entry.engine}`;
+    claimedRefs.set(String(entry.task.display_id), rowRef);
+    claimedActors.set(String(entry.task.display_id), holder);
     const leaseSet = leaseDb.setLease(leaseConnection, { id: leaseId, holder });
     if (!leaseSet && (!ownCli || leaseDb.getTask(leaseConnection, leaseId))) throw new Error('could not set claim lease');
     if (leaseSet) leased.set(leaseId, holder);
@@ -3330,7 +3399,7 @@ async function runFleetFlight({
       flight.landed.push(landedRow);
       const restaffProof = result.restaffed ? ` Restaffed from ${result.restaffed.from} to ${result.restaffed.to} (${result.restaffed.reason}).` : '';
       const reviewRecorded = recordLandedTaskReview(cli, [
-        'task', 'ready', String(entry.task.display_id),
+        'task', 'ready', jobRef(entry.task, entry.task.display_id),
         '--proof', `Built by ${activeEngine} engine in fleet flight.${restaffProof} Landed via worktree ship gate (rebase-before-ship, verify re-run). Receipt saved at ${path.relative(root, receiptPath)}. Report tail: ${headTail(String(result.report || '').replace(/\n/g, ' '))}`,
         '--result', 'Operators can now review fleet-shipped work faster because the worktree was verified before landing.',
         ...landedMergeFlags(landed.merge),
@@ -3365,7 +3434,8 @@ async function runFleetFlight({
   releasePausedClaimsWithoutWork(cli, {
     paused: flight.paused,
     worktreeByTask: new Map(prepared.map((entry) => [String(entry.task.display_id), entry.worktreePath])),
-    actorByTask: new Map(staffed.map((entry) => [String(entry.task.display_id), `fleet-${entry.engine}`])),
+    actorByTask: claimedActors,
+    refByTask: claimedRefs,
     baseRef: landTarget,
     log,
   });
@@ -3390,10 +3460,47 @@ async function runFleetFlight({
 // ---------------------------------------------------------------------------
 // T5, one-command dispatch: `atris engine dispatch <task-id> --engine <name>`
 
+// Why the flight let a claim go, in one plain line. It is saved on the release
+// so the rating can tell good work that stalled from a plain drop.
+function pausedStageLabel(stage) {
+  return String(stage || 'an unknown step').replace(/_failed$/, '').replace(/_/g, ' ');
+}
+
+function releaseReason(lead, detail) {
+  const firstLine = String(detail || '').split(/\r?\n/).map((line) => line.trim()).find(Boolean) || '';
+  return (firstLine ? `${lead}: ${firstLine}` : lead).slice(0, 300);
+}
+
+// Pauses where the engine never got to finish its turn.
+const ENGINE_DID_NOT_FINISH = new Set(['worktree_start', 'remote_quarantine', 'prepare', 'build']);
+
+// The word a flight uses to name a job to the task command at every step: its row id when the
+// task command (or the task list) gave one, else the display id the flight has. The display id a
+// person reads is not a key. The same folder name in another place gives the same ids, and the
+// list that gives an id its meaning can be written again between two commands, so a command that
+// finds a job by it again can land on another job. It names a job only when no row id came back,
+// as with a stand-in task plane.
+function jobRef(task, displayId) {
+  return task && task.id ? String(task.id) : String(displayId);
+}
+
+// A flight works only on jobs in its own workspace, and the store takes a row id from any
+// workspace, so the flight asks whose workspace the row is in before it claims anything. That is
+// the store's own rule for what a workspace holds (rowInWorkspace, the one its workspace listing
+// uses): the workspace, spelled the way the store spells it, and the git worktrees linked to it.
+// A row with no workspace is in no workspace's listing, so it is not inside this one. A job shown
+// with no row id has no row to ask about; it is named by its display id at every step.
+function jobOutsideWorkspace(taskDb, task, workspace) {
+  return Boolean(task && task.id) && !taskDb.rowInWorkspace(task, workspace);
+}
+
+const namesAnotherWorkspace = (displayId) => `${displayId} names a job in another workspace`;
+
 // A claim taken before the engine starts must not stay held if the flight
-// refuses or errors first. Release through the same task plane the claim used.
-function releaseUnstartedDispatchClaim(cli, { taskId, actor, detail }) {
-  const released = cli(['task', 'release', taskId, '--as', actor]);
+// refuses or errors first. Release through the same task plane the claim used,
+// naming the job by ref: the row id the claim named.
+function releaseUnstartedDispatchClaim(cli, { taskId, ref = taskId, actor, detail, stage }) {
+  const released = cli(['task', 'release', ref, '--as', actor, '--reason', releaseReason(`paused at ${pausedStageLabel(stage)}`, detail)]);
   const releasedOk = Boolean(released && released.status === 0);
   const suffix = releasedOk
     ? 'claim released, safe to retry'
@@ -3413,38 +3520,122 @@ function releaseUnstartedDispatchClaim(cli, { taskId, actor, detail }) {
 // nothing is working the task any more, and a kept claim made the retry
 // fail at "claim failed". The work stays on its branch and the retry's
 // worktree start resumes from it.
-function releasePausedClaimsWithoutWork(cli, { paused, worktreeByTask, actorByTask, baseRef = '', log = () => {}, keepClaimsWithWork = true }) {
+//
+// refByTask names each claimed job by the row id the flight claimed it with, so the release
+// lands on that row even if the display id a person reads now means another job. A job with
+// no entry there is named by the display id in its pause row.
+function releasePausedClaimsWithoutWork(cli, { paused, worktreeByTask, actorByTask, refByTask = new Map(), baseRef = '', log = () => {}, keepClaimsWithWork = true }) {
   for (const row of paused || []) {
-    if (row.stage === 'claim' || row.stage === 'task_lookup' || row.landed === true) continue; // no claim, or work already landed
+    // No claim (the job was never found, was refused as another workspace's, or the claim
+    // failed), work already landed, or work waiting on a pull request for a person (the flight
+    // let that claim go itself when saving its proof failed).
+    if (row.stage === 'claim' || row.stage === 'task_lookup' || row.stage === 'other_workspace' || row.landed === true || row.held_for_review === true) continue;
     if (row.claim_released !== undefined) continue;
     const taskId = String(row.task || '');
     const actor = actorByTask.get(taskId);
     if (!taskId || !actor) continue;
     const worktreePath = row.worktree || worktreeByTask.get(taskId) || '';
-    if (!keepClaimsWithWork) {
-      const released = cli(['task', 'release', taskId, '--as', actor]);
-      row.claim_released = Boolean(released && released.status === 0);
-      if (row.claim_released) log(`    released claim on ${taskId} so a retry can pick it up${worktreePath ? `; any work stays in ${path.basename(worktreePath)}` : ''}`);
-      continue;
-    }
-    if (worktreePath && fs.existsSync(worktreePath)) {
-      const resolvedBase = baseRef || defaultMainlineBase(worktreePath);
-      if (!baseRef && resolvedBase === 'HEAD') continue; // no known start point: preserve the claim
-      const ahead = spawnSync('git', ['-C', worktreePath, 'rev-list', '--count', `${resolvedBase}..HEAD`], { encoding: 'utf8' });
-      if (ahead.status !== 0 || parseInt(String(ahead.stdout).trim(), 10) > 0) continue;
-      // -uall lists untracked files one by one; the default collapses a fully
-      // untracked .atris/ into "?? .atris/", which the allowlist cannot judge.
-      const status = spawnSync('git', ['-C', worktreePath, 'status', '--porcelain', '-uall'], { encoding: 'utf8' });
-      if (status.status !== 0) continue;
-      const dirt = String(status.stdout || '').split('\n').filter(Boolean).filter((line) => !isConductorStatusLine(line));
-      if (dirt.length > 0) continue;
-    } else if (row.stage !== 'worktree_start' && row.stage !== 'remote_quarantine' && row.stage !== 'prepare') {
-      continue; // worktree gone and stage ambiguous: leave the claim for a human
-    }
-    const released = cli(['task', 'release', taskId, '--as', actor]);
+    const noWork = pausedWorktreeHasNoWork(row, worktreePath, baseRef);
+    if (keepClaimsWithWork && !noWork) continue;
+    // "No work" is for an engine that finished its turn and changed nothing. A
+    // pause before that, or a dead engine, keeps its own reason: it is not a
+    // worker saying the job was already done.
+    const reason = noWork && !ENGINE_DID_NOT_FINISH.has(row.stage)
+      ? 'engine produced no work'
+      : releaseReason(`paused at ${pausedStageLabel(row.stage)}`, row.stage === 'build' ? row.reason || row.detail : row.detail || row.reason);
+    const released = cli(['task', 'release', refByTask.get(taskId) || taskId, '--as', actor, '--reason', reason]);
     row.claim_released = Boolean(released && released.status === 0);
-    if (row.claim_released) log(`    released claim on ${taskId} (engine produced no work)`);
+    if (!row.claim_released) continue;
+    log(keepClaimsWithWork
+      ? `    released claim on ${taskId} (engine produced no work)`
+      : `    released claim on ${taskId} so a retry can pick it up${worktreePath ? `; any work stays in ${path.basename(worktreePath)}` : ''}`);
+  }
+}
+
+// A pull request is open for a person, but the proof that says so could not be
+// saved. Left alone, the claim would keep its 60 minute lease and then a sweep
+// would expire it as a plain drop, with the pull request still open. Let it go
+// now, under the name that holds it, and put the link in the reason so the
+// record points at the work.
+//
+// The release also names its kind and the pull request as fields (never read
+// back out of the reason), so the rating leaves it out of both landed and
+// missed. Only the flight can say that: it opened the pull request itself, so it
+// records the release here, in its own process, through the task store it already
+// holds for leases. `atris task release` takes no kind, because any worker holding
+// a failed job could pass one to excuse its own miss. Nothing here reads the
+// environment, so a flight started from an agent session records it the same.
+//
+// It lets go of the exact row it claimed: rowId is the id the task command showed
+// before the claim, and the claim and the lease named that same row. The display id
+// a person reads is not a key, since the same folder name in another place gives the
+// same ids, so it is never looked up again. With no row id there is nothing exact to
+// release, and nothing is.
+//
+// Tried once: if the release fails too, the row says so.
+function releaseClaimOfUnsavedPullRequest({ taskDb, db, root, row, rowId, actor, log = () => {} }) {
+  const reason = releaseReason(`PR ${row.pull_request.url} is open but its proof could not be saved`, row.detail);
+  let released = false;
+  let failure = 'unknown';
+  try {
+    if (!rowId) {
+      failure = 'the flight has no row id for it';
+    } else {
+      const result = taskDb.releaseTask(db, {
+        id: rowId,
+        actor,
+        reason,
+        kind: PROOF_NOT_SAVED,
+        pullRequest: row.pull_request,
+      });
+      if (!result.released) {
+        failure = `release failed: ${result.reason}${result.claimed_by ? ` (held by ${result.claimed_by})` : ''}`;
+      } else {
+        released = true;
+        // The two files people read are drawn again from the saved state, the way the
+        // task command does after every release: the task list file, and atris/TODO.md
+        // of the flight's own workspace. The release is already saved, so a file that
+        // cannot be written does not undo it, and one failing does not stop the other.
+        // The task command is loaded only here: this file is read on every start, and
+        // only this rare path needs it.
+        for (const [what, refresh] of [
+          ['task list file', () => require('../commands/task').writeDefaultProjection(taskDb, db, { root })],
+          ['TODO.md', () => require('../commands/task').autoRenderTodoFromDb(taskDb.workspaceRoot(root))],
+        ]) {
+          try { refresh(); } catch (err) {
+            if (process.env.ATRIS_DEBUG) process.stderr.write(`${what} refresh failed: ${String(err?.message ?? err).replace(/[\r\n]+/g, ' ')}\n`);
+          }
+        }
+      }
+    }
+  } catch (err) {
+    failure = String(err?.message ?? err).trim() || 'unknown';
+  }
+  row.claim_released = released;
+  log(row.claim_released
+    ? `    released the claim on ${row.task} with the pull request link as the reason`
+    : `    could not release the claim on ${row.task}: ${failure.replace(/\s+/g, ' ').trim().slice(0, 80)}. it stays until its lease runs out, unless the task record is repaired first.`);
+  return row.claim_released;
+}
+
+// True only when the paused task's worktree is level with its base and holds
+// nothing but conductor litter. Any doubt counts as work, so a claim is never
+// let go as "no work" while real changes may exist.
+function pausedWorktreeHasNoWork(row, worktreePath, baseRef) {
+  if (worktreePath && fs.existsSync(worktreePath)) {
+    const resolvedBase = baseRef || defaultMainlineBase(worktreePath);
+    if (!baseRef && resolvedBase === 'HEAD') return false; // no known start point
+    const ahead = spawnSync('git', ['-C', worktreePath, 'rev-list', '--count', `${resolvedBase}..HEAD`], { encoding: 'utf8' });
+    if (ahead.status !== 0 || parseInt(String(ahead.stdout).trim(), 10) > 0) return false;
+    // -uall lists untracked files one by one; the default collapses a fully
+    // untracked .atris/ into "?? .atris/", which the allowlist cannot judge.
+    const status = spawnSync('git', ['-C', worktreePath, 'status', '--porcelain', '-uall'], { encoding: 'utf8' });
+    if (status.status !== 0) return false;
+    const dirt = String(status.stdout || '').split('\n').filter(Boolean).filter((line) => !isConductorStatusLine(line));
+    return dirt.length === 0;
   }
+  // Worktree gone: only the early stages are known to hold nothing.
+  return row.stage === 'worktree_start' || row.stage === 'remote_quarantine' || row.stage === 'prepare';
 }
 
 // The manual version of this loop took 6 Bash calls per task the night this
@@ -3521,6 +3712,9 @@ async function runDispatchFlight({
   const cli = ownCli || defaultOwnCli(root);
   const leaseDb = require('./task-db');
   const leaseConnection = leaseDb.open();
+  // The workspace this flight works in, spelled the way the store spells it. It is read once, before
+  // the flight writes anything into its folder.
+  const workspace = leaseDb.workspaceRoot(root);
   try { leaseDb.expireLeases(leaseConnection); } catch (err) { if (process.env.ATRIS_DEBUG) process.stderr.write(`lease sweep failed: ${String(err?.message ?? err).replace(/[\r\n]+/g, ' ')}\n`); }
   // Cut worktrees from, and check self-landing against, the workspace's real
   // protected branch, not a hard-coded origin/master (CLI-1298).
@@ -3547,6 +3741,7 @@ async function runDispatchFlight({
     results: [],
     landed: [],
     ready: [],
+    held_for_review: [],
     paused: [],
   };
   if (yolo) flight.yolo = true;
@@ -3566,6 +3761,9 @@ async function runDispatchFlight({
   const startBaseArgs = landTarget ? ['--base', landTarget] : [];
   const prepared = [];
   const leasedIds = new Set();
+  // What each claimed job is called to the task command, by the id the caller gave. Only jobs this
+  // flight claimed are in it.
+  const claimedRefs = new Map();
   const leaseTimer = setInterval(() => {
     for (const id of leasedIds) leaseDb.renewLease(leaseConnection, { id, holder: taskActor, pid: process.pid });
   }, 5 * 60000);
@@ -3578,15 +3776,29 @@ async function runDispatchFlight({
       log(`    ✗ ${taskId} not found`);
       continue;
     }
-    const claimed = cli(['task', 'claim', taskId, '--as', taskActor, '--lease-minutes', '60', '--lease-pid', String(process.pid)]);
+    // Only this workspace's own jobs. What the task command showed can be a job in another
+    // workspace (the list it read named it under this display id), and the store takes its row id
+    // as readily as one of ours, so the row is asked before anything is claimed.
+    if (jobOutsideWorkspace(leaseDb, task, workspace)) {
+      const detail = namesAnotherWorkspace(taskId);
+      flight.paused.push({ task: taskId, stage: 'other_workspace', detail });
+      log(`    ✗ ${detail}`);
+      continue;
+    }
+    // The row the task command just showed is the row this claims, leases, proves and lets go of:
+    // named once, by its row id, at every step (see jobRef). Log lines and the receipt keep saying
+    // the display id.
+    const rowRef = jobRef(task, taskId);
+    const claimed = cli(['task', 'claim', rowRef, '--as', taskActor, '--lease-minutes', '60', '--lease-pid', String(process.pid)]);
     if (!claimed || claimed.status !== 0) {
       const detail = String(claimed && (claimed.stderr || claimed.stdout) || 'claim failed').trim().slice(0, 300);
       flight.paused.push({ task: taskId, stage: 'claim', detail });
       log(`    x ${taskId} claim failed`);
       continue;
     }
+    claimedRefs.set(String(taskId), rowRef);
     try {
-      const leaseId = task.id || taskId;
+      const leaseId = rowRef;
       const leased = leaseDb.setLease(leaseConnection, { id: leaseId, holder: taskActor });
       if (!leased && (!ownCli || leaseDb.getTask(leaseConnection, leaseId))) throw new Error('could not set claim lease');
       if (leased) leasedIds.add(leaseId);
@@ -3604,7 +3816,9 @@ async function runDispatchFlight({
         if (!wt) {
           const released = releaseUnstartedDispatchClaim(cli, {
             taskId,
+            ref: rowRef,
             actor: taskActor,
+            stage: 'worktree_start',
             detail: String(started.stderr || '').slice(0, 200),
           });
           flight.paused.push({ task: taskId, stage: 'worktree_start', detail: released.detail, claim_released: released.released });
@@ -3616,7 +3830,9 @@ async function runDispatchFlight({
       if (enforceRemoteBoundary && (!remoteBoundary || remoteBoundary.ok !== true)) {
         const released = releaseUnstartedDispatchClaim(cli, {
           taskId,
+          ref: rowRef,
           actor: taskActor,
+          stage: 'remote_quarantine',
           detail: headTail(String(remoteBoundary && remoteBoundary.detail || 'could not prepare a sealed review sandbox')),
         });
         flight.paused.push({
@@ -3659,7 +3875,9 @@ async function runDispatchFlight({
     } catch (err) {
       const released = releaseUnstartedDispatchClaim(cli, {
         taskId,
+        ref: rowRef,
         actor: taskActor,
+        stage: 'prepare',
         detail: String(err && err.message || err).slice(0, 200),
       });
       flight.paused.push({ task: taskId, stage: 'prepare', detail: released.detail, claim_released: released.released });
@@ -3813,10 +4031,35 @@ async function runDispatchFlight({
         change,
       };
     }
-    const shipped = shipWithRetry(cli, fleetShipArgs({ task: entry.task, engine: entry.engine || engine }, check, landTarget), entry.worktreePath);
+    // A flight never merges protected-lane work. It ships the branch without
+    // --merge, so a pull request opens and a person lands it.
+    const lane = protectedLaneOfTask(entry.task);
+    const shipped = shipWithRetry(cli, fleetShipArgs({ task: entry.task, engine: entry.engine || engine }, check, landTarget, { merge: !lane }), entry.worktreePath);
     if (shipped.status !== 0 || !/done: worktree shipped/.test(shipped.stdout)) {
       return { ok: false, stage: 'ship', detail: shipFailureDetail(shipped) };
     }
+    if (lane) {
+      const pullRequest = shipPullRequest(shipped.stdout);
+      if (!pullRequest) {
+        const nothingToReview = /^pr: skipped \(no commits ahead of base\)/m.test(shipped.stdout);
+        return {
+          ok: false,
+          stage: 'ship',
+          detail: nothingToReview
+            ? 'no commits ahead of base, so there was no pull request to open'
+            : `the branch was pushed, but no pull request link came back for the protected ${lane} lane`,
+        };
+      }
+      return {
+        ok: true,
+        stage: 'held_for_review',
+        lane,
+        pull_request: pullRequest,
+        check,
+        verifyOutput: `${verified.stdout}${verified.stderr}`,
+        verifier_result: verifierResult,
+      };
+    }
     return {
       ok: true,
       stage: 'shipped',
@@ -4176,7 +4419,7 @@ async function runDispatchFlight({
           ? ` Independent validator ${validatorResult.engine} signed off: ${validatorResult.reason}.`
           : '';
         const readyResult = cli([
-          'task', 'ready', entry.taskId,
+          'task', 'ready', jobRef(entry.task, entry.taskId),
           '--proof', `Built by ${activeEngine} engine via one-lap dispatch.${restaffProof} Preserved in isolated worktree ${reviewWorktreePath}.${verificationCitation}${validatorCitation} Verify output: ${verifyTail || '(command produced no output, exit 0)'}. Receipt saved at ${path.relative(root, receiptPath)}.`,
           '--result', 'Operators can review a completed, verified change before it lands, reducing the risk of unreviewed changes reaching users.',
           '--landing', 'Operators can review the verified change before it reaches users, reducing the risk of an unreviewed release.',
@@ -4210,13 +4453,49 @@ async function runDispatchFlight({
         }
         continue;
       }
+      if (landed.stage === 'held_for_review') {
+        // Protected-lane work: the pull request is open, a person lands it.
+        // The claim stays with the builder and the job waits in Review, so the
+        // rating sees good work waiting, not a drop.
+        const prUrl = landed.pull_request.url;
+        const heldRow = {
+          task: entry.taskId,
+          engine: activeEngine,
+          check: landed.check,
+          lane: landed.lane,
+          pull_request: landed.pull_request,
+          verifier_result: landed.verifier_result,
+        };
+        if (result.brief_id) heldRow.brief_id = result.brief_id;
+        if (result.restaffed) heldRow.restaffed = result.restaffed;
+        flight.held_for_review.push(heldRow);
+        const heldRecorded = recordLandedTaskReview(cli, [
+          'task', 'ready', jobRef(entry.task, entry.taskId),
+          '--proof', `Built by ${activeEngine} engine via atris engine dispatch.${restaffProof} This task sits in the protected ${landed.lane} lane, so it was not merged: pull request ${prUrl} waits for a person to land it. The declared verifier passed (exit 0). Verify output: ${verifyTail || '(command produced no output, exit 0)'}. Receipt saved at ${path.relative(root, receiptPath)}.`,
+          '--result', 'A person can review and land this fix from its pull request, because dispatch reran the verifier before opening it.',
+          '--checked', `${landed.check} passed before the pull request was opened`,
+          '--tested', 'The requested behavior passed its declared verifier.',
+          ...openPullRequestFlags(landed.pull_request),
+          '--as', readyActor,
+        ], { flight, landedRow: heldRow, worktree: entry.worktreePath, heldForReview: true, save: () => writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly: proofOnly, enforceRemoteBoundary }) });
+        if (!heldRecorded) {
+          stampDispatchBrief(root, result.brief_id, 'partial', `opened a pull request for ${entry.taskId}, but task ready failed`);
+          log('    the pull request is open, but saving its proof failed. repair the task record before starting more work.');
+          const unsaved = flight.paused.find((row) => row.task === entry.taskId && row.stage === 'task_ready' && row.held_for_review === true);
+          if (unsaved) releaseClaimOfUnsavedPullRequest({ taskDb: leaseDb, db: leaseConnection, root, row: unsaved, rowId: entry.task && entry.task.id, actor: taskActor, log });
+          continue;
+        }
+        stampDispatchBrief(root, result.brief_id, 'pass', `held ${entry.taskId} for a person to land`);
+        log(`    ⏸ ${entry.taskId} waits for a person to land it: ${prUrl}`);
+        continue;
+      }
       const landedRow = { task: entry.taskId, engine: activeEngine, check: landed.check };
       landedRow.verifier_result = landed.verifier_result;
       if (result.brief_id) landedRow.brief_id = result.brief_id;
       if (result.restaffed) landedRow.restaffed = result.restaffed;
       flight.landed.push(landedRow);
       const reviewRecorded = recordLandedTaskReview(cli, [
-        'task', 'ready', entry.taskId,
+        'task', 'ready', jobRef(entry.task, entry.taskId),
         '--proof', `Built by ${activeEngine} engine via atris engine dispatch.${restaffProof} Landed via worktree ship gate (rebase-before-ship, verify re-run). The declared verifier passed (exit 0). Verify output: ${verifyTail || '(command produced no output, exit 0)'}. Receipt saved at ${path.relative(root, receiptPath)}.`,
         '--result', 'Operators can now review engine-built work faster because dispatch reran the verifier before landing.',
         '--checked', `${landed.check} passed before landing`,
@@ -4248,6 +4527,7 @@ async function runDispatchFlight({
     paused: flight.paused,
     worktreeByTask: new Map(prepared.map((entry) => [String(entry.taskId), entry.worktreePath])),
     actorByTask: new Map(ids.map((taskId) => [String(taskId), taskActor])),
+    refByTask: claimedRefs,
     baseRef: landTarget,
     log,
     keepClaimsWithWork: proofOnly,
@@ -4269,7 +4549,8 @@ async function runDispatchFlight({
     log(`  fable handoff failed: ${cause}. receipt: ${path.relative(root, receiptPath)}`);
   }
   const completedLabel = proofOnly ? `${flight.ready.length} proof ready` : `${flight.landed.length} landed`;
-  log(`  dispatch over: ${completedLabel}, ${flight.paused.length} paused - receipt: ${path.relative(root, flight.receipt)}`);
+  const heldLabel = flight.held_for_review.length ? `, ${flight.held_for_review.length} waiting for a person to land` : '';
+  log(`  dispatch over: ${completedLabel}${heldLabel}, ${flight.paused.length} paused - receipt: ${path.relative(root, flight.receipt)}`);
   log('');
   return flight;
   } finally {