atris 3.70.0 → 3.71.1

package/lib/member-up.js

@@ -4,27 +4,150 @@
 // working. Each check it looks at every runnable member, and when one has no
 // live run and a task with a runnable check fits it, starts
 // `atris member go <name> --needs-check` so the member claims and runs that
-// task. A member with no such task stays idle; it never falls back to its
-// own mission or goal text. The clock, the spawner, the member list and the
-// task picker are passed in, so tests drive it with fake time.
+// task. A member with no such task writes its own next job from its standing
+// mission when that mission names a check (lib/member-self-next-job.js), and
+// starts on it; otherwise it stays idle. The clock, the spawner, the member
+// list and the task picker are passed in, so tests drive it with fake time.
 
 const { taskCheck } = require('./member-task-pick');
 const { followBoard } = require('./member-board');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
 
 const CHECK_MS = 60 * 1000;
 const IDLE_CHECK_MS = 5 * 60 * 1000;
+const IDLE_MAX_CHECK_MS = 30 * 60 * 1000;
 const SUMMARY_MS = 10 * 60 * 1000;
+// A run with no new step for this long is called out as stuck, once per stall.
+const STALL_MS = 20 * 60 * 1000;
+// How often member changes GitHub dropped from its merge line are put back.
+// Each look can call GitHub, so it runs less often than the member check.
+const REQUEUE_MS = 5 * 60 * 1000;
+// Put-back outcomes worth a line: one went back in, or one was left for you.
+const REQUEUE_SAID = new Set(['requeued', 'clash', 'gave-up', 'changed', 'moved', 'stalled', 'refreshed', 'refresh-failed']);
+const MAINTENANCE_LOCK_MS = 2 * 60 * 1000;
+const MERGE_QUIET_MS = 2 * 60 * 60 * 1000;
 const IDLE_AFTER_EMPTY = 3;
 const DEFAULT_MAX = 6;
 // Exit code `member go --needs-check` uses when it found no task with a check
 // to claim (another run took it first). Not a failure, just idle.
 const IDLE_EXIT = 75;
