atris 3.68.1 → 3.68.3

package/lib/fleet.js

@@ -32,7 +32,7 @@ const {
   buildOneLapValidatorPrompt,
   parseOneLapValidatorVerdict,
 } = require('./one-lap-validator');
-const { listWorktrees, defaultMainlineBase } = require('../commands/worktree');
+const { listWorktrees, defaultMainlineBase, gitFailureDetail, gitNetworkEnvironment } = require('../commands/worktree');
 const { isConductorStatusLine } = require('./conductor-artifacts');
 const { matchLessons } = require('./lesson-preflight');
 const { sleepSync } = require('./sleep-sync');
@@ -171,20 +171,34 @@ const YOLO_ENGINE_FLAGS = Object.freeze({
   codex: '--dangerously-bypass-approvals-and-sandbox',
   claude: '--dangerously-skip-permissions',
 });
-const DISPATCH_SELF_LAND_TARGET = 'origin/master';
+const DISPATCH_SELF_LAND_TARGET = 'HEAD';
 
 // Dispatch used to cut every build worktree from origin/master and check
 // self-landing against it, hard-coded. A workspace whose protected branch is
 // `main` had no origin/master, so the worktree cut and the ancestry check both
-// failed. Resolve the workspace's real protected branch instead (remote HEAD,
-// then origin/main), falling back to the historical origin/master when nothing
-// else can be determined so single-branch repos and test roots behave as before.
+// failed. Resolve the workspace's real protected branch instead, using local
+// HEAD only when origin is absent.
+
+// Only an absent origin enables local dispatch. An unreachable origin is
+// still an origin and must keep the protected-branch path unchanged.
+function localDispatchBase(root) {
+  const remote = spawnSync('git', ['remote'], { cwd: root, encoding: 'utf8' });
+  if (remote.status !== 0 || String(remote.stdout || '').trim().split(/\s+/).includes('origin')) return '';
+  const head = spawnSync('git', ['rev-parse', '--verify', 'HEAD^{commit}'], { cwd: root, encoding: 'utf8' });
+  return head.status === 0 ? String(head.stdout || '').trim() : '';
+}
+
+// Without origin, pin the current local commit even if stale remote refs remain.
 function resolveDispatchLandTarget(root, explicitBase) {
   if (explicitBase) return explicitBase;
-  try {
-    const mainline = defaultMainlineBase(root);
-    if (mainline && mainline !== 'HEAD') return mainline;
-  } catch {}
+  const localBase = localDispatchBase(root);
+  if (localBase) return localBase;
+  const mainline = defaultMainlineBase(root);
+  if (mainline && mainline !== 'HEAD') return mainline;
+  // A configured origin with no known mainline must fail at worktree start,
+  // before an engine can build from an unprotected local HEAD.
+  const origin = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8' });
+  if (origin.status === 0) return 'origin/HEAD';
   return DISPATCH_SELF_LAND_TARGET;
 }
 const DEFAULT_DISPATCH_TIMEOUT_MS = 900000;