+// A member name that gets each job by itself, for the add-one hint.
+const JOB_MEMBER = { build: 'builder', review: 'reviewer', search: 'researcher' };
+
+function maintenanceGit(cwd, args) {
+  const out = spawnSync('git', args, {
+    cwd, encoding: 'utf8', timeout: 30000,
+    env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_TERMINAL_PROMPT: '0' },
+  });
+  return { ok: out.status === 0, text: String(out.stdout || '').trim() };
+}
+
+// Never move a developer's branch, a linked work folder, or any edited copy.
+// Recheck after the fetch, which can take long enough for edits to arrive.
+function refreshMemberCode(root) {
+  const safe = () => {
+    try { if (!fs.lstatSync(path.join(root, '.git')).isDirectory()) return false; } catch { return false; }
+    const detached = maintenanceGit(root, ['symbolic-ref', '-q', 'HEAD']);
+    const clean = maintenanceGit(root, ['status', '--porcelain', '--untracked-files=all']);
+    return !detached.ok && clean.ok && !clean.text;
+  };
+  if (!safe()) return null;
+  const before = maintenanceGit(root, ['rev-parse', '--verify', 'HEAD']);
+  const fetched = maintenanceGit(root, ['fetch', '-q', 'origin', '+refs/heads/master:refs/remotes/origin/master']);
+  if (!fetched.ok) return { state: 'refresh-failed', line: 'could not refresh the members\' code copy; will try again' };
+  const tip = maintenanceGit(root, ['rev-parse', '--verify', 'refs/remotes/origin/master^{commit}']);
+  const current = maintenanceGit(root, ['rev-parse', '--verify', 'HEAD']);
+  if (!before.ok || !tip.ok || !current.ok || current.text !== before.text || !safe()) return null;
+  if (tip.text === before.text) return null;
+  // A detached local commit is still someone's work. Only move forward.
+  if (!maintenanceGit(root, ['merge-base', '--is-ancestor', before.text, tip.text]).ok) return null;
+  const moved = maintenanceGit(root, ['checkout', '--detach', tip.text]);
+  return moved.ok
+    ? { state: 'refreshed', line: 'the members\' code copy is current' }
+    : { state: 'refresh-failed', line: 'could not refresh the members\' code copy; will try again' };
+}
+
+// Shared by all windows of a project, including linked work folders. The
+// completed-pass timestamp survives release, so a second window waits too.
+function memberMaintenance({ cwd, codeRoot, now = Date.now(), requeueDropped, waitingTasks = () => [] }) {
+  const common = maintenanceGit(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!common.ok) return { results: [] };
+  const dir = path.join(path.dirname(common.text), '.atris', 'state');
+  fs.mkdirSync(dir, { recursive: true });
+  const lock = path.join(dir, 'member-up-maintenance.lock');
+  const file = path.join(dir, 'member-up-maintenance.json');
+  let fd;
+  try {
+    fd = fs.openSync(lock, 'wx');
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    // A live owner always holds, even past the lease: GitHub may be slow.
+    // Unknown/malformed owners get a short grace period before recovery.
+    try {
+      const stat = fs.statSync(lock);
+      let owner;
+      try { owner = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch {}
+      if (Number.isInteger(owner?.pid) && owner.pid > 0) {
+        try { process.kill(owner.pid, 0); return { results: [] }; }
+        catch (e) { if (e.code !== 'ESRCH') return { results: [] }; }
+      } else if (now - stat.mtimeMs < MAINTENANCE_LOCK_MS) return { results: [] };
+      if (fs.statSync(lock).ino !== stat.ino) return { results: [] };
+      fs.unlinkSync(lock);
+      fd = fs.openSync(lock, 'wx');
+    } catch { return { results: [] }; }
+  }
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: now }));
+    let state = {};
+    try { state = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch {}
+    if (Number.isFinite(state.checked_at) && now - state.checked_at < REQUEUE_MS) return { results: [] };
+    const save = () => {
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(state));
+      fs.renameSync(tmp, file);
+    };
+    state.checked_at = now;
+    save();
+    const out = requeueDropped();
+    const results = [...(out?.results || [])];
+    const merged = results.some((r) => r.state === 'merged');
+    const waiting = results.some((r) => !['merged', 'closed'].includes(r.state)) || waitingTasks().length > 0;
+    if (merged || !waiting) {
+      state.waiting_since = null;
+      state.quiet_said = false;
+    }
+    if (waiting && state.waiting_since == null) state.waiting_since = now;
+    if (waiting && !state.quiet_said && now - state.waiting_since >= MERGE_QUIET_MS) {
+      results.push({ state: 'stalled', line: 'jobs are waiting, but nothing has merged for two hours' });
+      state.quiet_said = true;
+    }
+    const refresh = codeRoot ? refreshMemberCode(codeRoot) : null;
+    if (refresh && (refresh.state !== 'refresh-failed' || !state.refresh_failed)) results.push(refresh);
+    state.refresh_failed = refresh?.state === 'refresh-failed';
+    save();
+    return { ...out, results };
+  } finally {
+    fs.closeSync(fd);
+    fs.unlinkSync(lock);
+  }
+}
 
 function dayOf(ms) {
   const d = new Date(ms);
   return `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}`;
 }
 
+// How long an idle member waits before its next check. The first few empty
+// checks wait one round; after that the wait doubles from 5 minutes each
+// empty check, up to 30 minutes. Finding work resets it.
+function idleWaitMs(empty) {
+  if (!(empty >= IDLE_AFTER_EMPTY)) return 0;
+  const doublings = Math.min(empty - IDLE_AFTER_EMPTY, 10);
+  return Math.min(IDLE_CHECK_MS * 2 ** doublings, IDLE_MAX_CHECK_MS);
+}
+
 function oneLine(text) {
   return String(text || '').replace(/\s+/g, ' ').trim();
 }
@@ -38,9 +161,17 @@ function hasRunnableCheck(task) {
 // deps:
 //   listMembers() -> [{ name, parked, human, sleeping, live }]
 //   pickTask(name, takenIds) -> { id, title } | null   (looks only, never claims)
-//   spawn(name, onExit) -> any                         (onExit(code) when it ends)
+//   spawn(name, onExit, onClaim) -> any (claim confirms { id, title })
 //   now() -> ms
 //   print(line)
+//   jobOf(name) -> 'build' | 'review' | 'search'       (optional)
+//   writeNextJob(name, { dryRun }) -> { task } | { skip } (optional; writes
+//                     the member's next job from its mission when its list
+//                     is empty; a dry run only says what it would write)
+//   waitingTasks() -> [{ id, title, job }]            (optional; open tasks
+//                     with a runnable check, any job)
+//   requeueDropped() -> { results: [{ state, line }] } (optional; puts member
+//                     changes GitHub dropped from its merge line back in)
 function createMemberUp(deps, options = {}) {
   const max = Math.max(1, Number(options.max) || DEFAULT_MAX);
   const dryRun = options.dryRun === true;
@@ -51,11 +182,14 @@ function createMemberUp(deps, options = {}) {
     ? new Set(options.only.map((name) => String(name).trim()).filter(Boolean))
     : null;
   const skippedUnknown = new Set();
+  const hintedJobs = new Set();
   const state = new Map();
   const running = new Map();
   let doneToday = 0;
   let doneDay = dayOf(deps.now());
   let lastSummaryAt = deps.now();
+  let lastRequeueAt = -Infinity;
+  let requeueFailSaid = false;
   // Members working right now: the runs this supervisor started plus any
   // live run started some other way. Both count toward --max.
   let liveElsewhere = new Set();
@@ -66,6 +200,20 @@ function createMemberUp(deps, options = {}) {
     return state.get(name);
   };
 
+  function claimed(name, run, task) {
+    if (running.get(name) !== run || run.announced || !task?.id || !task?.title) return;
+    run.announced = true;
+    run.taskId = task.id;
+    const s = seat(name);
+    const title = oneLine(task.title);
+    run.title = title;
+    if (s.idle) print(`${name} woke up for: ${title}`);
+    s.idle = false;
+    s.empty = 0;
+    s.nextCheckAt = 0;
+    print(`${name} started on: ${title}`);
+  }
+
   function finish(name, code, result = {}) {
     if (!running.has(name)) return;
     const run = running.get(name);
@@ -95,6 +243,29 @@ function createMemberUp(deps, options = {}) {
 
   const idleLine = (name) => `${name} is idle, no task with a check`;
 
+  // Jobs waiting for a kind of work no awake member does, said once per kind:
+  // name a member who could be woken for it, or say to add one.
+  function otherKindHints(team, awake, taken) {
+    if (!deps.jobOf || !deps.waitingTasks) return;
+    const awakeJobs = new Set(awake.map((m) => deps.jobOf(m.name)));
+    const waiting = new Map();
+    for (const task of deps.waitingTasks() || []) {
+      if (!task || !task.job || (task.id && taken.has(task.id))) continue;
+      if (awakeJobs.has(task.job) || hintedJobs.has(task.job)) continue;
+      waiting.set(task.job, (waiting.get(task.job) || 0) + 1);
+    }
+    const awakeNames = new Set(awake.map((m) => m.name));
+    for (const [job, count] of waiting) {
+      hintedJobs.add(job);
+      const jobs = count === 1 ? `1 ${job} job is waiting` : `${count} ${job} jobs are waiting`;
+      const sleeper = team.find((m) => m && m.name && !m.human && !m.parked
+        && !awakeNames.has(m.name) && deps.jobOf(m.name) === job);
+      print(sleeper
+        ? `${jobs}, but nobody who does ${job} is awake. wake one: atris member wake ${sleeper.name} --keep`
+        : `${jobs}, but no member on the team does ${job}. add one: atris member create ${JOB_MEMBER[job] || job}`);
+    }
+  }
+
   function progress(event) {
     const run = running.get(event.member);
     if (!run || Date.parse(event.at) < run.startedAt) return;
@@ -104,6 +275,9 @@ function createMemberUp(deps, options = {}) {
     }
     if (event.kind !== 'step') return;
     if (event.text.startsWith('editing ')) run.changed = event.text;
+    run.lastStepAt = Math.max(run.lastStepAt, Date.parse(event.at) || 0);
+    run.lastStep = oneLine(event.text);
+    run.stallSaid = false;
     const time = new Date(event.at);
     const hhmm = `${String(time.getHours()).padStart(2, '0')}:${String(time.getMinutes()).padStart(2, '0')}`;
     print(`  ${event.member} ${hhmm}  ${oneLine(event.text)}`);
@@ -114,9 +288,60 @@ function createMemberUp(deps, options = {}) {
     return `working ${working()}, idle ${idle}, done today ${doneToday}`;
   }
 
+  // Say once when a run has shown no new step for STALL_MS, so a hung member
+  // does not hold a seat in silence. A new step lets a later stall be said again.
+  function callOutStalls(now) {
+    for (const [name, run] of running) {
+      const quietMs = now - run.lastStepAt;
+      if (run.stallSaid || quietMs < STALL_MS) continue;
+      run.stallSaid = true;
+      print(`${name} looks stuck: no progress for ${Math.floor(quietMs / 60000)} minutes on ${run.title}. `
+        + `last step: ${run.lastStep || 'none yet'}`);
+    }
+  }
+
+  // Every REQUEUE_MS, put back member changes GitHub dropped from its merge
+  // line, so nobody has to run atris land --requeue. A dry run never pushes.
+  // A failure is said once until a later look works.
+  function putBackDropped(now) {
+    if (dryRun || !deps.requeueDropped || now - lastRequeueAt < REQUEUE_MS) return;
+    lastRequeueAt = now;
+    let out;
+    try {
+      out = deps.requeueDropped();
+      requeueFailSaid = false;
+    } catch (error) {
+      if (!requeueFailSaid) print(`could not check github's merge line: ${oneLine(error && error.message || error)}`);
+      requeueFailSaid = true;
+      return;
+    }
+    for (const result of (out && out.results) || []) {
+      if (result && REQUEUE_SAID.has(result.state)) print(oneLine(result.line));
+    }
+  }
+
+  // An empty list: the member writes its next job from its mission. The new
+  // task is the one it starts on; a skip or an error leaves it idle.
+  function ownNextJob(name, s) {
+    if (!deps.writeNextJob) return null;
+    let out;
+    try {
+      out = deps.writeNextJob(name, { dryRun });
+    } catch (error) {
+      if (!s.idle) print(`${name} could not write its own next job: ${oneLine(error && error.message || error)}`);
+      return null;
+    }
+    const task = out && out.task;
+    if (!task || !hasRunnableCheck(task)) return null;
+    print(`${name} had no job, so it ${dryRun ? 'would write' : 'wrote'} its own from its mission: ${oneLine(task.title)}`);
+    return task;
+  }
+
   // One pass over the team. Returns the members it started (or would start).
   function check() {
     const now = deps.now();
+    callOutStalls(now);
+    putBackDropped(now);
     const started = [];
     const taken = new Set(Array.from(running.values()).map((run) => run.taskId).filter(Boolean));
     const team = deps.listMembers();
@@ -138,12 +363,14 @@ function createMemberUp(deps, options = {}) {
       const s = seat(name);
       if (now < s.nextCheckAt) continue;
       const picked = deps.pickTask(name, taken);
-      const task = picked && hasRunnableCheck(picked) ? picked : null;
+      let task = picked && hasRunnableCheck(picked) ? picked : null;
+      if (!task) task = ownNextJob(name, s);
       if (!task) {
         s.empty += 1;
         if (!s.idle && !dryRun) print(idleLine(name));
         s.idle = true;
-        if (s.empty >= IDLE_AFTER_EMPTY) s.nextCheckAt = now + IDLE_CHECK_MS;
+        const wait = idleWaitMs(s.empty);
+        if (wait) s.nextCheckAt = now + wait;
         continue;
       }
       const title = oneLine(task.title);
@@ -153,24 +380,23 @@ function createMemberUp(deps, options = {}) {
         started.push({ name, task });
         continue;
       }
-      if (s.idle) print(`${name} woke up for: ${title}`);
-      s.idle = false;
-      s.empty = 0;
-      s.nextCheckAt = 0;
-      running.set(name, { taskId: task.id || null, startedAt: now });
+      const run = { taskId: task.id || null, title, startedAt: now, lastStepAt: now, announced: false };
+      running.set(name, run);
       try {
         deps.spawn(name, (code, result) => {
           deps.flushProgress?.();
-          finish(name, code, result);
-        });
+          if (running.get(name) === run) finish(name, code, result);
+        }, (claimedTask) => claimed(name, run, claimedTask));
       } catch (error) {
         running.delete(name);
         print(`${name} failed to start: ${oneLine(error && error.message || error)}`);
         continue;
       }
-      print(`${name} started on: ${title}`);
       started.push({ name, task });
     }
+    try {
+      otherKindHints(team, members.filter((m) => m && m.name && !m.parked && !m.human && !m.sleeping), taken);
+    } catch {}
     if (!dryRun && now - lastSummaryAt >= SUMMARY_MS) {
       lastSummaryAt = now;
       print(summary());
@@ -209,7 +435,7 @@ function memberUpResult(stdout, stderr = '', signal = '') {
     : oneLine(stderr) || 'run ended without a checked task result' };
 }
 
-// Reads `member up` flags: --max N, --only a,b and --dry-run.
+// Reads `member up` flags: --max N, --only a,b and --dry-run (or --plan).
 // Returns { max, only, dryRun } or { error }.
 function parseMemberUpArgs(args = []) {
   const list = args.map((arg) => String(arg == null ? '' : arg));
@@ -219,7 +445,9 @@ function parseMemberUpArgs(args = []) {
     const inline = list.find((arg) => arg.startsWith(`${flag}=`));
     return inline == null ? null : inline.slice(flag.length + 1);
   };
-  const out = { max: undefined, only: null, dryRun: list.includes('--dry-run') };
+  // --plan only plans, same as on a single wake: `member wake a --keep --plan`
+  // must never start a paid run.
+  const out = { max: undefined, only: null, dryRun: list.includes('--dry-run') || list.includes('--plan') };
   const maxText = valueOf('--max');
   if (maxText != null) {
     const max = Number(maxText);
@@ -278,9 +506,14 @@ module.exports = {
   DEFAULT_MAX,
   IDLE_CHECK_MS,
   IDLE_EXIT,
+  IDLE_MAX_CHECK_MS,
+  REQUEUE_MS,
+  STALL_MS,
   SUMMARY_MS,
   createMemberUp,
+  idleWaitMs,
   memberUpResult,
+  memberMaintenance,
   parseMemberUpArgs,
   runMemberUp,
 };

package/lib/roster-prep.js

@@ -19,6 +19,7 @@ const {
 const { spawnSync } = require('child_process');
 const { buildReadOnlyEngineInvocation, buildAskSpawnEnv, runAskProcess } = require('./engine-ask');
 const { appendRosterRun, parseRunUsage } = require('./roster-runs');
+const { startEngineRun } = require('./engine-resource');
 
 // A brief is at most 300 lines and 20 KB: enough for a dozen file:line
 // pointers with short excerpts, small enough that a heavy model reads it in
@@ -154,7 +155,7 @@ function defaultPrepAskSync({ engine, model, effort, prompt, cwd, timeoutMs }) {
   else if (spawnError) reason = 'spawn_error';
   else if (run.status !== 0) reason = `exit_${run.status == null ? 'unknown' : run.status}`;
   else if (!hasOutput) reason = 'no_output';
-  return { ok: reason === 'ok', reason, timed_out: timedOut, stdout, stderr: spawnError ? `${stderr}${spawnError.message}` : stderr };
+  return { ok: reason === 'ok', reason, timed_out: timedOut, signal: run.signal || null, stdout, stderr: spawnError ? `${stderr}${spawnError.message}` : stderr };
 }
 
 function skipped(job, reason, extra = {}) {
@@ -211,7 +212,9 @@ function finishPrepPass(plan, answer, { startedMs, endedMs, task, root = process
     reason = exit ? `${engine} exited ${exit[1]}`
       : answer.reason === 'no_output' ? 'returned nothing'
         : answer.reason === 'spawn_error' ? `${engine} could not start`
-          : `${engine} failed`;
+          : answer.signal ? `${engine} stopped by ${answer.signal}`
+            : `${engine} failed`;
+    if (answer.cause) reason = `${reason}; ${answer.cause}`;
   } else if (!brief.text) {
     outcome = 'failed';
     reason = 'returned nothing';
@@ -239,6 +242,22 @@ function askFailure(error) {
   return { ok: false, reason: 'runner_error', stderr: String(error && error.message || error), stdout: '' };
 }
 
+// Machine memory and load at both ends of the prep launch. The ask answers
+// instead of throwing, so a failure is passed in the thrown shape, and a
+// SIGKILL hands its cause back on the answer.
+function startPrepReadings(plan, root) {
+  const endResource = startEngineRun(root || process.cwd(), { engine: plan.engine, task: `prep for ${plan.forLabel}` });
+  return (answer) => {
+    const end = endResource(answer.ok ? null : {
+      code: answer.timed_out ? 'ETIMEDOUT' : '',
+      signal: answer.signal,
+      stderr: answer.stderr,
+      message: answer.reason,
+    });
+    return end && end.cause && !answer.timed_out ? { ...answer, cause: end.cause } : answer;
+  };
+}
+
 // One prep pass for one task. Never throws: every way it can go wrong comes
 // back as { ok: false, reason } so the heavy worker still runs.
 async function runPrepPass({
@@ -250,12 +269,14 @@ async function runPrepPass({
   const plan = planPrepPass(options);
   if (plan.skip) return plan.skip;
   const startedMs = clock();
+  const endReadings = startPrepReadings(plan, options.root);
   let answer;
   try {
     answer = await ask(plan.request);
   } catch (error) {
     answer = askFailure(error);
   }
+  answer = endReadings(answer || { ok: false, reason: 'no_answer', stdout: '' });
   return finishPrepPass(plan, answer, { startedMs, endedMs: clock(), task: options.task, root: options.root, record });
 }
 
@@ -269,12 +290,14 @@ function runPrepPassSync({
   const plan = planPrepPass(options);
   if (plan.skip) return plan.skip;
   const startedMs = clock();
+  const endReadings = startPrepReadings(plan, options.root);
   let answer;
   try {
     answer = ask(plan.request);
   } catch (error) {
     answer = askFailure(error);
   }
+  answer = endReadings(answer || { ok: false, reason: 'no_answer', stdout: '' });
   return finishPrepPass(plan, answer, { startedMs, endedMs: clock(), task: options.task, root: options.root, record });
 }
 

package/lib/runner-command.js

@@ -43,6 +43,11 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
     model: 'atris:fast',
     commandTemplate: '{bin} --fast {prompt}',
   }),
+  mercury: Object.freeze({
+    bin: 'ax',
+    model: 'inception:mercury-3-preview-1002',
+    commandTemplate: '{bin} --mercury {prompt}',
+  }),
   // Guest engines: any installed headless coding CLI is a swappable worker.
   // No commandTemplate on claude, the default spawn shape is already
   // claude-compatible (bin -p prompt --model X --allowedTools ...).

package/lib/task-db.js

@@ -31,7 +31,7 @@ const dailyLog = require('./daily-log');
 const { isGenericScratchRoot } = require('./scratch-root');
 const { isDecisionTask } = require('./task-decision');
 const { parseVerifyCommand } = require('./auto-accept-certified');
-const { taskExplanation } = require('./task-explanation');
+const { explicitDoneLooksLike, taskExplanation } = require('./task-explanation');
 const { treeHashFor } = require('./tree-hash');
 const { sleepSync } = require('./sleep-sync');
 const { atrisHome } = require('./state-home');
@@ -559,6 +559,22 @@ function getTask(db, id) {
   return { ...row, metadata, ...(unreadable ? { metadata_unreadable: true } : {}) };
 }
 
+// The commit a workspace sits on. Claim and ready stamp it so a landing can
+// later be proven from the task's own change (lib/landing-proof.js) instead
+// of whatever the checkout's HEAD happens to be at accept time.
+function workspaceHead(workspaceRoot) {
+  if (!workspaceRoot) return null;
+  try {
+    const result = require('child_process').spawnSync('git', ['rev-parse', 'HEAD'], {
+      cwd: workspaceRoot, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const sha = String(result.stdout || '').trim();
+    return result.status === 0 && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
 // 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`.
@@ -577,13 +593,21 @@ function claimTask(db, { id, claimedBy }) {
   `);
   const result = withBusyRetry(() => stmt.run(claimedBy, now, now, id));
   if (result.changes === 1) {
-    const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+    let row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+    // First claim wins: a re-claim after a revision keeps the original start.
+    const startCommit = workspaceHead(row.workspace_root);
+    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, {
       taskId: id,
       workspaceRoot: row.workspace_root,
       actor: claimedBy,
       eventType: 'claimed',
-      payload: { claimed_by: claimedBy },
+      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' });
@@ -595,7 +619,7 @@ function claimTask(db, { id, claimedBy }) {
   return { claimed: false, reason: 'already_' + row.status, claimed_by: row.claimed_by };
 }
 
-function releaseTask(db, { id, actor }) {
+function releaseTask(db, { id, actor, expectedUpdatedAt }) {
   if (!id) throw new Error('id required');
   if (!actor) throw new Error('actor required');
   const row = getTask(db, id);
@@ -616,7 +640,8 @@ function releaseTask(db, { id, actor }) {
      WHERE id = ?
        AND status = 'claimed'
        AND claimed_by = ?
-  `).run(now, id, actor));
+       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 };
   const updated = getTask(db, id);
   const event = appendTaskEvent(db, {
@@ -632,12 +657,14 @@ function releaseTask(db, { id, actor }) {
   return { released: true, row: updated, event };
 }
 
-function reopenTask(db, { id, actor, reason, metadata: metadataPatch } = {}) {
+function reopenTask(db, { id, actor, reason, metadata: metadataPatch, fromReview = false } = {}) {
   if (!id) throw new Error('id required');
   const row = getTask(db, id);
   if (!row) return { reopened: false, reason: 'not_found' };
-  if (OPEN_TASK_STATUSES.has(row.status)) return { reopened: false, reason: `already_${row.status}`, row };
-  if (!['done', 'failed', 'archived'].includes(row.status)) {
+  // A job marked done and waiting to merge can be sent back only on request.
+  const reviewReopen = fromReview && row.status === 'review';
+  if (!reviewReopen && OPEN_TASK_STATUSES.has(row.status)) return { reopened: false, reason: `already_${row.status}`, row };
+  if (!reviewReopen && !['done', 'failed', 'archived'].includes(row.status)) {
     return { reopened: false, reason: `not_reopenable_${row.status}` };
   }
 
@@ -912,7 +939,7 @@ function recordReviewPassActor(metadata, claimedBy, rawActor) {
   return { builder: builder || null, independent };
 }
 
-function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, resultTrace, result: resultSentence, reason }) {
+function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, resultTrace, result: resultSentence, reason, workRoot }) {
   if (!id) throw new Error('id required');
   const text = String(proof || '').trim();
   if (!text) throw new Error('proof required');
@@ -940,6 +967,15 @@ function readyTask(db, { id, actor, proof, lesson, nextTask, landing = {}, resul
     const cleaned = cleanLandingText(landingInput[key]);
     if (cleaned) metadata[`landing_${key}`] = cleaned;
   }
+  // 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;
@@ -1302,7 +1338,7 @@ function stageTask(db, {
   let stageOwner = requestedOwner || actorText || cleanStageText(row.claimed_by) || null;
   let goalText = requestedGoal || cleanStageText(metadata.task_goal || metadata.goal_objective || metadata.objective || metadata.stage_goal);
   let proofText = requestedProof || cleanStageText(metadata.verify || metadata.proof_needed);
-  let exitText = requestedExit || cleanStageText(metadata.exit_condition);
+  let exitText = requestedExit || cleanStageText(metadata.exit_condition) || cleanStageText(explicitDoneLooksLike(metadata));
 
   function recordedDoPlan(currentRow, { claimedOwnerWins = false } = {}) {
     const currentMetadata = currentRow && currentRow.metadata && typeof currentRow.metadata === 'object'
@@ -1314,7 +1350,7 @@ function stageTask(db, {
     const caller = actorText || requestedOwner || null;
     const recordedGoal = cleanStageText(currentMetadata.goal_objective || currentMetadata.objective || currentMetadata.stage_goal || currentMetadata.task_goal);
     const recordedProof = cleanStageText(currentMetadata.verify || currentMetadata.proof_needed);
-    const recordedExit = cleanStageText(currentMetadata.exit_condition);
+    const recordedExit = cleanStageText(currentMetadata.exit_condition) || cleanStageText(explicitDoneLooksLike(currentMetadata));
     const planRecorded = cleanStageText(currentMetadata.planned_at)
       || cleanStageText(currentMetadata.stage) === 'plan'
       || cleanStageText(currentMetadata.stage_plan_recorded_at);

package/lib/task-explanation.js

@@ -81,6 +81,12 @@ function explicitExplanationFields(metadata) {
   return out;
 }
 
+// The author's own "done looks like" line, or empty when it was only derived.
+// A job that states this has a finish line, so plan gates read it as one.
+function explicitDoneLooksLike(metadata) {
+  return explicitExplanationFields(metadata).done_looks_like || '';
+}
+
 function explanationGoalText(task) {
   const metadata = task && task.metadata || {};
   return cleanText(metadata.task_goal || metadata.goal_objective || (task && task.objective) || metadata.objective);
@@ -219,6 +225,7 @@ module.exports = {
   EXPLANATION_FIELDS,
   EXPLANATION_LABELS,
   NO_REASON_RECORDED,
+  explicitDoneLooksLike,
   plainText,
   taskExplanation,
   explanationFieldsFromInput,

package/lib/task-list-keeper.js

@@ -7,6 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const taskDb = require('./task-db');
 const { protectedLaneOf } = require('./auto-accept-certified');
+const { isDecisionTask } = require('./task-decision');
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 const OPEN_STATUSES = new Set(['open', 'claimed', 'review']);
@@ -72,6 +73,12 @@ function isProtectedRow(row) {
   return Boolean(protectedLaneOf({ ...row, metadata: parsedMetadata(row) }));
 }
 
+// A task tagged needs-human or decision is waiting on a person, not stuck.
+// Their silence is not an answer, so idle time never puts it away.
+function isHeldForPerson(row) {
+  return isDecisionTask({ ...row, metadata: parsedMetadata(row) });
+}
+
 function decisionFor(row, now, { includeDone = true } = {}) {
   if (!row || row.status === 'archived') return null;
   if (row.status === 'done') {
@@ -79,7 +86,7 @@ function decisionFor(row, now, { includeDone = true } = {}) {
     return { reason: REASONS.done, fromDone: true, fromFailed: false };
   }
   if (!Object.prototype.hasOwnProperty.call(IDLE_LIMITS_MS, row.status)) return null;
-  if (OPEN_STATUSES.has(row.status) && isProtectedRow(row)) return null;
+  if (OPEN_STATUSES.has(row.status) && (isProtectedRow(row) || isHeldForPerson(row))) return null;
   const at = Number(row.updated_at || row.created_at || 0);
   if (!((now - at) > IDLE_LIMITS_MS[row.status])) return null;
   return { reason: REASONS[row.status], fromDone: false, fromFailed: row.status === 'failed' };