@@ -634,7 +648,10 @@ function detectDeadEngineDispatch(result) {
   const exitCode = terminal.exit_code;
   const signal = dispatchResultSignal(result);
   if (signal) return { reason: 'signalled', signal, exitCode };
-  if (terminal.reason === 'ok') return null;
+  // A finished build's report and tool output are work, not engine failures.
+  const hasWorkOutput = [result && result.report, result && result.stdout]
+    .some((value) => String(value || '').trim());
+  if (terminal.reason === 'ok' && hasWorkOutput && !result.error && result.ok !== false) return null;
   // A credit wall is read from engine-level signals only. The report and
   // stdout are the task's own work: a failing "rate limit" test says nothing
   // about the engine's credits.
@@ -651,6 +668,17 @@ function detectDeadEngineDispatch(result) {
     ? DEAD_ENGINE_OUTPUT_PATTERNS.find((p) => engineText.includes(p))
     : null;
   if (pattern) return { reason: 'usage_limit', pattern };
+  // Engines print their own refusal at startup. Later stderr can contain a
+  // tool transcript, including the task's login checks, so stop at that boundary.
+  const startup = String(result && result.stderr || '').split(/\r?\n/).slice(0, 5);
+  const toolBoundary = startup.findIndex(line => /^(?:exec|tool\b|.*\bsucceeded in\b)/i.test(line.trim()));
+  const refusal = [
+    result && result.error && (result.error.message || result.error.code || result.error),
+    ...startup.slice(0, toolBoundary < 0 ? startup.length : toolBoundary),
+  ].filter(Boolean).map(value => String(value).trim())
+    .find(line => /^(?:error:\s*)?(?:refusing to run\b|(?:you are |you'?re )?not (?:logged in|authenticated)\b|please (?:log|sign) in\b|(?:login|authentication) required\b)/i.test(line));
+  if (refusal) return { reason: 'engine_refused', detail: refusal, exitCode };
+  if (terminal.reason === 'ok') return null;
   if (terminal.reason === 'no_output' || terminal.reason === 'unknown' || terminal.reason === 'timeout' || terminal.reason === 'cancelled') {
     return { reason: terminal.reason, exitCode };
   }
@@ -660,6 +688,7 @@ function detectDeadEngineDispatch(result) {
 function plainDispatchFailureCause(result, failure = {}) {
   const reason = String(failure.reason || failure.stage || '').trim();
   const output = dispatchResultOutput(result);
+  if (reason === 'engine_refused') return failure.detail;
   if (reason === 'no_output') return 'the engine returned no output';
   if (/not authenticated|please log in|login required|auth(?:entication)?[ _-]?expired/i.test(output)) {
     return 'the engine login expired';
@@ -957,7 +986,7 @@ async function dispatchEntryAttempts({
   if (handover) return handover;
   stampDispatchBrief(root, first.brief_id, 'fail', `restaffed from ${engine}: ${deadEngine.reason}`);
 
-  const outage = { from: engine, reason: deadEngine.reason };
+  const outage = { from: engine, reason: deadEngine.reason, ...(deadEngine.detail ? { detail: deadEngine.detail } : {}) };
   if (restaffState.used) {
     return { ...first, deadEngine: { ...outage, skipped: 'already_restaffed' } };
   }
@@ -976,6 +1005,7 @@ async function dispatchEntryAttempts({
       from: engine,
       to: fallback,
       reason: deadEngine.reason,
+      ...(deadEngine.detail ? { detail: deadEngine.detail } : {}),
       failed_legs: [failedDispatchLeg(first, engine)],
     },
   };
@@ -1362,7 +1392,7 @@ function dispatchResultToTerminal(entry = {}, result = {}) {
   return payload;
 }
 
-// Fleet landings always target master. Without the explicit --target, ship
+// Fleet landings always target the repository mainline. Without the explicit --target, ship
 // falls back to the launcher branch's atris-base, a flight launched from a
 // feature-branch checkout would merge PRs into that branch while the receipt
 // and land board define "landed" as in-master (PRs #207/#208, 2026-07-04).
@@ -1389,12 +1419,12 @@ function shipFailureDetail(shipped, { head = 400, tail = 500 } = {}) {
   return `${cause}${headTail(combined.trim(), head, tail)}`;
 }
 
-function fleetShipArgs(entry, check) {
+function fleetShipArgs(entry, check, targetRef = resolveDispatchLandTarget(entry.worktreePath || process.cwd())) {
   return [
     'worktree', 'ship',
     '--message', `${String(entry.task.title || '').split(/[.:]/)[0].slice(0, 90)} (${entry.task.display_id}, built by ${entry.engine})`,
     '--verify', check,
-    '--target', 'origin/master',
+    '--target', targetRef,
     '--merge',
   ];
 }
@@ -1482,11 +1512,32 @@ function pausedPathsSuffix(landed) {
   return paths.length ? ` (${paths.join(', ')})` : '';
 }
 
-function landArrival({ worktreePath, git = null }) {
-  const run = git || ((args) => spawnSync('git', args, { cwd: worktreePath, encoding: 'utf8' }));
-  const fetch = run(['fetch', 'origin']);
-  if (fetch.status !== 0) return { ok: false, stage: 'fetch', detail: String(fetch.stderr || '').trim() };
-  const rebase = run(['rebase', 'origin/master']);
+// Probe the SSH setup once per runner, not once per git call.
+function boundedGit(cwd) {
+  const env = gitNetworkEnvironment(process.env, cwd);
+  return (args) => spawnSync('git', args, { cwd, encoding: 'utf8', env, timeout: 15000, killSignal: 'SIGKILL' });
+}
+
+function landArrival({ worktreePath, targetRef = resolveDispatchLandTarget(worktreePath), git = null }) {
+  const run = git || boundedGit(worktreePath);
+  const remotes = run(['remote']);
+  if (remotes.status !== 0) return { ok: false, stage: 'fetch', detail: String(remotes.stderr || '').trim() };
+  if (String(remotes.stdout || '').trim().split(/\s+/).includes('origin')) {
+    const fetch = run(['fetch', 'origin']);
+    if (fetch.status !== 0) return { ok: false, stage: 'fetch', detail: gitFailureDetail(fetch) };
+  }
+  const sourceDirt = () => {
+    const status = run(['status', '--porcelain=v1', '--untracked-files=all']);
+    if (status.status !== 0) return { ok: false, stage: 'status', detail: String(status.stderr || '').trim() };
+    const dirty = String(status.stdout || '').split('\n').filter(Boolean)
+      .filter((line) => !isConductorStatusLine(line)).map((line) => line.slice(3).trim());
+    return dirty.length ? { ok: false, stage: 'dirty_worktree', dirty } : null;
+  };
+  // Untracked source would not stop git rebase, but must never get swept into
+  // a ship commit. Untracked receipts and ignored files are not source dirt.
+  const beforeRebase = sourceDirt();
+  if (beforeRebase) return beforeRebase;
+  const rebase = run(['rebase', targetRef]);
   if (rebase.status !== 0) {
     const conflicts = String(run(['diff', '--name-only', '--diff-filter=U']).stdout || '')
       .trim().split('\n').filter(Boolean);
@@ -1499,11 +1550,7 @@ function landArrival({ worktreePath, git = null }) {
     // after a killed engine left modified/untracked files behind). An empty
     // conflicts list is never a conflict: name the dirty paths instead.
     if (!conflicts.length) {
-      const dirty = String(run(['status', '--porcelain']).stdout || '')
-        .split('\n')
-        .map((line) => line.slice(3).trim())
-        .filter(Boolean);
-      return { ok: false, stage: 'dirty_worktree', dirty };
+      return sourceDirt() || { ok: false, stage: 'rebase_failed', detail: String(rebase.stderr || rebase.stdout || '').trim() };
     }
     return { ok: false, stage: 'rebase_conflict', conflicts };
   }
@@ -1844,8 +1891,8 @@ function reviewOnlyEngineEnvironment(worktreePath, options = {}) {
   return environment;
 }
 
-function conductorGitEnvironment() {
-  const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+function conductorGitEnvironment(cwd) {
+  const env = gitNetworkEnvironment(process.env, cwd);
   for (const key of Object.keys(env)) {
     if (/^GIT_CONFIG_(?:COUNT|KEY_\d+|VALUE_\d+)$/.test(key)) delete env[key];
   }
@@ -1856,12 +1903,13 @@ function conductorGitEnvironment() {
   return env;
 }
 
-function remoteMasterOid(worktreePath, remote = 'origin') {
-  const result = spawnSync('git', ['ls-remote', '--exit-code', remote, 'refs/heads/master'], {
+function remoteMasterOid(worktreePath, remote = 'origin', branch) {
+  const result = spawnSync('git', ['ls-remote', '--exit-code', remote, `refs/heads/${branch}`], {
     cwd: worktreePath,
     encoding: 'utf8',
     timeout: 15000,
-    env: conductorGitEnvironment(),
+    env: conductorGitEnvironment(worktreePath),
+    killSignal: 'SIGKILL',
   });
   if (result.status !== 0) return '';
   return String(result.stdout || '').trim().split(/\s+/)[0] || '';
@@ -1872,7 +1920,8 @@ function remoteRefsDigest(worktreePath, remote = 'origin') {
     cwd: worktreePath,
     encoding: 'utf8',
     timeout: 30000,
-    env: conductorGitEnvironment(),
+    env: conductorGitEnvironment(worktreePath),
+    killSignal: 'SIGKILL',
   });
   if (result.status !== 0) return '';
   return crypto.createHash('sha256').update(String(result.stdout || '')).digest('hex');
@@ -1924,7 +1973,7 @@ function bareRefsDigest(gitDir) {
   return crypto.createHash('sha256').update(String(result.stdout || '')).digest('hex');
 }
 
-function prepareReviewSandbox({ root, taskId, engine }) {
+function prepareReviewSandbox({ root, taskId, engine, baseRef = '' }) {
   const run = (args, options = {}) => spawnSync('git', args, {
     cwd: options.cwd || root,
     encoding: 'utf8',
@@ -1934,7 +1983,8 @@ function prepareReviewSandbox({ root, taskId, engine }) {
   const runConductorGit = (args) => spawnSync('git', args, {
     cwd: root,
     encoding: 'utf8',
-    env: conductorGitEnvironment(),
+    env: conductorGitEnvironment(root),
+    killSignal: 'SIGKILL',
     timeout: 30000,
   });
   // `git` walks up to the nearest enclosing repository when `root` is not itself
@@ -1946,18 +1996,20 @@ function prepareReviewSandbox({ root, taskId, engine }) {
     || realpathOrResolve(String(toplevel.stdout || '').trim()) !== realpathOrResolve(root)) {
     return { ok: false, detail: 'review-only dispatch requires the workspace to be its own git repository' };
   }
-  const fetched = runConductorGit(['fetch', 'origin', 'master']);
+  baseRef = baseRef || resolveDispatchLandTarget(root);
+  const mainBranch = baseRef.replace(/^origin\//, '');
+  const fetched = runConductorGit(['fetch', 'origin', mainBranch]);
   const original = runConductorGit(['remote', 'get-url', 'origin']);
-  const base = run(['rev-parse', '--verify', 'origin/master^{commit}']);
+  const base = run(['rev-parse', '--verify', `${baseRef}^{commit}`]);
   if (fetched.status !== 0 || original.status !== 0 || base.status !== 0) {
-    return { ok: false, detail: 'review-only dispatch requires a current protected origin/master' };
+    return { ok: false, detail: `review-only dispatch requires a current protected ${baseRef}` };
   }
   const originalUrl = String(original.stdout || '').trim();
-  const protectedMaster = remoteMasterOid(root, originalUrl);
+  const protectedMaster = remoteMasterOid(root, originalUrl, mainBranch);
   const protectedRefs = remoteRefsDigest(root, originalUrl);
   const baseOid = String(base.stdout || '').trim();
   if (!protectedMaster || !protectedRefs || baseOid !== protectedMaster) {
-    return { ok: false, detail: 'review-only origin/master is not at the protected remote snapshot' };
+    return { ok: false, detail: `review-only ${baseRef} is not at the protected remote snapshot` };
   }
 
   const token = `${String(taskId || 'task').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'task'}-${process.pid}-${crypto.randomBytes(5).toString('hex')}`;
@@ -1978,20 +2030,20 @@ function prepareReviewSandbox({ root, taskId, engine }) {
 
   try {
     fs.mkdirSync(sandboxRoot, { recursive: true });
-    let result = run(['bundle', 'create', seedBundle, 'origin/master']);
+    let result = run(['bundle', 'create', seedBundle, baseRef]);
     if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'could not create seed bundle').trim());
-    result = run(['init', '--bare', '--initial-branch=master', gitDir], { cwd: sandboxRoot });
+    result = run(['init', '--bare', `--initial-branch=${mainBranch}`, gitDir], { cwd: sandboxRoot });
     if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'could not initialize sandbox object store').trim());
     result = spawnSync('git', ['--git-dir', gitDir, 'bundle', 'unbundle', seedBundle], { encoding: 'utf8', timeout: 30000 });
     if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'could not seed sandbox object store').trim());
-    result = run(['init', '--bare', '--initial-branch=master', quarantine], { cwd: sandboxRoot });
+    result = run(['init', '--bare', `--initial-branch=${mainBranch}`, quarantine], { cwd: sandboxRoot });
     if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'could not initialize quarantine remote').trim());
     result = spawnSync('git', ['--git-dir', quarantine, 'bundle', 'unbundle', seedBundle], { encoding: 'utf8', timeout: 30000 });
     if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'could not seed quarantine remote').trim());
     for (const [repo, ref, oid] of [
       [gitDir, `refs/heads/${branch}`, baseOid],
-      [gitDir, 'refs/remotes/origin/master', baseOid],
-      [quarantine, 'refs/heads/master', baseOid],
+      [gitDir, `refs/remotes/${baseRef}`, baseOid],
+      [quarantine, `refs/heads/${mainBranch}`, baseOid],
     ]) {
       result = spawnSync('git', ['--git-dir', repo, 'update-ref', ref, oid], { encoding: 'utf8' });
       if (result.status !== 0) throw new Error(String(result.stderr || `could not seed ${ref}`).trim());
@@ -2027,7 +2079,7 @@ function prepareReviewSandbox({ root, taskId, engine }) {
       owner: engine || 'one-lap',
       task: String(taskId || ''),
       branch,
-      base: 'origin/master',
+      base: baseRef,
       sealed_review_sandbox: true,
       created_at: new Date().toISOString(),
     }, null, 2)}\n`, 'utf8');
@@ -2044,6 +2096,8 @@ function prepareReviewSandbox({ root, taskId, engine }) {
       originalUrl,
       protectedMaster,
       protectedRefs,
+      baseRef,
+      mainBranch,
       quarantineRefs: bareRefsDigest(quarantine),
       branch,
       baseOid,
@@ -2075,9 +2129,9 @@ function reviewRemoteBoundaryState(worktreePath, boundary) {
       protected_master: boundary.protectedMaster,
     };
   }
-  const protectedMaster = remoteMasterOid(boundary.trustedRoot, boundary.originalUrl);
+  const protectedMaster = remoteMasterOid(boundary.trustedRoot, boundary.originalUrl, boundary.mainBranch);
   const protectedRefs = remoteRefsDigest(boundary.trustedRoot, boundary.originalUrl);
-  const quarantineMasterResult = spawnSync('git', ['--git-dir', boundary.quarantine, 'rev-parse', '--verify', 'refs/heads/master^{commit}'], { encoding: 'utf8' });
+  const quarantineMasterResult = spawnSync('git', ['--git-dir', boundary.quarantine, 'rev-parse', '--verify', `refs/heads/${boundary.mainBranch}^{commit}`], { encoding: 'utf8' });
   const quarantineMaster = quarantineMasterResult.status === 0 ? String(quarantineMasterResult.stdout || '').trim() : '';
   const quarantineRefs = bareRefsDigest(boundary.quarantine);
   if (!protectedMaster || !protectedRefs || protectedMaster !== boundary.protectedMaster || protectedRefs !== boundary.protectedRefs) {
@@ -2330,7 +2384,7 @@ function importReviewCommit(boundary, { cli, taskId, engine, expectedCommit = ''
   const allowedRefs = new Map([
     [`refs/heads/${boundary.branch}`, headOid],
     ['refs/remotes/origin/HEAD', boundary.baseOid],
-    ['refs/remotes/origin/master', boundary.baseOid],
+    [`refs/remotes/${boundary.baseRef}`, boundary.baseOid],
   ]);
   const refLines = String(refs.stdout || '').trim().split(/\r?\n/).filter(Boolean);
   const seenRefs = new Set();
@@ -2339,7 +2393,7 @@ function importReviewCommit(boundary, { cli, taskId, engine, expectedCommit = ''
     if (!allowedRefs.has(ref) || allowedRefs.get(ref) !== oid) return fail('sandbox_metadata_changed', `the worker created an unexpected Git ref (${ref || 'unknown'})`);
     seenRefs.add(ref);
   }
-  for (const ref of [`refs/heads/${boundary.branch}`, 'refs/remotes/origin/master']) {
+  for (const ref of [`refs/heads/${boundary.branch}`, `refs/remotes/${boundary.baseRef}`]) {
     if (!seenRefs.has(ref)) return fail('sandbox_metadata_changed', `the sealed sandbox is missing a required Git ref (${ref})`);
   }
 
@@ -2415,7 +2469,7 @@ function disposeReviewSandbox(boundary) {
   fs.rmSync(boundary.sandboxRoot, { recursive: true, force: true });
 }
 
-function inspectReviewChange(worktreePath, baseRef = 'origin/master') {
+function inspectReviewChange(worktreePath, baseRef = resolveDispatchLandTarget(worktreePath)) {
   const run = (args) => spawnSync('git', args, { cwd: worktreePath, encoding: 'utf8', env: trustedGitEnvironment() });
   const base = run(['rev-parse', '--verify', `${baseRef}^{commit}`]);
   const head = run(['rev-parse', '--verify', 'HEAD^{commit}']);
@@ -2533,6 +2587,7 @@ async function validateWithAttempts({
   task,
   worktreePath,
   executorEngine,
+  baseRef = resolveDispatchLandTarget(worktreePath),
   verifierCommand,
   validatorEngines,
   validatorDispatcher = null,
@@ -2581,7 +2636,7 @@ async function validateWithAttempts({
 
   // One prep pass per prep job for this task: a backup reviewer whose line
   // asks for the same prep reuses the brief the first reviewer's prep wrote.
-  const reviewPrompt = buildOneLapValidatorPrompt(task, { verifierCommand, executorEngine });
+  const reviewPrompt = buildOneLapValidatorPrompt(task, { verifierCommand, executorEngine, baseRef });
   const prepPasses = new Map();
   for (let index = 0; index < candidates.length; index += 1) {
     const validatorEngine = candidates[index];
@@ -2899,8 +2954,8 @@ function defaultDispatchStartCommit({ worktreePath, git = null } = {}) {
   return String(head.stdout || '').trim();
 }
 
-function defaultSelfLandCheck({ worktreePath, targetRef = DISPATCH_SELF_LAND_TARGET, startCommit = '', entry = null, git = null } = {}) {
-  const run = git || ((args) => spawnSync('git', args, { cwd: worktreePath, encoding: 'utf8' }));
+function defaultSelfLandCheck({ worktreePath, targetRef = resolveDispatchLandTarget(worktreePath), startCommit = '', entry = null, git = null } = {}) {
+  const run = git || boundedGit(worktreePath);
   const recordedStart = String(startCommit || (entry && entry.startCommit) || '').trim();
   if (!recordedStart) {
     return { ok: false, stage: 'self_land_check', reason: 'unknown_start_commit', target: targetRef, detail: 'dispatch start commit was not recorded' };
@@ -2954,7 +3009,7 @@ function defaultSelfLandCheck({ worktreePath, targetRef = DISPATCH_SELF_LAND_TAR
   const branch = String(targetRef || '').startsWith('origin/') ? String(targetRef).slice('origin/'.length) : '';
   const fetch = run(branch ? ['fetch', 'origin', `${branch}:refs/remotes/origin/${branch}`] : ['fetch', 'origin']);
   if (fetch.status !== 0) {
-    return { ok: false, stage: 'self_land_check', target: targetRef, start_commit: recordedStart, head, detail: String(fetch.stderr || fetch.stdout || '').trim() };
+    return { ok: false, stage: 'self_land_check', target: targetRef, start_commit: recordedStart, head, detail: gitFailureDetail(fetch) };
   }
   const ancestor = run(['merge-base', '--is-ancestor', 'HEAD', targetRef]);
   if (ancestor.status === 0) return { ok: true, stage: 'self_landed', target: targetRef, start_commit: recordedStart, head };
@@ -2988,13 +3043,14 @@ async function runFleetFlight({
   dispatcher = null,
   lander = null,
   rebase = null,
-  checkoutBase = 'origin/master',
+  checkoutBase = null,
   guardCliLink = guardGlobalCliLink,
   scoutAsk = null,
   clock = Date.now,
   prepAsk = undefined,
 } = {}) {
   const cli = ownCli || defaultOwnCli(root);
+  const landTarget = resolveDispatchLandTarget(root, checkoutBase);
   // Staff first, rank second: every task staffFlight returns already cleared
   // the safe-lane filter (not a decision row, no denied tags), so the rank
   // that pairs engines to those tasks is low stakes and the stretch zone
@@ -3059,13 +3115,13 @@ async function runFleetFlight({
   }));
   const restaffState = { used: false };
 
-  // Cut every build worktree from origin/master by default, not the launcher's
+  // Cut every build worktree from the protected mainline by default, not the launcher's
   // HEAD. A flight launched from a long-lived feature-branch checkout would
   // otherwise stack all that branch's commits onto the build branch, so
   // rebase-before-ship replays them onto master and pauses at rebase_conflict
   // (three backend pauses on members.py, 2026-07-05). --base overrides only
   // when the operator explicitly wants launcher-HEAD.
-  const startBaseArgs = checkoutBase ? ['--base', checkoutBase] : [];
+  const startBaseArgs = ['--base', landTarget];
   const prepared = [];
   for (const entry of staffed) {
     const claimed = cli(['task', 'claim', String(entry.task.display_id), '--as', `fleet-${entry.engine}`]);
@@ -3111,10 +3167,10 @@ async function runFleetFlight({
   // Land serially: rebase-before-ship, conflict pauses (never auto-resolve).
   const rebaseArrival = rebase || landArrival;
   const land = lander || (({ entry }) => {
-    const rebased = rebaseArrival({ worktreePath: entry.worktreePath });
+    const rebased = rebaseArrival({ worktreePath: entry.worktreePath, targetRef: landTarget });
     if (!rebased.ok) return rebased;
     const check = focusedCheck(entry.task) || 'git log -1 --oneline';
-    const shipped = shipWithRetry(cli, fleetShipArgs(entry, check), entry.worktreePath);
+    const shipped = shipWithRetry(cli, fleetShipArgs(entry, check, landTarget), entry.worktreePath);
     if (shipped.status !== 0 || !/done: worktree shipped/.test(shipped.stdout)) {
       return { ok: false, stage: 'ship', detail: shipFailureDetail(shipped) };
     }
@@ -3124,7 +3180,7 @@ async function runFleetFlight({
   for (const { entry, result } of results) {
     const activeEngine = result.engine || entry.engine;
     const landingEntry = { ...entry, engine: activeEngine };
-    if (result.restaffed) log(`    restaffed ${entry.task.display_id}: ${result.restaffed.from} -> ${result.restaffed.to} (${result.restaffed.reason})`);
+    if (result.restaffed) log(`    restaffed ${entry.task.display_id}: ${result.restaffed.from} -> ${result.restaffed.to} (${result.restaffed.detail || result.restaffed.reason})`);
     if (result.handover) log(`    handed over ${entry.task.display_id}: ${result.handover_reason}`);
     const buildFailure = detectDeadEngineDispatch(result);
     if (buildFailure) {
@@ -3133,14 +3189,14 @@ async function runFleetFlight({
         engine: activeEngine,
         stage: 'build',
         reason: buildFailure.reason,
-        detail: String(result.stderr || buildFailure.reason).slice(0, 200),
+        detail: buildFailure.detail || String(result.stderr || buildFailure.reason).slice(0, 200),
       };
       if (result.restaffed) paused.restaffed = result.restaffed;
       if (result.handover) paused.handover = result.handover;
       if (result.deadEngine) paused.deadEngine = result.deadEngine;
       flight.paused.push(paused);
       stampDispatchBrief(root, result.brief_id, 'fail', `build failed for ${entry.task.display_id}`);
-      log(`    ${activeEngine.padEnd(8)} ✗ build failed ${entry.task.display_id}, worktree kept for takeover`);
+      log(`    ${activeEngine.padEnd(8)} ✗ build failed ${entry.task.display_id}: ${plainDispatchFailureCause(result, buildFailure)}, worktree kept for takeover`);
       continue;
     }
     log(`    ${activeEngine.padEnd(8)} landing ${entry.task.display_id}...`);
@@ -3187,7 +3243,7 @@ async function runFleetFlight({
     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}`])),
-    baseRef: checkoutBase || 'origin/master',
+    baseRef: landTarget,
     log,
   });
 
@@ -3222,7 +3278,7 @@ function releaseUnstartedDispatchClaim(cli, { taskId, actor, detail }) {
 // paused task whose worktree holds no commits past base and nothing but
 // conductor litter gets its claim released; a paused task WITH work keeps the
 // claim so takeover stays attributed.
-function releasePausedClaimsWithoutWork(cli, { paused, worktreeByTask, actorByTask, baseRef = 'origin/master', log = () => {} }) {
+function releasePausedClaimsWithoutWork(cli, { paused, worktreeByTask, actorByTask, baseRef = '', log = () => {} }) {
   for (const row of paused || []) {
     if (row.stage === 'claim' || row.stage === 'task_lookup' || row.landed === true) continue; // no claim, or work already landed
     if (row.claim_released !== undefined) continue;
@@ -3231,7 +3287,9 @@ function releasePausedClaimsWithoutWork(cli, { paused, worktreeByTask, actorByTa
     if (!taskId || !actor) continue;
     const worktreePath = row.worktree || worktreeByTask.get(taskId) || '';
     if (worktreePath && fs.existsSync(worktreePath)) {
-      const ahead = spawnSync('git', ['-C', worktreePath, 'rev-list', '--count', `${baseRef}..HEAD`], { encoding: 'utf8' });
+      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.
@@ -3319,7 +3377,13 @@ async function runDispatchFlight({
   const cli = ownCli || defaultOwnCli(root);
   // Cut worktrees from, and check self-landing against, the workspace's real
   // protected branch, not a hard-coded origin/master (CLI-1298).
-  const landTarget = resolveDispatchLandTarget(root, checkoutBase);
+  const localBase = reviewOnly ? '' : localDispatchBase(root);
+  const localOnly = Boolean(localBase);
+  const proofOnly = reviewOnly || localOnly;
+  const landTarget = localOnly ? (checkoutBase || localBase) : resolveDispatchLandTarget(root, checkoutBase);
+  const localBranch = localOnly
+    ? String(spawnSync('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout || '').trim()
+    : '';
   const verify = verifier || (trustedVerifier ? defaultTrustedVerifyRunner : defaultVerifyRunner);
   const inspectChange = changeInspector || inspectReviewChange;
   const readStartCommit = startCommitReader || defaultDispatchStartCommit;
@@ -3339,7 +3403,8 @@ async function runDispatchFlight({
     paused: [],
   };
   if (yolo) flight.yolo = true;
-  if (reviewOnly) flight.review_only = true;
+  if (proofOnly) flight.review_only = true;
+  if (localOnly) flight.local_only = true;
   flight.actor = taskActor;
   if (receiptContext && typeof receiptContext === 'object') flight.context = receiptContext;
   const requiresIndependentValidator = reviewOnly && flight.context && flight.context.source === 'one_lap';
@@ -3371,7 +3436,7 @@ async function runDispatchFlight({
       let landingWorktreePath = '';
       let remoteBoundary = null;
       if (enforceRemoteBoundary) {
-        remoteBoundary = prepareReviewSandbox({ root, taskId, engine });
+        remoteBoundary = prepareReviewSandbox({ root, taskId, engine, baseRef: landTarget });
       } else {
         const started = cli(['worktree', 'start', '--agent', engine, '--task', `dispatch-${taskId.toLowerCase()}`, ...startBaseArgs]);
         const wt = (started.stdout.match(/next: cd (.+)/) || [])[1];
@@ -3405,13 +3470,13 @@ async function runDispatchFlight({
       }
       const worktreePath = enforceRemoteBoundary ? remoteBoundary.worktreePath : landingWorktreePath;
       const startCommit = yolo ? readStartCommit({ worktreePath }) : '';
-      const basePrompt = promptOverride || buildFleetPrompt(task, { worktreePath, yolo });
-      const safetyPrompt = reviewOnly
+      const basePrompt = promptOverride || buildFleetPrompt(task, { worktreePath, yolo: yolo && !localOnly });
+      const safetyPrompt = proofOnly
         ? `${basePrompt}\n\nSafety boundary: edit and test this checkout only. Do not push, merge, deploy, publish, send messages, change cloud state, install dependencies, or use credentials.`
         : basePrompt;
       const trustedPrompt = trustedVerifier
         ? `${safetyPrompt}\n\nTrusted verifier (run it bare before reporting done): ${trustedVerifier}`
-        : promptOverride;
+        : (localOnly ? safetyPrompt : promptOverride);
       prepared.push({
         task,
         taskId,
@@ -3518,16 +3583,16 @@ async function runDispatchFlight({
   const rebaseArrival = rebase || landArrival;
   const checkSelfLand = selfLandCheck || defaultSelfLandCheck;
   const land = lander || (({ entry }) => {
-    const rebased = enforceRemoteBoundary
+    const rebased = enforceRemoteBoundary || localOnly
       ? { ok: true, stage: 'frozen_base' }
-      : rebaseArrival({ worktreePath: entry.worktreePath });
+      : rebaseArrival({ worktreePath: entry.worktreePath, targetRef: landTarget });
     if (!rebased.ok) return rebased;
     if (enforceRemoteBoundary) {
       const candidate = reviewCandidateSnapshot(entry.remoteBoundary, entry.candidate);
       if (!candidate.ok) return candidate;
     }
-    const change = reviewOnly ? inspectChange(entry.worktreePath, landTarget) : null;
-    if (reviewOnly && (!change || change.has_change !== true)) {
+    const change = proofOnly ? inspectChange(entry.worktreePath, landTarget) : null;
+    if (proofOnly && (!change || change.has_change !== true)) {
       return {
         ok: false,
         stage: 'no_change',
@@ -3535,6 +3600,9 @@ async function runDispatchFlight({
         change: change || null,
       };
     }
+    if (localOnly && (!change.commit || change.dirty)) {
+      return { ok: false, stage: 'uncommitted_change', detail: 'commit the local change before merging it', change };
+    }
     if (enforceRemoteBoundary && (change.head !== entry.candidate.commit || change.dirty)) {
       return {
         ok: false,
@@ -3569,7 +3637,7 @@ async function runDispatchFlight({
       const candidate = reviewCandidateSnapshot(entry.remoteBoundary, entry.candidate);
       if (!candidate.ok) return { ...candidate, check, verifier_result: verifierResult };
     }
-    if (reviewOnly) {
+    if (proofOnly) {
       return {
         ok: true,
         stage: 'verified_for_review',
@@ -3579,7 +3647,7 @@ async function runDispatchFlight({
         change,
       };
     }
-    const shipped = shipWithRetry(cli, fleetShipArgs({ task: entry.task, engine: entry.engine || engine }, check), entry.worktreePath);
+    const shipped = shipWithRetry(cli, fleetShipArgs({ task: entry.task, engine: entry.engine || engine }, check, landTarget), entry.worktreePath);
     if (shipped.status !== 0 || !/done: worktree shipped/.test(shipped.stdout)) {
       return { ok: false, stage: 'ship', detail: shipFailureDetail(shipped) };
     }
@@ -3596,7 +3664,7 @@ async function runDispatchFlight({
     const activeEngine = result.engine || entry.engine || engine;
     const readyActor = explicitActor || `fleet-${activeEngine}`;
     const landingEntry = { ...entry, engine: activeEngine, candidate };
-    if (result.restaffed) log(`    restaffed ${entry.taskId}: ${result.restaffed.from} -> ${result.restaffed.to} (${result.restaffed.reason})`);
+    if (result.restaffed) log(`    restaffed ${entry.taskId}: ${result.restaffed.from} -> ${result.restaffed.to} (${result.restaffed.detail || result.restaffed.reason})`);
     if (result.handover) log(`    handed over ${entry.taskId}: ${result.handover_reason}`);
     const buildFailure = detectDeadEngineDispatch(result);
     if (buildFailure) {
@@ -3605,7 +3673,7 @@ async function runDispatchFlight({
         engine: activeEngine,
         stage: 'build',
         reason: buildFailure.reason,
-        detail: String(result.stderr || buildFailure.reason).slice(0, 300),
+        detail: buildFailure.detail || String(result.stderr || buildFailure.reason).slice(0, 300),
         worktree: entry.worktreePath,
       };
       if (result.restaffed) paused.restaffed = result.restaffed;
@@ -3613,7 +3681,7 @@ async function runDispatchFlight({
       if (result.deadEngine) paused.deadEngine = result.deadEngine;
       flight.paused.push(paused);
       stampDispatchBrief(root, result.brief_id, 'fail', `build failed for ${entry.taskId}`);
-      log(`    ✗ build failed ${entry.taskId}, worktree kept for takeover`);
+      log(`    ✗ build failed ${entry.taskId}: ${plainDispatchFailureCause(result, buildFailure)}, worktree kept for takeover`);
       continue;
     }
     if (enforceRemoteBoundary && (!candidate || candidate.ok !== true)) {
@@ -3646,7 +3714,7 @@ async function runDispatchFlight({
         continue;
       }
     }
-    if (yolo) {
+    if (yolo && !localOnly) {
       log(`    checking self-land ${entry.taskId}...`);
       const selfLanded = checkSelfLand({
         entry,
@@ -3690,7 +3758,7 @@ async function runDispatchFlight({
       }
       continue;
     }
-    log(`    ${reviewOnly ? 'checking' : 'landing'} ${entry.taskId}...`);
+    log(`    ${proofOnly ? 'checking' : 'landing'} ${entry.taskId}...`);
     const landed = land({ entry: landingEntry, result });
     stampDispatchResultVerification(
       flight,
@@ -3702,7 +3770,7 @@ async function runDispatchFlight({
     if (landed.ok) {
       const verifyTail = String(landed.verifyOutput || '').trim().slice(-1200).replace(/\n/g, ' ');
       const restaffProof = result.restaffed ? ` Restaffed from ${result.restaffed.from} to ${result.restaffed.to} (${result.restaffed.reason}).` : '';
-      if (reviewOnly) {
+      if (proofOnly) {
         let finalMaster = entry.remoteMasterBefore;
         const boundaryBeforeReview = enforceRemoteBoundary
           ? reviewRemoteBoundaryState(entry.worktreePath, entry.remoteBoundary)
@@ -3746,6 +3814,7 @@ async function runDispatchFlight({
             task: entry.task,
             worktreePath: entry.worktreePath,
             executorEngine: activeEngine,
+            baseRef: entry.remoteBoundary ? entry.remoteBoundary.baseOid : landTarget,
             verifierCommand: landed.check,
             validatorEngines,
             validatorDispatcher,
@@ -3893,11 +3962,13 @@ async function runDispatchFlight({
           finalMaster = boundaryAfterImport.protected_master || finalMaster;
           disposeReviewSandbox(entry.remoteBoundary);
         }
-        const shipArgs = fleetShipArgs({ task: entry.task, engine: activeEngine }, landed.check);
+        const shipArgs = fleetShipArgs({ task: entry.task, engine: activeEngine }, landed.check, landTarget);
         const shellQuote = (value) => /^[A-Za-z0-9_./:-]+$/.test(String(value))
           ? String(value)
           : `'${String(value).replace(/'/g, `'"'"'`)}'`;
-        const nextCommand = `cd ${shellQuote(reviewWorktreePath)} && atris ${shipArgs.map(shellQuote).join(' ')}`;
+        const nextCommand = localOnly
+          ? `cd ${shellQuote(root)}${localBranch ? ` && git switch ${shellQuote(localBranch)}` : ''} && git merge --ff-only ${shellQuote(reviewChange.commit)}`
+          : `cd ${shellQuote(reviewWorktreePath)} && atris ${shipArgs.map(shellQuote).join(' ')}`;
         const readyRow = {
           task: entry.taskId,
           engine: activeEngine,
@@ -3917,7 +3988,7 @@ async function runDispatchFlight({
         if (result.restaffed) readyRow.restaffed = result.restaffed;
 
         flight.ready.push(readyRow);
-        writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly, enforceRemoteBoundary });
+        writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly: proofOnly, enforceRemoteBoundary });
         const verificationCommit = String(reviewChange.source_commit || reviewChange.commit || reviewChange.head || '').trim();
         const verificationCitation = verificationCommit
           ? ` Verification snapshot: commit ${verificationCommit}${reviewChange.dirty ? ' with a worktree diff' : ''}; the declared verifier passed (exit 0).`
@@ -3946,7 +4017,7 @@ async function runDispatchFlight({
             worktree: reviewWorktreePath,
             change: reviewChange,
           });
-          writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly, enforceRemoteBoundary });
+          writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly: proofOnly, enforceRemoteBoundary });
           stampDispatchBrief(root, result.brief_id, 'partial', `verified ${entry.taskId}, but task ready failed`);
           log(`    paused ${entry.taskId} at task_ready - worktree kept`);
           continue;
@@ -3954,6 +4025,10 @@ async function runDispatchFlight({
         readyRow.review_recorded = true;
         stampDispatchBrief(root, result.brief_id, 'pass', `verified ${entry.taskId} for Review`);
         log(`    proof ready ${entry.taskId}`);
+        if (localOnly) {
+          log('    the verified change is ready on a local branch. review it, then merge it locally:');
+          log(`    next: ${nextCommand}`);
+        }
         continue;
       }
       const landedRow = { task: entry.taskId, engine: activeEngine, check: landed.check };
@@ -3968,7 +4043,7 @@ async function runDispatchFlight({
         '--checked', `${landed.check} passed before landing`,
         '--tested', 'The requested behavior passed its declared verifier.',
         '--as', readyActor,
-      ], { flight, landedRow, worktree: entry.worktreePath, save: () => writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly, enforceRemoteBoundary }) });
+      ], { flight, landedRow, worktree: entry.worktreePath, save: () => writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly: proofOnly, enforceRemoteBoundary }) });
       if (!reviewRecorded) {
         stampDispatchBrief(root, result.brief_id, 'partial', `landed ${entry.taskId}, but task ready failed`);
         log('    the change landed, but saving its proof failed. repair the task record before starting more work.');
@@ -4004,7 +4079,7 @@ async function runDispatchFlight({
   });
   flight.status = flight.paused.length ? 'failed' : 'completed';
   flight.finished_at = new Date().toISOString();
-  writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly, enforceRemoteBoundary });
+  writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly: proofOnly, enforceRemoteBoundary });
   log('');
   if (engine === 'fable' && flight.paused.length) {
     const paused = flight.paused[0];
@@ -4012,7 +4087,7 @@ async function runDispatchFlight({
     const cause = plainDispatchFailureCause(failed && failed.result, paused);
     log(`  fable handoff failed: ${cause}. receipt: ${path.relative(root, receiptPath)}`);
   }
-  const completedLabel = reviewOnly ? `${flight.ready.length} proof ready` : `${flight.landed.length} landed`;
+  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)}`);
   log('');
   return flight;