Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

89.7 KB
Raw Blame
import { isLegacyDeepAudit } from '../lib/auditWorkflow.js';
/**
 * Agent Worktree Cleanup
 *
 * Post-completion worktree handling for agents: merge-or-PR the worktree
 * branch, drive the multi-reviewer review-loop follow-up, and retain
 * completion recovery when a merge or PR creation fails. Extracted from
 * agentLifecycle.js as a self-contained leaf so the completion-cleanup
 * orchestrator (agentCompletionCleanup.js) can import it without a circular
 * dependency back into agentLifecycle.js. Consumers import these functions from
 * here directly — the agentLifecycle.js pass-through re-exports were retired
 * with the subAgentSpawner barrel (#3450).
 */

import { existsSync } from 'fs';
import { isDeepStrictEqual } from 'node:util';
import { PORTOS_APP_ID } from '../lib/appIdentity.js';
import { join } from 'path';
import { emitLog } from './cosEvents.js';
import { addTask, updateTask } from './cosTaskStore.js';
import { forceSpawnTask } from './cos.js';
import { getAgents } from './cosAgentLifecycle.js';
import * as git from './git.js';
import { resolveTaskHookType } from './taskTypeHooks.js';
import { removeWorktree, classifyWorktreeDirt, listWorktrees } from './worktreeManager.js';
import { hasClaimFlowContract } from '../lib/claimFlowTaskTypes.js';
import { claimContinuationPointer } from '../lib/claimContinuation.js';
import { isTruthyMeta } from './agentState.js';
import { PATHS } from '../lib/fileUtils.js';
import { execGit } from '../lib/execGit.js';
import { isRetryHoldOwner, clearedRetryHoldMetadata } from '../lib/taskRetryHold.js';
import { resolveTaskTargetBranch, resolveTaskRemoteBranch, shouldStripTaskTargetBranch } from '../lib/taskTargetBranch.js';
import { ServerError } from '../lib/errorHandler.js';
import { detectForgeCli } from '../lib/gitForge.js';
import { normalizeForkHead } from '../lib/forkHead.js';
import { PR_COMPLETIONS, resolvePrCompletion, PR_COMPLETION_VALUES, PR_CREATION, PR_MISSING_CATEGORY, leavesPrForHuman, prClaimWasVerified } from '../lib/prDisposition.js';
import { DEFAULT_REVIEWER, DEFAULT_REVIEWERS, DEFAULT_REVIEW_STOP_MODE, MODEL_SELECTABLE_REVIEWERS, EFFORT_SELECTABLE_REVIEWERS, isProviderReviewer, normalizeReviewers, normalizeReviewUsernames, normalizeOptionalReviewers, normalizeReviewerMaxRounds, prioritizeToolFreeReviewers } from '../lib/reviewerConfig.js';

// In-flight cleanup per agentId, so two completion paths racing to clean the
// SAME agent coalesce onto one run instead of tripping over each other.
//
// A completing agent reaches cleanup twice by design: the runner path
// (`handleAgentCompletion` → `runAgentCompletionCleanup`) AND the spawner's
// `finally` safety net (agentTuiSpawning.js / agentCliSpawning.js), which fires
// unconditionally so a throw from `finalizeAgent` can never strand a worktree.
// Neither knows about the other, and they are driven by independent events, so
// they overlap. The loser then ran `git status --porcelain` while the winner was
// mid-`git worktree remove --force`, saw the in-progress deletions as ` D <path>`
// dirt, and reported "Worktree preserved — uncommitted changes detected" for a
// worktree that removed cleanly milliseconds later — a false warning AND a false
// user notification on a successful run (observed on agent-ce67bb09, whose PR had
// already merged). Sanctioned by the Security Model's re-entrancy-guard carve-out:
// this is one actor's duplicate in-flight operation, not two competing humans.
const inFlightCleanups = new Map();
// Fail closed even when the agent store cannot persist the hold. Normally the
// persisted metadata owns recovery across restarts; this covers sibling cleanup
// callbacks in the process where that write failed.
const publicationHolds = new Map();


/**
 * Clean up a worktree for a completed agent.
 * Reads worktree metadata from the agent's registered state and removes the worktree.
 * `prCreation` (see `PR_CREATION`) decides who opens the change request:
 * `'always'` pushes and creates one instead of auto-merging; `'if-missing'` does
 * that only when the forge confirms the agent — which owned its own PR workflow —
 * opened none (#3733); `'never'` leaves it entirely to the agent.
 * `prCompletion` decides whether the PR is reviewed then merged, merged after
 * green CI, or intentionally left open. The explicit leave-open policy does
 * not spawn a post-PR agent.
 * `reviewers` is the ordered reviewer list (e.g. `[codex, antigravity, copilot]`); the native
 * GitHub Copilot review is pre-requested here only when copilot LEADS the list (otherwise
 * the follow-up requests it at its turn so Copilot sees the post-fix diff). `reviewStopMode`
 * (`all`/`on-findings`/`on-clean`) and `reviewerApplies` are threaded into the follow-up's
 * metadata. CLI reviewers (claude/antigravity/codex/grok) are always driven by the follow-up agent,
 * which works on any forge; copilot is GitHub-only and dropped on non-GitHub remotes.
 * When skipMerge is true (review-loop follow-up agents), the cleanup never auto-merges
 * the worktree branch into the source workspace because `gh pr merge` already handled it.
 * Otherwise, merges the worktree branch back to the source branch on success.
 *
 * Re-entrant per `agentId`: a second call that arrives while the first is still
 * running joins it and resolves with the SAME warnings rather than starting a
 * competing pass (see `inFlightCleanups`). The joiner's `options` are therefore
 * ignored — one completing agent gets one cleanup, and the two duplicate callers
 * this guards against derive their options from the same task metadata anyway.
 */
export async function cleanupAgentWorktree(agentId, success, options = {}) {
  const existing = inFlightCleanups.get(agentId);
  // Join the pass already underway. Its warnings are the run's warnings — the
  // duplicate caller must not re-derive them from a half-removed worktree.
  if (existing) return existing;

  const run = runCleanupAgentWorktree(agentId, success, options);
  const settled = run.finally(() => { inFlightCleanups.delete(agentId); });
  inFlightCleanups.set(agentId, settled);

  // The audit hangs off THIS wrapper rather than off `runCleanupAgentWorktree`,
  // so its disposition handlers do not each need the call, and because every
  // completion path — runner, TUI `finish()`, direct-CLI, the manual stop in
  // agentManagement — funnels through here. One `.then` on `run` means a
  // duplicate completion callback that JOINS the in-flight pass audits once.
  //
  // Detached, NOT awaited: it makes two network calls and nothing downstream
  // consumes its result, while the callers awaiting cleanup still owe the run a
  // retry-hold release, a lane release and a shell-session kill. Only
  // `originalTask` is captured — closing over `options` would pin the whole TUI
  // output buffer for the duration of the probes.
  const originalTask = options?.originalTask || null;
  run.then(
    (warnings) => Promise.all([
      auditRepoState(agentId, success, originalTask, warnings)
        .catch(err => emitLog('warn', `🔎 Repo-state audit failed for ${agentId}: ${err.message}`, { agentId })),
      auditMergeGate(agentId, originalTask)
        .catch(err => emitLog('warn', `🚦 Merge-gate audit failed for ${agentId}: ${err.message}`, { agentId })),
    ]),
    // A cleanup that threw has no end state to audit; `settled` still rejects.
    () => {}
  // Nothing awaits this chain, so a throw from the reporting itself would surface
  // as an unhandled rejection and take the process down outside any request.
  ).catch(() => {});

  return settled;
}

/**
 * Post-cleanup repo-state audit — did this run actually leave the repository the
 * way its task asked? `verifyAgentRepoState` itself decides whether the run is
 * even auditable, and files a recovery task when it is not clean.
 *
 * Imported lazily so the cleanup graph doesn't pull the verification module's
 * branch-reconcile / apps / github reach into every consumer's module-init.
 */
async function auditRepoState(agentId, success, originalTask, warnings) {
  const { verifyAgentRepoState } = await import('./agentRepoStateVerification.js');
  // `getAgentRecord`, not `getAgent` — the audit reads three worktree metadata
  // fields and has no use for the run's whole output.txt.
  const { getAgentRecord } = await import('./cosAgentLifecycle.js');
  const agentState = await getAgentRecord(agentId).catch(() => null);
  if (publicationHolds.has(agentId) || ['running', 'blocked'].includes(agentState?.metadata?.publicationValidation?.status)) return;
  await verifyAgentRepoState({
    agentId,
    task: originalTask,
    agentState,
    success,
    prExpected: isTruthyMeta(originalTask?.metadata?.openPR),
    cleanupWarnings: warnings || [],
  });
}

/**
 * Post-merge gate audit (#12549): did a claim run's merged PR hold the merge
 * admission lease and land on green checks? Detection only; it flags and files
 * one default-branch recovery task. Lazily imported like the repo-state audit.
 */
async function auditMergeGate(agentId, originalTask) {
  const { auditClaimMergeGate } = await import('./mergeGateAudit.js');
  const { getAgentRecord } = await import('./cosAgentLifecycle.js');
  const agentState = await getAgentRecord(agentId).catch(() => null);
  if (!agentState) return;
  await auditClaimMergeGate({ agentId, task: originalTask, agentState });
}

// A disposition is selected once, after forge evidence is available. Merge is
// still governed by success/skipMerge even for stand-down: the existing local
// cleanup contract is independent of who opened the PR.
const WORKTREE_DISPOSITIONS = Object.freeze({
  'not-a-worktree': Object.freeze({ merge: false }),
  discard: Object.freeze({ merge: false }),
  'open-pr': Object.freeze({ merge: false }),
  'stand-down': Object.freeze({}),
  'stand-down-uncertain': Object.freeze({}),
  'stranded-pr-handoff': Object.freeze({}),
  'delivered-pr': Object.freeze({ merge: false }),
  'merge-or-preserve': Object.freeze({}),
});

/** Pure policy: unknown forge evidence must never authorize a duplicate PR. */
export function resolveWorktreeDisposition({ isWorktree, success, prCreation, discardWorktree, skipMerge, prClaimVerdict }) {
  let name = 'merge-or-preserve';
  if (isWorktree === false) name = 'not-a-worktree';
  else if (discardWorktree) name = 'discard';
  else if (prCreation === PR_CREATION.IF_MISSING) {
    if (success) {
      if (prClaimVerdict?.category === PR_MISSING_CATEGORY) name = 'open-pr';
      else name = prClaimWasVerified(prClaimVerdict) ? 'stand-down' : 'stand-down-uncertain';
    } else if (prClaimVerdict?.mergedExactHead === true) {
      name = 'delivered-pr';
    } else if (prClaimVerdict?.status === 'found' && prClaimVerdict.url) {
      name = 'stranded-pr-handoff';
    }
  } else if (success && prCreation === PR_CREATION.ALWAYS) name = 'open-pr';

  return {
    disposition: name,
    merge: success && !skipMerge,
    ...WORKTREE_DISPOSITIONS[name],
  };
}

async function worktreeCleanupContext(agentId, options) {
  const { getAgent } = await import('./cosAgentLifecycle.js');
  const agentState = await getAgent(agentId).catch(() => null);
  const metadata = agentState?.metadata;
  if (!metadata?.isWorktree || metadata.isPersistentWorktree) return { isWorktree: false };
  const { sourceWorkspace, worktreeBranch } = metadata;
  if (!sourceWorkspace || !worktreeBranch) return { isWorktree: false };
  const normalized = cleanupOptions(options);
  return {
    ...normalized,
    ...(normalized.originalTask?.metadata?.prCompletion === PR_COMPLETIONS.DRAFT ? { prCompletion: PR_COMPLETIONS.LEAVE_OPEN, skipMerge: true } : {}),
    isWorktree: true, agentId, sourceWorkspace, worktreeBranch,
    discardWorktree: isTruthyMeta(normalized.originalTask?.metadata?.discardWorktree),
    worktreePath: metadata.workspacePath || join(PATHS.worktrees, agentId),
    publicationValidation: publicationHolds.get(agentId) || metadata.publicationValidation,
    runtimeVerificationRequested: agentState?.result?.taskOutcome?.recovery?.mode === 'runtime',
    taskId: agentState?.taskId || normalized.originalTask?.id,
    securityScan: metadata.securityScan,
    securityScanControl: metadata.securityScanControl,
    warnings: [],
  };
}

async function probeWorktreePr(context, success) {
  if (!context.isWorktree || context.discardWorktree || context.prCreation !== PR_CREATION.IF_MISSING) return null;
  const { worktreePath, worktreeBranch, agentOutput } = context;
  if (success) {
    const { verifyPrClaim } = await import('./agentFinalization.js');
    // `agentOutput` (the run's output buffer) rides along so the probe can
    // recognize the parallel-claim stand-down the same way finalize did —
    // without it, cleanup would re-ask the forge, see "no PR", and open a
    // DUPLICATE of the change request the summary says already landed.
    const { extractFinalSummary } = await import('./agentSummaryExtraction.js');
    const agentSummary = extractFinalSummary(agentOutput);
    return verifyPrClaim({ task: context.originalTask, workspacePath: worktreePath, success: true, prExpected: true, agentSummary })
      .catch(err => ({ ok: false, category: 'forge-unreachable', message: err.message }));
  }
  const { findPullRequestForBranch } = await import('./github.js');
  const forge = await git.resolveForgeForRepo(worktreePath).catch(() => null);
  if (!forge) return { status: 'unavailable' };
  const found = await findPullRequestForBranch(worktreeBranch, { cwd: worktreePath, env: forge.env || null })
    .catch(() => ({ status: 'unavailable' }));
  if (found.status === 'found' && String(found.detail).toUpperCase() === 'MERGED' && found.headRefOid
    && !leavesPrForHuman(context.originalTask)) {
    const tip = await execGit(['rev-parse', '--verify', `refs/heads/${worktreeBranch}`], context.sourceWorkspace,
      { ignoreExitCode: true }).catch(() => null);
    if (tip?.exitCode === 0 && tip.stdout.trim() === found.headRefOid) return { ...found, mergedExactHead: true };
  }
  return found;
}

async function runCleanupAgentWorktree(agentId, success, options = {}) {
  const context = await worktreeCleanupContext(agentId, options);
  if (context.runtimeVerificationRequested) {
    const { getTaskById } = await import('./cosTaskStore.js');
    const held = context.taskId ? await getTaskById(context.taskId) : null;
    if (held?.metadata?.runtimeVerificationId === `${held.id}:${agentId}`
      && held.metadata.runtimeVerification?.agentId === agentId) return [];
  }
  if (['running', 'blocked'].includes(context.publicationValidation?.status)) {
    return [`Publication validation ${context.publicationValidation.status} for ${context.worktreeBranch}; worktree preserved at ${context.worktreePath}. Resume the task after resolving the validation outcome.`];
  }
  const verdict = await probeWorktreePr(context, success);
  const disposition = resolveWorktreeDisposition({ ...context, success, prClaimVerdict: verdict });
  reportWorktreeDisposition(context, disposition, verdict);
  switch (disposition.disposition) {
    case 'not-a-worktree':
      return [];
    case 'discard':
      return discardAgentWorktree(context);
    case 'open-pr':
      return openWorktreePullRequest(context);
    case 'delivered-pr':
      await mergeOrPreserveWorktree({ ...context, skipMerge: true }, disposition);
      break;
    case 'stranded-pr-handoff': {
      const released = await mergeOrPreserveWorktree(context, disposition);
      if (released?.cleanupIncomplete) {
        deferFollowUpWhileBranchHeld(context, verdict.url);
        break;
      }
      await handoffFollowUpAfterRelease(context, verdict.url, {
        prCompletion: PR_COMPLETION_VALUES.includes(context.prCompletion)
          ? context.prCompletion : PR_COMPLETIONS.REVIEW_THEN_MERGE,
      }, 'orphaned');
      break;
    }
    case 'stand-down':
    case 'stand-down-uncertain':
    case 'merge-or-preserve':
      await mergeOrPreserveWorktree(context, disposition);
      break;
  }
  return context.warnings;
}

function reportWorktreeDisposition({ agentId, worktreeBranch, prCreation, warnings }, { disposition }, verdict) {
  switch (disposition) {
    case 'open-pr':
      if (prCreation !== PR_CREATION.IF_MISSING) break;
      emitLog('warn', `🌳 ${agentId} owned its PR workflow but opened no pull request for ${worktreeBranch} — PortOS is opening one`, { agentId, branchName: worktreeBranch });
      warnings.push(`Agent ${agentId} was told to open its own pull request for ${worktreeBranch} but did not; PortOS opened it instead.`);
      break;
    case 'stand-down':
      emitLog('info', `🌳 ${agentId} opened its own pull request for ${worktreeBranch} — PortOS is standing down`, { agentId, branchName: worktreeBranch });
      break;
    case 'stand-down-uncertain': {
      const why = verdict?.category || 'nothing to verify against';
      emitLog('warn', `🌳 Could not confirm a pull request for ${worktreeBranch} (${why}) — keeping the branch rather than opening a possible duplicate`, { agentId, branchName: worktreeBranch });
      warnings.push(`Could not confirm a pull request for ${worktreeBranch} (${why}); the branch was preserved for manual follow-up rather than risking a duplicate PR.`);
      break;
    }
    case 'stranded-pr-handoff':
      emitLog('warn', `🌳 ${agentId} failed after opening ${verdict.url} — handing the PR to a follow-up so it isn't stranded`, { agentId, prUrl: verdict.url, branchName: worktreeBranch });
      warnings.push(`Agent ${agentId} failed after opening ${verdict.url}; a follow-up was queued to land it.`);
      break;
  }
}

function cleanupOptions({ prCreation = PR_CREATION.NEVER, prCompletion = null, requestCopilotReview: legacyRequestCopilotReview = false, reviewers, usernames = [], optionalReviewers = [], reviewerMaxRounds = {}, reviewStopMode = DEFAULT_REVIEW_STOP_MODE, reviewerApplies = false, reviewerModels = null, reviewerEfforts = null, skipMerge = false, description = null, agentOutput = null, originalTask = null } = {}) {
  return { prCreation, prCompletion, legacyRequestCopilotReview, reviewers, usernames,
    optionalReviewers, reviewerMaxRounds, reviewStopMode, reviewerApplies,
    reviewerModels, reviewerEfforts, skipMerge, description, agentOutput, originalTask };
}

// A lockfile-only diff is a legitimate deliverable for dependency-updates only.
export const lockfileDeliverable = (task) => (resolveTaskHookType(task) === 'dependency-updates' ? { preserveLockfiles: true } : {});

async function discardAgentWorktree({ agentId, sourceWorkspace, worktreeBranch }) {
  emitLog('info', `🌳 Discarding worktree for reasoning agent ${agentId} (no merge, no PR)`, { agentId, branchName: worktreeBranch });
  // `discardDirt`: the discard prompt explicitly invites scratch edits ("only
  // the completion sentinel is kept"), and removeWorktree otherwise ABORTS on
  // any non-lockfile dirt — so an agent that took its own prompt at its word
  // stranded a full checkout on disk, once per run, forever.
  const result = await removeWorktree(agentId, sourceWorkspace, worktreeBranch, { merge: false, discardDirt: true }).catch(err => {
    emitLog('warn', `🌳 Worktree discard failed for ${agentId}: ${err.message}`, { agentId });
    return { warnings: [`Worktree discard failed: ${err.message}`] };
  });
  return result?.warnings || [];
}

async function openWorktreePullRequest(context) {
  const { agentId, sourceWorkspace, worktreeBranch, worktreePath, warnings, description, agentOutput } = context;
  emitLog('info', `🌳 Opening PR for worktree agent ${agentId} branch ${worktreeBranch}`, { agentId, branchName: worktreeBranch });

  if (context.originalTask?.metadata?.app === PORTOS_APP_ID) {
    const { updateAgent } = await import('./cosAgentLifecycle.js');
    try {
      publicationHolds.set(agentId, { status: 'running' });
      await updateAgent(agentId, { metadata: { publicationValidation: { status: 'running', startedAt: new Date().toISOString() } } });
      const { validatePublication } = await import('./publicationValidation.js');
      const validation = await validatePublication(context);
      publicationHolds.set(agentId, validation);
      await updateAgent(agentId, { metadata: { publicationValidation: validation } });
      if (validation.status !== 'passed') {
        warnings.push(`Publication validation blocked for ${worktreeBranch}: ${validation.reason}. Worktree preserved at ${worktreePath}; resolve validation before resuming the task.`);
        return warnings;
      }
      publicationHolds.delete(agentId);
    } catch (error) {
      publicationHolds.set(agentId, { status: 'blocked', reason: 'recording-failed' });
      warnings.push(`Publication validation could not be recorded for ${worktreeBranch}: ${error.message}. Worktree preserved at ${worktreePath}.`);
      return warnings;
    }
  }

  const [pushResult, branchInfo] = await Promise.all([
    git.push(worktreePath, worktreeBranch).then(() => true).catch(err => {
      emitLog('warn', `🌳 Failed to push worktree branch ${worktreeBranch}: ${err.message}`, { agentId });
      return false;
    }),
    git.getRepoBranches(sourceWorkspace).catch(() => ({ baseBranch: null, devBranch: null }))
  ]);

  if (!pushResult) {
    warnings.push(`Push failed for branch ${worktreeBranch} — worktree preserved at ${worktreePath} for manual retry`);
    emitLog('warn', `🌳 Push failed for ${worktreeBranch} — worktree preserved at ${worktreePath} for manual retry`, { agentId, branchName: worktreeBranch });
    return warnings;
  }
  let targetBranch = branchInfo.baseBranch;
  if (!targetBranch) {
    targetBranch = await git.getDefaultBranch(sourceWorkspace, { allowRemote: false }).catch(() => null) || 'main';
  }
  const prTitle = await git.suggestPRTitle(worktreePath, targetBranch, worktreeBranch, description);

  const prBody = await git.generatePRDescription(worktreePath, targetBranch, worktreeBranch, agentOutput, context.securityScan, context.securityScanControl);

  const prResult = await git.createPR(worktreePath, {
    title: prTitle,
    body: prBody,
    base: targetBranch,
    head: worktreeBranch,
    ...(context.originalTask?.metadata?.prCompletion === PR_COMPLETIONS.DRAFT ? { draft: true } : {})
  }).catch(err => {
    emitLog('warn', `🌳 Failed to create PR for ${worktreeBranch}: ${err.message}`, { agentId });
    return null;
  });

  if (!prResult?.success) return handlePrCreationFailure(context, prResult, targetBranch);
  if (context.originalTask?.metadata?.prCompletion === PR_COMPLETIONS.DRAFT) {
    const { verifyPrClaim } = await import('./agentFinalization.js');
    const verdict = await verifyPrClaim({ task: context.originalTask, workspacePath: worktreePath, success: true, prExpected: true })
      .catch(() => ({ ok: false }));
    if (!verdict?.ok || !verdict.branch) {
      warnings.push(`Draft PR disposition could not be verified for ${worktreeBranch}; worktree preserved for review`);
      return warnings;
    }
  }
  return completeOpenedPullRequest(context, prResult);
}

async function handlePrCreationFailure({ agentId, sourceWorkspace, worktreeBranch, warnings, originalTask }, prResult, targetBranch) {
  const reason = prResult?.error || 'unknown error (createPR returned null or threw)';

  // "No commits between X and Y" means the agent made no code changes.
  // Clean up the worktree silently — nothing to review or merge.
  // Also delete the remote branch (it was pushed before PR creation).
  if (reason.includes('No commits between')) {
    emitLog('info', `🌳 No commits on ${worktreeBranch} vs ${targetBranch} — agent made no changes, cleaning up`, { agentId });
    await git.deleteBranch(sourceWorkspace, worktreeBranch, { remote: true }).catch(err => {
      emitLog('warn', `🌳 Remote branch delete failed for ${worktreeBranch}: ${err.message}`, { agentId });
      warnings.push(`Remote branch delete failed for ${worktreeBranch}: ${err.message}`);
    });
    const result = await removeWorktree(agentId, sourceWorkspace, worktreeBranch, { merge: false, ...lockfileDeliverable(originalTask) }).catch(err => {
      emitLog('warn', `🌳 Worktree cleanup failed for ${agentId}: ${err.message}`, { agentId });
      return { warnings: [`Worktree cleanup failed for ${agentId}: ${err.message}`] };
    });
    warnings.push(...(result?.warnings || []));
    return warnings;
  }

  const cliName = prResult?.cli || 'gh';
  const authHint = prResult?.account
    ? ` (${cliName} authed as ${prResult.account} for ${prResult.owner})`
    : prResult?.owner
      ? ` (${cliName} on ${prResult.host || prResult.owner} — no account auto-pinned)`
      : '';
  emitLog('error', `🌳 PR creation failed for ${worktreeBranch}${authHint}: ${reason}`, { agentId, branchName: worktreeBranch, cli: prResult?.cli, account: prResult?.account, owner: prResult?.owner, host: prResult?.host });
  warnings.push(`PR creation failed for branch ${worktreeBranch}: ${reason}. Worktree preserved for manual PR creation.`);
  return warnings;
}

async function completeOpenedPullRequest(context, prResult) {
  const { agentId, sourceWorkspace, worktreeBranch, warnings, prCompletion,
    legacyRequestCopilotReview, reviewers, originalTask } = context;
  const { recordBranchCompletionPolicy } = await import('./branchCompletionPolicy.js');
  await recordBranchCompletionPolicy({ agentId, task: originalTask, repoPath: sourceWorkspace,
    branch: worktreeBranch, prUrl: prResult.url });
  const cliName = prResult.cli || 'gh';
  emitLog('success', `🌳 Created PR: ${prResult.url} (${cliName}${prResult.account ? ` authed as ${prResult.account}` : ''})`, { agentId, branchName: worktreeBranch, cli: prResult.cli, account: prResult.account, owner: prResult.owner, host: prResult.host });

  // Production completion paths pass a resolver-backed policy. Keep the
  // former option as a narrow compatibility fallback for direct callers.
  const resolvedPrCompletion = PR_COMPLETION_VALUES.includes(prCompletion)
    ? prCompletion
    : (legacyRequestCopilotReview ? PR_COMPLETIONS.REVIEW_THEN_MERGE : PR_COMPLETIONS.MERGE_ON_GREEN);
  const runsReviewLoop = resolvedPrCompletion === PR_COMPLETIONS.REVIEW_THEN_MERGE;
  // Keep the pre-reviewer-chain API contract for direct callers: the legacy
  // flag explicitly requested Copilot, whereas an explicitly supplied empty
  // list means the caller opted into no reviewers. Production callers pass
  // the resolved list, so a fresh install remains reviewer-free by default.
  const reviewerList = reviewers === undefined
    ? (legacyRequestCopilotReview ? [DEFAULT_REVIEWER] : [...DEFAULT_REVIEWERS])
    : normalizeReviewers({ reviewers });
  await preRequestWorktreeReview(context, prResult, runsReviewLoop, reviewerList);

  // JIRA remains a legacy human hand-off: configured reviewers can still
  // run, but the follow-up must not merge. An explicit leave-open policy is
  // different — opening the PR is the entire requested outcome.
  const leaveOpen = leavesPrForHuman(originalTask);

  // Release the PR branch BEFORE anything is queued against it. A follow-up
  // spawned below attaches its OWN worktree to `worktreeBranch`, and the CoS
  // evaluation tick preps that task within a second or two — comfortably
  // inside the window this cleanup needs for its own teardown. Removing
  // afterwards lost that race (~0.7s in the reported incident): the
  // follow-up's `git worktree add` failed with "is already used by worktree
  // at …", the task was blocked, and the pull request it existed to land was
  // orphaned. Nothing below this point reads the worktree — the Copilot
  // pre-request above is the last user of that checkout.
  const result = await removeWorktree(agentId, sourceWorkspace, worktreeBranch, { merge: false, ...lockfileDeliverable(originalTask) }).catch(err => {
    emitLog('warn', `🌳 Worktree cleanup failed for ${agentId}: ${err.message}`, { agentId });
    return { cleanupIncomplete: true, warnings: [`Worktree cleanup failed: ${err.message}`] };
  });
  warnings.push(...(result?.warnings || []));

  // The PR itself is already open and stays reported as such; only work that
  // needs the branch FREE is gated on whether the release actually happened.
  // `cleanupIncomplete` means a removal was attempted and failed. A tree merely
  // preserved for uncommitted work (`removed:false` without it) is deliberately
  // not gated: the follow-up adopts that surviving holder rather than racing it
  // (agentWorkspacePrep's adoptWorktreeHoldingBranch), which is the data-safe path.
  await completeReleasedPullRequest(context, prResult, resolvedPrCompletion, reviewerList, leaveOpen, {
    branchHeld: !!result?.cleanupIncomplete,
  });
  return warnings;
}

async function preRequestWorktreeReview({ agentId, worktreePath, warnings }, prResult, runsReviewLoop, reviewerList) {
  const copilotIsFirst = reviewerList[0] === DEFAULT_REVIEWER;
  const nonCopilotReviewers = reviewerList.filter(r => r !== DEFAULT_REVIEWER);
  // Pre-request the native Copilot review ONLY when copilot LEADS the order — it
  // then reviews the freshly-opened PR. When copilot is configured after a CLI
  // reviewer (e.g. [codex, copilot]), pre-requesting now would make Copilot review
  // the stale pre-CLI-fix diff; instead the follow-up agent requests it at copilot's
  // turn, after the earlier reviewer's fixes are pushed. This pre-request is a
  // latency optimization only — the follow-up requests Copilot at its turn
  // regardless, so a failed/absent pre-request is recoverable (no reviewer dropped).
  if (runsReviewLoop && copilotIsFirst) {
    const reviewResult = await git.requestCopilotReview(worktreePath, prResult.url).catch(err => ({ success: false, error: err.message }));
    if (reviewResult.success && reviewResult.skipped) {
      emitLog('info', `🤖 Skipping Copilot pre-request for ${prResult.url} (non-GitHub forge)`, { agentId, prUrl: prResult.url });
    } else if (reviewResult.success) {
      emitLog('success', `🤖 Requested initial Copilot review on ${prResult.url}`, { agentId, prUrl: prResult.url });
    } else {
      emitLog('warn', `🤖 Copilot pre-request failed for ${prResult.url}: ${reviewResult.error} — follow-up will re-request at its turn`, { agentId, prUrl: prResult.url });
      warnings.push(`Copilot review request failed for ${prResult.url}: ${reviewResult.error}`);
    }
  }
  if (runsReviewLoop && nonCopilotReviewers.length > 0) {
    emitLog('info', `🤖 Follow-up will run CLI reviewers: ${nonCopilotReviewers.join(', ')}`, { agentId, prUrl: prResult.url });
  }
}

async function completeReleasedPullRequest(context, prResult, resolvedPrCompletion, reviewerList, leaveOpen, { branchHeld = false } = {}) {
  const { agentId } = context;
  const runsReviewLoop = resolvedPrCompletion === PR_COMPLETIONS.REVIEW_THEN_MERGE;
  if (resolvedPrCompletion === PR_COMPLETIONS.LEAVE_OPEN) {
    emitLog('info', `🤝 Leaving ${prResult.url} open by task completion policy`, { agentId, prUrl: prResult.url });
  } else if (leaveOpen && !runsReviewLoop) {
    emitLog('info', `🤝 Leaving ${prResult.url} open for a human — JIRA-tracked task, no reviewers configured`, { agentId, prUrl: prResult.url });
  } else {
    const queuedDeterministicMerge = await queueWorktreeMerge(context, prResult, resolvedPrCompletion);

    if (!queuedDeterministicMerge && branchHeld) {
      deferFollowUpWhileBranchHeld(context, prResult.url);
    } else if (!queuedDeterministicMerge) {
      await handoffFollowUpAfterRelease(context, prResult.url, {
        prCompletion: resolvedPrCompletion,
        reviewers: runsReviewLoop ? reviewerList : [],
        usernames: runsReviewLoop ? context.usernames : [],
        optionalReviewers: runsReviewLoop ? context.optionalReviewers : [],
        reviewerMaxRounds: runsReviewLoop ? context.reviewerMaxRounds : {},
      });
    }
  }
}

async function queueWorktreeMerge({ agentId, worktreeBranch, originalTask, description }, prResult, resolvedPrCompletion) {
  // A merge-only GitHub PR needs no model while CI is healthy. Hand it to
  // pr-watcher's deterministic tick instead; that tick merges green PRs
  // directly and recreates this exact follow-up only for a failed check or
  // conflict. Non-GitHub forges and unscoped tasks retain the legacy agent
  // path because pr-watcher intentionally speaks gh against managed apps.
  const canQueueDeterministicMerge = resolvedPrCompletion === PR_COMPLETIONS.MERGE_ON_GREEN
    && prResult.cli === 'gh'
    && !!originalTask?.metadata?.app;
  let queuedDeterministicMerge = false;
  if (canQueueDeterministicMerge) {
    const parsedPr = git.parsePullRequestUrl(prResult.url);
    try {
      const { queuePendingMerge } = await import('./prWatcher.js');
      queuedDeterministicMerge = await queuePendingMerge(originalTask.metadata.app, {
        prUrl: prResult.url,
        prNumber: parsedPr?.number,
        prBranch: worktreeBranch,
        sourceAgentId: agentId,
        sourceTask: {
          id: originalTask?.id || null,
          priority: originalTask?.priority || 'MEDIUM',
          description: originalTask?.description || description || 'CoS automated task',
          metadata: {
            app: originalTask.metadata.app,
            provider: originalTask.metadata.provider,
            providerId: originalTask.metadata.providerId,
            model: originalTask.metadata.model,
            effort: originalTask.metadata.effort,
          }
        }
      });
    } catch (err) {
      emitLog('warn', `🤖 Failed to queue deterministic merge for ${prResult.url}: ${err.message}`, { agentId, prUrl: prResult.url });
    }
    if (queuedDeterministicMerge) {
      emitLog('info', `🤖 Queued ${prResult.url} for deterministic merge on the next pr-watcher tick`, { agentId, prUrl: prResult.url });
    }
  }
  return queuedDeterministicMerge;
}

// A healthy handoff owns the branch until it merges (#12247); anything else
// open or unreadable is preserved for recovery.
const preservedPrState = (pr) => (pr?.mergeHandoffQueued === true ? 'pending-merge handoff'
  : pr?.autoMergeEnabled === true ? 'pending GitHub auto-merge' : 'unconfirmed PR recovery');

async function mergeOrPreserveWorktree({ agentId, sourceWorkspace, worktreeBranch, warnings, skipMerge, originalTask }, disposition) {
  // Default: auto-merge on success, just cleanup on failure.
  // Review-loop follow-up agents pass skipMerge: true because gh pr merge already
  // handled the merge upstream — re-merging the worktree branch into the local
  // source workspace would duplicate the squashed commits.
  const shouldMerge = disposition.merge;
  if (skipMerge) {
    const meta = originalTask?.metadata;
    const forkPrNumber = meta?.forkHead && (meta.reviewLoopPRNumber || meta.prRemediationNumber);
    const pr = await import('./prProbe.js').then(({ probePrForBranch, probeChangeRequestState }) =>
      meta?.forkHead
        ? probeChangeRequestState(sourceWorkspace, { number: forkPrNumber, branch: resolveTaskRemoteBranch(meta) })
        : probePrForBranch(sourceWorkspace, worktreeBranch)).catch(() => null);
    if (!pr?.readable || (pr.prState && pr.prState !== 'MERGED')) {
      // Failed/unreadable CI or unpublished commits need recovery, which needs this
      // branch. Only a healthy handoff suppresses the post-cleanup audit.
      emitLog('info', `🌳 Preserving ${preservedPrState(pr)} worktree for ${agentId}`, { agentId, branchName: worktreeBranch });
      return;
    }
  }
  emitLog('info', `🌳 Cleaning up worktree for agent ${agentId} (merge: ${shouldMerge})`, {
    agentId, branchName: worktreeBranch, merge: shouldMerge
  });

  // Cleanup retains branches without merge evidence, including failed runs and
  // successful runs whose PR could not be confirmed. Their retry can resume
  // from the preserved work through resolveResumeBranch below.
  const result = await removeWorktree(agentId, sourceWorkspace, worktreeBranch, {
    merge: shouldMerge,
    ...lockfileDeliverable(originalTask),
  }).catch(err => {
    emitLog('warn', `🌳 Worktree cleanup failed for ${agentId}: ${err.message}`, { agentId });
    return { cleanupIncomplete: true, warnings: [`Worktree cleanup failed: ${err.message}`] };
  });
  warnings.push(...(result?.warnings || []));

  // The branch just landed by local merge. If the agent pushed it anyway — an
  // older prompt said `/do:push` under this posture, and the repo's own
  // "commit and push" convention still reaches every agent — origin holds a
  // copy nothing will ever read, which the post-completion audit reports as a
  // leaked remote branch and hands to a recovery agent. Finish the job here,
  // deterministically, instead of paying a model to run one `git push --delete`.
  if (result?.merged) await deleteMergedRemoteCopy(agentId, sourceWorkspace, worktreeBranch);
  return result;
}

// A follow-up attaches its OWN worktree to the PR branch, which `git worktree
// add` refuses while the old checkout still holds it. When cleanup could not
// release the branch, dispatching now just blocks the task and orphans the PR it
// exists to land — so the dispatch is withheld and the state is reported as a
// retryable cleanup warning (the post-cleanup repo-state audit independently
// observes the surviving worktree and files the recovery that retries removal
// and drives the PR). The PR itself is untouched: it stays open/merged as it was.
function deferFollowUpWhileBranchHeld({ agentId, worktreeBranch, worktreePath, warnings }, prUrl) {
  // The failed removal that left the branch held reported itself; this line only records the deferral.
  emitLog('info', `🌳 Deferring follow-up for ${prUrl} — worktree ${agentId} still holds ${worktreeBranch}`, { agentId, prUrl, branchName: worktreeBranch });
  warnings.push(`PR follow-up for ${prUrl} deferred — worktree ${worktreePath || agentId} still holds branch ${worktreeBranch}; retry the worktree cleanup, then re-dispatch the follow-up`);
}

// Call only after removeWorktree settles: the follow-up attaches its own
// checkout to this branch. Both PR creation and failed-agent recovery use this
// one argument builder; their completion/reviewer compatibility defaults differ.
async function handoffFollowUpAfterRelease(context, prUrl, overrides, failureKind = 'created') {
  const { agentId, worktreeBranch, sourceWorkspace, warnings, originalTask,
    prCompletion, reviewers, usernames, optionalReviewers, reviewerMaxRounds,
    reviewStopMode, reviewerApplies, reviewerModels, reviewerEfforts } = context;
  await spawnReviewLoopFollowUp({
    originalAgentId: agentId, originalTask, prUrl, prBranch: worktreeBranch,
    sourceWorkspace, prCompletion, reviewers, usernames, optionalReviewers,
    reviewerMaxRounds, reviewStopMode, reviewerApplies, reviewerModels, reviewerEfforts,
    leaveOpen: leavesPrForHuman(originalTask),
    ...overrides,
  }).catch(err => {
    if (failureKind === 'orphaned') {
      emitLog('warn', `🌳 Failed to spawn a follow-up for orphaned ${prUrl}: ${err.message}`, { agentId });
      warnings.push(`Could not queue a follow-up for ${prUrl}: ${err.message}`);
    } else {
      emitLog('warn', `🤖 Failed to spawn PR follow-up for ${prUrl}: ${err.message}`, { agentId, prUrl });
      warnings.push(`PR follow-up spawn failed for ${prUrl}: ${err.message}`);
    }
  });
}

/**
 * Delete origin's copy of a worktree branch that cleanup just merged locally.
 *
 * Cheap on the common path, narrow on the rare one:
 *   - A push from the worktree updates the shared clone's remote-tracking ref,
 *     so `refs/remotes/origin/<branch>` answers "did this agent push?" with one
 *     local rev-parse and no network. Absent ⇒ nothing to do. (A push from some
 *     other clone is invisible here; the repo-state audit still reports it.)
 *   - Merge evidence uses `git.hasBranchMergeEvidence` — the predicate the branch-
 *     reconcile reaper and `removeWorktree` already use — so a copy the agent
 *     amended or rebased after pushing (patch-equivalent, not an ancestor) still
 *     counts as landed, and an unresolvable object fails closed.
 *   - The delete is lease-protected against the SHA this clone last pushed: one
 *     round trip that asserts and deletes atomically, refused as "stale info" if
 *     origin has since moved. Nothing is deleted on stale knowledge.
 * Never adds a warning: a warning is what spawns cleanup's own merge-recovery
 * task, and a copy that could not be deleted is exactly what the audit exists
 * to catch on its own.
 */
async function deleteMergedRemoteCopy(agentId, sourceWorkspace, branchName) {
  const remoteRef = `refs/heads/${branchName}`;
  const tracked = await execGit(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branchName}`], sourceWorkspace, { ignoreExitCode: true })
    .catch(() => null);
  const pushedSha = tracked?.exitCode === 0 ? tracked.stdout.trim() : '';
  if (!pushedSha) return;
  const hasMergeEvidence = await git.hasBranchMergeEvidence(sourceWorkspace, pushedSha, 'HEAD').catch(() => false);
  if (!hasMergeEvidence) {
    emitLog('warn', `🌳 origin/${branchName} (${pushedSha.slice(0, 7)}) has no established merge evidence in the checkout that received the branch — left in place for the repo-state audit`, { agentId, branchName });
    return;
  }
  const pushed = await execGit(['push', `--force-with-lease=${remoteRef}:${pushedSha}`, 'origin', `:${remoteRef}`], sourceWorkspace, { ignoreExitCode: true })
    .catch(err => ({ exitCode: 1, stderr: err.message }));
  if (pushed.exitCode === 0) {
    emitLog('info', `🌳 ${agentId} pushed ${branchName} but cleanup merged it locally — deleted the remote copy`, { agentId, branchName });
    return;
  }
  const why = String(pushed.stderr || '').trim().split('\n').pop() || `exit ${pushed.exitCode}`;
  emitLog('warn', `🌳 Could not delete origin/${branchName} after merging it locally (${why}) — left for the repo-state audit`, { agentId, branchName });
}

/**
 * What, if anything, should a retry of this task pick up from the run that just
 * died? Called after cleanup has decided what to preserve, so the answer reflects
 * what's actually on disk rather than what we hoped.
 *
 * Two shapes of leftover work, in priority order:
 *
 *   1. **Adopt the worktree** — `{ branchName, worktreePath }`. The dead agent's
 *      own worktree survived cleanup (a dirty tree aborts removal) and is still on
 *      its branch. This is the shape a server restart leaves behind: the run is
 *      killed mid-edit, so its work is UNCOMMITTED and no branch pointer can carry
 *      it. The retry moves that tree to its own directory (see `adoptWorktree`).
 *   2. **Attach the branch** — `{ branchName, worktreePath: null }`. The worktree
 *      is gone but the branch survived with unmerged commits, so a fresh worktree
 *      attaches to it via `createWorktree`'s `existingBranch` path.
 *
 * Returns null when there is nothing to resume — no branch, no leftover work, or
 * a branch whose commits already landed. A null answer means "start clean", the
 * correct behavior for an agent that died before producing anything.
 *
 * Deliberately checks the LOCAL branch: `removeWorktree` preserves it in place,
 * and `createWorktree`'s `existingBranch` path prefers a local copy before
 * falling back to `origin/<branch>`, so a local-only branch resumes fine.
 *
 * @param {string} sourceWorkspace - the parent git repository
 * @param {string} branchName - the dead agent's worktree branch
 * @param {string} [worktreePath] - the dead agent's worktree directory, the
 *   adoption candidate. Omit to consider only the branch-attach shape.
 * @returns {Promise<{branchName: string, worktreePath: string|null}|null>}
 */
export async function resolveResumePointer(sourceWorkspace, branchName, worktreePath = null, { preserveLockfiles = false } = {}) {
  if (!sourceWorkspace || !branchName) return null;

  const survivingTree = !!(worktreePath && existsSync(worktreePath));
  const target = await git.getDefaultBranch(sourceWorkspace).catch(() => null) || 'main';
  // Same predicate `removeWorktree` used to decide whether to KEEP this branch, so
  // the two can't disagree and orphan it. `hasBranchMergeEvidence` (not a rev-list
  // count) because a rebase/squash-merged branch has new SHAs and would otherwise
  // read as resumable — pointing a retry at already-landed work. Note the polarity
  // flips only for a rejected call: resume starts clean on rejection, while the
  // predicate's internal probe failures still return false. The existence checks
  // below keep that negative evidence result from reviving an absent branch.
  const hasMergeEvidence = await git.hasBranchMergeEvidence(sourceWorkspace, branchName, target).catch(() => true);
  // Nothing survived and nothing is unmerged — the common "run finished, branch
  // landed, tree already reaped" shape. Bail before spending any more git calls.
  if (hasMergeEvidence && !survivingTree) return null;

  // How many commits the branch holds that the default branch doesn't. Only ever
  // consulted on one of the two mutually exclusive paths below, so it costs a
  // single call per resolution.
  const commitsAhead = async () =>
    (await git.getBranchComparison(sourceWorkspace, target, branchName).catch(() => null))?.ahead || 0;

  // 1. Adopt the surviving tree — but only if it is actually on the branch we're
  //    resuming; a half-cleaned or repurposed directory must not be handed over.
  if (survivingTree && await git.getBranch(worktreePath).catch(() => null) === branchName) {
    if (!hasMergeEvidence) {
      emitLog('info', `🌳 Worktree ${worktreePath} survived on ${branchName} without established merge evidence — a retry can adopt it`, { branchName, worktreePath });
      return { branchName, worktreePath };
    }
    // A merged branch reads that way for two very different reasons. Commits that
    // already LANDED (ahead > 0) must never be resumed onto — that's the
    // agent-d2ae0352 incident. A branch that never committed at all (ahead === 0)
    // has nothing to duplicate, so an uncommitted tree on top of it is safe to
    // adopt — and that is exactly the restart case this function exists for:
    // killed mid-edit, zero commits, hours of uncommitted work.
    if (await commitsAhead() > 0) return null;
    // Same dirt classifier `removeWorktree` uses, so "worth preserving" and "worth
    // resuming" can't disagree: lockfile churn an agent never meant to commit is
    // not work, and a tree holding only that should start clean.
    const porcelain = await git.getStatusPorcelain(worktreePath).catch(() => '');
    if (!classifyWorktreeDirt(porcelain, { preserveLockfiles }).hasRealChanges) return null;
    emitLog('info', `🌳 Worktree ${worktreePath} survived on ${branchName} — a retry can adopt it and keep its uncommitted work`, { branchName, worktreePath });
    return { branchName, worktreePath };
  }

  if (hasMergeEvidence) return null;

  // 2. Attach a fresh worktree to the branch. Git allows a branch to be checked out
  //    in only ONE worktree, so if a worktree is STILL on this branch, `git worktree
  //    add <path> <branch>` fails with "already checked out" and the retry can't
  //    spawn at all — worse than restarting clean. The adoption path above already
  //    handled the dead agent's OWN worktree; anything else holding the branch is
  //    not ours to move.
  const claimed = await git.getWorktreeBranches(sourceWorkspace).catch(() => null);
  if (claimed?.has(branchName)) {
    emitLog('info', `🌳 Branch ${branchName} is still checked out in a preserved worktree — a retry can't attach to it, so it will start clean`, { branchName });
    return null;
  }
  // Confirm the branch actually exists and holds commits — `hasBranchMergeEvidence`
  // returns false for an absent branch, which would hand back a branch name no
  // worktree can attach to.
  return await commitsAhead() > 0 ? { branchName, worktreePath: null } : null;
}

/**
 * The task-metadata patch that points a retry of `task` at what the run that just
 * died left behind — or clears a spent pointer, or does nothing. Resolves only;
 * `recordTaskResumePointer` persists it, `handleOrphanedTask` folds it into its own
 * retry write. Three outcomes, and the difference between the last two matters:
 *   - a **set** patch — there is leftover work; point the retry at it
 *   - a **clear** patch — this task WAS resuming, we looked, and there is nothing
 *     left (the branch merged or vanished); drop the pointer so the next attempt
 *     doesn't attach to it
 *   - an **empty** patch — nothing to say; leave whatever the task already carries
 *
 * Every path that retires a dead run funnels through here so the "can this be
 * resumed?" question has one answer:
 *   - `handleAgentCompletion` (agentCompletionCleanup.js) — the agent failed and
 *     its completion hook ran normally.
 *   - `handleOrphanedTask` (agentManagement.js) — the agent's process vanished
 *     (server restart / crash), so no completion hook ever ran. That path is why
 *     this is shared: a restart-killed run was requeued with no pointer at all,
 *     and its replacement redid work that was already sitting on disk.
 *
 * @param {{task: object, agentId: string, agentMetadata: object}} params
 * @returns {Promise<object>} metadata patch to merge into an `updateTask` call
 */
/**
 * A claim-flow relaunch continues the `claim-*` worktree the paused run already
 * cut for its pinned target. Resolved before the CoS-worktree bail: claim agents
 * record `isWorktree: false` because PortOS did not provision the directory, and
 * that bail is what used to requeue the relaunch onto a clean checkout.
 *
 * Fails closed (null → the caller keeps the ordinary "start clean" answer) when
 * the agent list cannot be read. An empty list would look like "nobody is in
 * that tree."
 */
async function resolveClaimContinuationPatch({ task, agentId, agentMetadata }) {
  const source = agentMetadata?.sourceWorkspace || agentMetadata?.workspacePath;
  if (!source) return null;
  const agents = await getAgents().catch(() => null);
  if (!agents) return null;
  const worktrees = await listWorktrees(source).catch(() => []);
  const pointer = claimContinuationPointer({
    task, agentId, worktrees, agents, worktreesRoot: PATHS.worktrees, sourceWorkspace: source,
  });
  if (!pointer) return null;
  emitLog('info', `🔁 Task ${task.id} will resume in the claim worktree ${pointer.resumeWorktreePath} (${pointer.existingBranch}) instead of starting clean`, {
    taskId: task.id, agentId, branchName: pointer.existingBranch, worktreePath: pointer.resumeWorktreePath,
  });
  return pointer;
}

export async function resolveTaskResumePatch({ task, agentId, agentMetadata }) {
  if (!task?.id || !agentId) return {};
  if (isTruthyMeta(task.metadata?.discardWorktree)) return {};
  const claimContinuation = await resolveClaimContinuationPatch({ task, agentId, agentMetadata });
  if (claimContinuation) return claimContinuation;
  // Persistent feature-agent worktrees are never torn down, and throwaway
  // reasoning worktrees are deliberately discarded — neither leaves work to resume.
  // These runs are NOT evaluated at all, which is why they return the empty patch
  // rather than the clear: a task already resuming whose retry couldn't get a
  // worktree (see agentWorkspacePrep's degrade path) must KEEP its pointer, since
  // the tree it names is still sitting there for the attempt after this one.
  if (!agentMetadata?.isWorktree || agentMetadata?.isPersistentWorktree) return {};

  // The agent's own recorded path is authoritative; the `<worktrees>/<agentId>`
  // convention is the fallback for a record written before it was stamped (same
  // idiom cleanupAgentWorktree uses for the PR push).
  const worktreePath = agentMetadata.workspacePath || join(PATHS.worktrees, agentId);
  const pointer = await resolveResumePointer(agentMetadata.sourceWorkspace, agentMetadata.worktreeBranch, worktreePath, lockfileDeliverable(task))
    .catch(err => {
      emitLog('warn', `Failed to resolve resume pointer for ${agentId}: ${err.message}`, { agentId });
      return null;
    });

  if (pointer) {
    emitLog('info', `🔁 Task ${task.id} will resume ${pointer.worktreePath ? `in the worktree ${agentId} left behind` : `from ${pointer.branchName}`} instead of restarting`, {
      taskId: task.id, agentId, branchName: pointer.branchName, worktreePath: pointer.worktreePath
    });
  }
  return resumePointerMetadata(pointer, agentId, task);
}

/**
 * The task-metadata patch that makes a retry resume (or stop resuming).
 *
 * `existingBranch` is the retry-owned target that `agentWorkspacePrep` resolves
 * before attaching a worktree, and `resumeWorktreePath` is honored there too, so
 * resuming needs no new spawn plumbing. `resumedFromAgentId` records whose run is
 * being continued — it drives the prompt's resume banner and is the marker that
 * distinguishes a resume from a review-loop follow-up (see `isPrBranchWorktree`
 * in agentPromptBuilder.js).
 *
 * With no pointer, a previously-stamped resume is CLEARED: its branch may since
 * have been merged or deleted, and leaving the pointer would attach the next
 * attempt to landed work. Keyed on `resumedFromAgentId` so it only ever clears a
 * pointer this mechanism wrote. Review-loop follow-ups keep their canonical target
 * in `reviewLoopPRBranch`, so clearing a legacy duplicate cannot strand the PR.
 *
 * @param {{branchName: string, worktreePath: string|null}|null} pointer
 * @param {string} agentId - the run being resumed from
 * @param {object} task - the task being retried (read for a prior pointer)
 * @returns {object} metadata patch to merge into an `updateTask` call
 */
export function resumePointerMetadata(pointer, agentId, task) {
  if (pointer) {
    return {
      existingBranch: pointer.branchName,
      resumedFromAgentId: agentId,
      resumeWorktreePath: pointer.worktreePath
    };
  }
  if (!shouldStripTaskTargetBranch(task?.metadata)) return {};
  // `undefined`, not `null`: `updateTask` DELETES undefined keys from the merged
  // metadata, while a null survives the merge and TASKS.md serializes it as the
  // literal string `"null"` — which reads back as a truthy `existingBranch` and
  // sends the next attempt looking for a branch named "null". The keys are still
  // present on the returned patch, so callers can tell a clear from a no-op.
  return {
    existingBranch: undefined,
    resumedFromAgentId: undefined,
    resumeWorktreePath: undefined,
    claimResumeInPlace: undefined,
  };
}

/**
 * Resolve AND persist the resume patch. For callers that aren't already writing the
 * task; `handleOrphanedTask` folds the patch into its own retry write instead, so
 * the pointer can't land after the status flip that makes the task spawnable.
 *
 * @param {{task: object, agentId: string, agentMetadata: object}} params
 * @returns {Promise<object>} the patch that was written (empty when nothing was)
 */
export async function recordTaskResumePointer({ task, agentId, agentMetadata }) {
  const metadata = await resolveTaskResumePatch({ task, agentId, agentMetadata });
  if (Object.keys(metadata).length === 0) return metadata;

  await updateTask(task.id, { metadata }, task.taskType || 'user').catch(err => {
    emitLog('warn', `Failed to record resume pointer for task ${task.id}: ${err.message}`, { taskId: task.id, agentId });
  });
  if (!resolveTaskTargetBranch(metadata)) {
    emitLog('info', `🧹 Cleared spent resume pointer on task ${task.id} — nothing left to resume`, { taskId: task.id, agentId });
  }
  return metadata;
}

/**
 * The post-cleanup write that RELEASES a failed task's retry hold, shared by every
 * spawn mode (#3368, #3373).
 *
 * A failed agent whose branch — or whole worktree — survived cleanup leaves real
 * work behind (cleanup requires merge evidence; a dirty tree aborts removal
 * outright). Recording where it lives on the TASK is what makes its retry RESUME
 * rather than restart from scratch — the behavior the agent-d2ae0352 incident
 * exposed, where a run reaped 30s after its PR merged was re-dispatched to a fresh
 * agent that began the shipped work over.
 *
 * Call this AFTER `cleanupAgentWorktree` so it reflects what actually survived, and
 * from all three completion paths — the two in-process spawners (`spawnDirectly` in
 * agentCliSpawning.js and the TUI `finish()` in agentTuiSpawning.js, both through
 * `runSpawnerCompletionCleanup`) and `handleAgentCompletion`
 * (agentCompletionCleanup.js, runner mode). Only the runner path used to do it, so a
 * failed direct-CLI/TUI run left a branch full of commits nothing would ever point a
 * retry at.
 *
 * Only for a task that is actually going to RETRY. The failure verdict has already
 * been persisted by `finalizeAgent` at this point, and a retryable failure leaves
 * the task HELD — `in_progress` plus the retry-hold marker (#3373,
 * lib/taskRetryHold.js) — precisely so nothing can dequeue it during the cleanup
 * this call follows. Releasing the hold and writing the pointer is therefore ONE
 * `updateTask`: the task becomes spawnable and pointed in the same write, never
 * spawnable-then-pointed. A `blocked` task that exhausted its budget carries no
 * hold and gets no pointer — dead metadata `updateTask` would strip again on the
 * next terminal write, and that a later `reviveBlockedTask` would resurrect as a
 * live pointer to a branch nobody vetted.
 *
 * The no-hold fallback (a task we read as plain `pending`) still writes the pointer
 * alone: that is the pre-#3373 shape, and it is also what a task the orphan sweep
 * already recovered mid-cleanup looks like. Anything else we read — `blocked`,
 * `in_progress` under someone else's hold or none at all (the retry already
 * spawned), a failed read, a task deleted mid-run — is not evidence of a retry we
 * own, so we write nothing.
 *
 * `agentMetadata` is optional: pass it when the caller already holds the agent
 * record (the runner path does), omit it and this reads the record itself —
 * `getAgentRecord`, not `getAgent`, so it doesn't read and line-split the run's
 * whole output.txt for three metadata fields. `undefined` means "not supplied" —
 * a caller that genuinely has no metadata still gets the no-op it deserves, since
 * `resolveTaskResumePatch` bails on a non-worktree run.
 *
 * @param {{agentId: string, task: object, success: boolean, agentMetadata?: object}} params
 * @returns {Promise<object>} the metadata patch that was written (empty when nothing was)
 */
export async function releaseRetryHold({ agentId, task, success, agentMetadata }) {
  if (!agentId || !task?.id) return {};
  if (success && !isLegacyDeepAudit(task.metadata)) return {};

  const { getTaskById } = await import('./cosTaskStore.js');
  const { getAgentRecord } = await import('./cosAgentLifecycle.js');
  const persisted = await getTaskById(task.id).catch(err => {
    emitLog('warn', `Skipping resume pointer for task ${task.id} — status unreadable: ${err.message}`, { taskId: task.id, agentId });
    return null;
  });
  if (!persisted) return {};

  if (persisted.status === 'blocked' && ['task-approval', 'task-recovery-exhausted', 'runtime-verification'].includes(persisted.metadata?.blockedCategory)) {
    if (persisted.metadata.deliveryDecisionAgentId !== agentId) return {};
    const metadata = agentMetadata === undefined ? (await getAgentRecord(agentId))?.metadata : agentMetadata;
    const patch = persisted.metadata.blockedCategory === 'runtime-verification'
      ? await runtimeResumePatch({ task: persisted, agentId, agentMetadata: metadata })
      : await resolveTaskResumePatch({ task, agentId, agentMetadata: metadata });
    const result = await updateTask(task.id, { metadata: { ...patch,
      ...(persisted.metadata.blockedCategory === 'runtime-verification' ? { runtimeVerificationReadyAgentId: agentId } : {}) } }, task.taskType || persisted.taskType || 'user', {
      expectedStatus: 'blocked', expectedMetadata: { blockedCategory: persisted.metadata.blockedCategory, blockedAt: persisted.metadata.blockedAt, deliveryDecisionAgentId: agentId },
    });
    return result?.error || result?.statusChanged ? {} : patch;
  }

  if (isLegacyDeepAudit(task.metadata)) {
    if (persisted.status !== 'in_progress' || !isRetryHoldOwner(persisted.metadata, agentId)) return {};
    const metadata = agentMetadata === undefined
      ? (await getAgentRecord(agentId).catch(() => null))?.metadata : agentMetadata;
    const patch = await resolveTaskResumePatch({ task, agentId, agentMetadata: metadata });
    const result = await updateTask(task.id, { status: 'blocked', metadata: {
      ...patch, ...clearedRetryHoldMetadata(), blockedCategory: 'deep-audit-partial',
      blockedReason: 'Deep audit checkpoint; resume explicitly', blockedAt: new Date().toISOString(),
    } }, task.taskType || persisted.taskType || 'user', {
      expectedStatus: 'in_progress', expectedMetadata: { retryPendingCleanup: agentId },
    });
    return result?.error || result?.statusChanged ? {} : patch;
  }

  // Release only OUR hold, and only while the task is still held `in_progress`.
  // Both halves matter: a slow cleanup from a previous attempt must not clear the
  // hold the CURRENT attempt just armed (it would make the task spawnable while
  // that attempt's cleanup is still running — the very race this exists to close),
  // and a task that reached `blocked`/`completed` carrying a stale marker must
  // never be flipped back to `pending` by a late cleanup.
  const held = isRetryHoldOwner(persisted.metadata, agentId) && persisted.status === 'in_progress';
  // A record with no `status` at all is a legacy shape that predates the field;
  // those are pending.
  if (!held && (persisted.status ?? 'pending') !== 'pending') return {};

  const metadata = agentMetadata === undefined
    ? (await getAgentRecord(agentId).catch(() => null))?.metadata
    : agentMetadata;

  if (!held) return await recordTaskResumePointer({ task, agentId, agentMetadata: metadata });

  // Fails open to "start clean" for the same reason `handleOrphanedTask` does:
  // requeueing the task matters far more than resuming it, and a throw here would
  // leave it held until the orphan sweep.
  const patch = await resolveTaskResumePatch({ task, agentId, agentMetadata: metadata }).catch(err => {
    emitLog('warn', `Resume pointer for task ${task.id} could not be resolved: ${err.message}`, { taskId: task.id, agentId });
    return {};
  });
  const taskType = task.taskType || persisted.taskType || 'user';
  const result = await updateTask(task.id, {
    status: 'pending',
    metadata: { ...patch, ...clearedRetryHoldMetadata() }
  }, taskType, {
    expectedStatus: 'in_progress', expectedMetadata: { retryPendingCleanup: persisted.metadata.retryPendingCleanup },
  }).catch(err => {
    emitLog('warn', `Failed to release retry hold on task ${task.id}: ${err.message}`, { taskId: task.id, agentId });
    return { error: err.message };
  });
  if (result?.statusChanged) return {};
  if (result?.error) {
    // The hold is still on disk, so the orphan sweep finishes the transition —
    // the task is delayed, never stranded.
    emitLog('warn', `⏳ Task ${task.id} still held after a failed release — the orphan sweep will requeue it`, { taskId: task.id, agentId });
    return {};
  }
  const targetBranch = resolveTaskTargetBranch(patch);
  emitLog('info', targetBranch
    ? `🔁 Task ${task.id} requeued pointing at ${targetBranch}`
    : `🔓 Task ${task.id} requeued for retry`, { taskId: task.id, agentId, branchName: targetBranch });
  return patch;
}

/**
 * Spawn an internal follow-up task that drives the ordered multi-reviewer
 * review-and-fix loop on the just-created PR until the configured reviewer chain
 * is satisfied, then merges the PR. This is what makes the user-facing "review
 * loop" actually loop — the original agent only opens the PR (and at most
 * pre-requests Copilot when it leads) and exits; without this follow-up the loop
 * ends after one iteration and the PR is never merged.
 *
 * `reviewers` is the ordered list (e.g. `[codex, antigravity, copilot]`); the follow-up
 * runs each in order — invoking the CLI reviewers itself and requesting Copilot at
 * its turn — honoring `reviewStopMode` (`all`/`on-findings`/`on-clean`) and
 * `reviewerApplies`. Copilot is GitHub-only, so it is stripped here on non-GitHub
 * forges. `usernames` are arbitrary GitHub reviewer usernames the follow-up
 * requests as PR reviewers to gate the merge — forge-agnostic, so never stripped.
 *
 * `prCompletion` is resolved before this function is called. It selects review
 * then merge versus merge on green directly; `leave-open` is intentional and
 * returns without creating a follow-up.
 *
 * The follow-up task uses an isolated worktree attached to the existing PR branch
 * through its canonical `reviewLoopPRBranch`, so it can fix-and-push without
 * trampling concurrent agents. `forkHead` is where that branch lives when the PR
 * came from a FORK — such a head has no `origin/<branch>` for the attach to
 * resolve, so without it the follow-up is queued and then blocked at workspace
 * prep for exactly the PRs external contributors open (#6064). Persisted beside
 * the branch name and threaded back out by `agentWorkspacePrep`; a same-repo PR
 * passes null and nothing changes.
 *
 * `dispatch` decides WHO starts the task:
 *   `'queue'`     (default) — the autonomous lane. The task is persisted and the
 *                 ordinary `tasks:changed` dequeue picks it up, which is correct
 *                 for a follow-up spawned by cleanup/prWatcher: the run that
 *                 produced the PR was itself autonomous, so its continuation
 *                 belongs under the CoS auto-run gate and daily action budget.
 *   `'immediate'` — an explicit human action (the app PR page's "Resolve &
 *                 merge"). The dequeue's Priority-2 tier only spawns
 *                 auto-approved system tasks while CoS auto-run is in `execute`
 *                 and under budget, so a queued follow-up would sit `pending`
 *                 until the user pressed Run now on the task page — the whole
 *                 point of the button was not having to. This suppresses the
 *                 automatic dequeue and force-spawns the task instead (same path
 *                 as that Run now button), reporting the outcome as `dispatch`.
 *
 * `selfReview` says the follow-up agent is the reviewer: it EMPTIES the roster
 * (reviewers, usernames and the `~opt` set alike) and then marks the resulting
 * no-roster run as one that still owes the change a review. That distinction is
 * the whole point — an empty roster has always meant "nothing reviews this, just
 * land it on green CI", and that stays what it means without this flag.
 * Deliberately ignored on a `merge-on-green` run, where the caller asked for no
 * review at all rather than for an undelegated one.
 *
 * Returns the follow-up task, or — when an equivalent follow-up was already
 * queued — that existing task with `duplicate: true`. `dispatch: 'immediate'`
 * additionally stamps `dispatch: { started, reason }` so the caller can say
 * whether an agent actually started or the task is still waiting (no slots,
 * daemon stopped, …) rather than guessing.
 */
export async function spawnReviewLoopFollowUp({ originalAgentId, originalTask, prUrl, prBranch, forkHead = null, sourceWorkspace, prCompletion = PR_COMPLETIONS.REVIEW_THEN_MERGE, reviewers = DEFAULT_REVIEWERS, usernames = [], optionalReviewers = [], reviewerMaxRounds = {}, reviewStopMode = DEFAULT_REVIEW_STOP_MODE, reviewerApplies = false, reviewerModels = null, reviewerEfforts = null, leaveOpen = false, selfReview = false, dispatch = 'queue', reviewTarget = null, mergeGuardTarget = null }) {
  if (!prUrl || !prBranch) return null;
  if (prCompletion === PR_COMPLETIONS.LEAVE_OPEN) return null;

  if (mergeGuardTarget) {
    const { validatePendingMergeRecovery } = await import('./pendingMergeRecovery.js');
    if (mergeGuardTarget.prUrl !== prUrl || mergeGuardTarget.branch !== prBranch
      || mergeGuardTarget.sourceTaskId !== originalTask?.id || mergeGuardTarget.sourceAgentId !== originalAgentId) return { blocked: 'Merge recovery identity changed' };
    const refused = await validatePendingMergeRecovery({ target: mergeGuardTarget, workspacePath: sourceWorkspace });
    if (refused) return { blocked: refused };
  }

  if (reviewTarget) {
    const { validateCleanupReviewTarget } = await import('./cosMergeHandoff.js');
    if (reviewTarget.prUrl !== prUrl || reviewTarget.branch !== prBranch
      || reviewTarget.ownerTaskId !== originalTask?.id || reviewTarget.ownerId !== originalAgentId) return { blocked: 'Review recovery identity changed' };
    const refused = await validateCleanupReviewTarget({ target: reviewTarget, workspacePath: sourceWorkspace });
    if (refused) return { blocked: refused };
  }

  // Recovery belongs to the same durable task. A fresh sys-rl task resets the
  // spawn budget on every CI/conflict handoff and recursively nests its title.
  // The id hint also recovers receipts written before the marker was retained.
  if (isTruthyMeta(originalTask?.metadata?.reviewLoopFollowUp) || originalTask?.id?.startsWith('sys-rl-')) {
    return resumeReviewLoopCoordinator(originalTask.id, prUrl, prBranch, reviewTarget, mergeGuardTarget);
  }

  const parsedPr = git.parsePullRequestUrl(prUrl);
  // Copilot is GitHub-only; CLI-based reviewers (claude/antigravity/codex/grok) work on any
  // forge because the agent invokes the CLI directly. On a GitLab forge, drop
  // copilot from the list. Classify with the shared detector rather than
  // `host !== 'github.com'` — a GitHub Enterprise host still has Copilot, and
  // misreading it as non-GitHub would strip the only reviewer and silently
  // downgrade the run to merge-only.
  const isNonGithubForge = !!parsedPr?.host && detectForgeCli(parsedPr.host) !== 'gh';
  // Self-review empties the roster HERE rather than at each caller. "The agent
  // reviews it itself" and "these reviewers review it" are mutually exclusive, so
  // whoever holds the flag has to hold the emptying too — and the non-obvious
  // half is the usernames: a single `@login` inherited from the Code Review
  // Defaults keeps the roster non-empty and quietly puts the run back on the
  // delegated path the caller opted out of. One owner, so a second caller adopting
  // the mode cannot rediscover that the hard way.
  //
  // An EXPLICITLY empty list means "no review was requested" and must stay empty —
  // normalizeReviewers' `[copilot]` default would otherwise resurrect a reviewer.
  const reviewerList = (selfReview || (Array.isArray(reviewers) && reviewers.length === 0))
    ? []
    : normalizeReviewers({ reviewers });
  const effectiveReviewers = prioritizeToolFreeReviewers(
    isNonGithubForge ? reviewerList.filter(r => r !== DEFAULT_REVIEWER) : reviewerList
  );
  // GitHub reviewer usernames are forge-agnostic requested reviewers, so they are
  // NOT stripped on a non-GitHub forge — a username reviewer alone can drive the
  // loop even when copilot was dropped.
  let effectiveUsernames = selfReview ? [] : normalizeReviewUsernames(usernames);
  // Non-blocking (`~opt`) marker set — forge-agnostic, threaded verbatim so the
  // follow-up's `--review-with` marks the same reviewers optional.
  let effectiveOptionalReviewers = selfReview ? [] : (normalizeOptionalReviewers(optionalReviewers) || []);
  // Target-forge identity preflight (#13115). A handle the forge verifiably does
  // not have would fail every PR-side request. A REQUIRED one fails closed (the
  // run must not merge without the review the operator demanded); an OPTIONAL one
  // is left out of this run's emitted roster and recorded, never reported clean.
  // Lookups that merely fail (auth/transport) are inconclusive and change nothing.
  // The saved roster is never rewritten.
  let reviewerIdentityFaults = [];
  if (effectiveUsernames.length || effectiveOptionalReviewers.length) {
    const { preflightReviewerIdentities } = await import('./reviewerIdentity.js');
    const preflight = await preflightReviewerIdentities({
      usernames: effectiveUsernames,
      optionalReviewers: effectiveOptionalReviewers,
      forge: isNonGithubForge ? 'gitlab' : 'github',
      host: parsedPr?.host,
    });
    if (preflight.requiredMissing.length) {
      const detail = preflight.requiredMissing.map((e) => `@${e.token}: ${e.reason}`).join('; ');
      throw new ServerError(`Required reviewer not found on the target forge — ${detail}. Fix it in Settings → Code Reviewers.`, {
        status: 409, code: 'REVIEWER_IDENTITY_NOT_FOUND', context: { reviewers: preflight.requiredMissing.map((e) => e.token) },
      });
    }
    if (preflight.optionalMissing.length) {
      const dropped = new Set(preflight.optionalMissing.map((e) => e.token.toLowerCase()));
      reviewerIdentityFaults = preflight.optionalMissing.map(({ token, reason }) => ({ token, reason }));
      effectiveUsernames = effectiveUsernames.filter((u) => !dropped.has(u.toLowerCase()));
      effectiveOptionalReviewers = effectiveOptionalReviewers.filter((r) => !dropped.has(r.replace(/^@/, '').toLowerCase()));
      console.log(`🚫 Optional reviewer(s) not found on the target forge, skipped for this run: ${reviewerIdentityFaults.map((f) => `@${f.token}`).join(', ')}`);
    }
  }
  // Per-reviewer iteration caps (`~max=<n>`) — forge-agnostic, threaded verbatim
  // so the follow-up's `--review-with` carries the same budgets. Entries for
  // reviewers that were stripped are inert (the emitter only marks tokens it
  // actually emits), so no narrowing is needed here.
  const effectiveReviewerMaxRounds = normalizeReviewerMaxRounds(reviewerMaxRounds) || {};
  // A review WAS asked for, but nothing is left to perform it — a legacy review
  // loop whose GitHub-only reviewer vanished on another forge (which retains its
  // prior merge-only fallback rather than leaving an orphaned PR), or a caller
  // that deliberately resolved no roster. Named rather than inlined into
  // `mergeOnly`, because the self-review branch below is exactly this case and
  // re-deriving it by conjunction reads as a condition that might contradict it.
  const noRosterMerge = prCompletion === PR_COMPLETIONS.REVIEW_THEN_MERGE
    && effectiveReviewers.length === 0 && effectiveUsernames.length === 0;
  // Merge-on-green deliberately skips every reviewer.
  const mergeOnly = prCompletion === PR_COMPLETIONS.MERGE_ON_GREEN || noRosterMerge;
  // The follow-up reviews the change ITSELF before the CI gate. Only meaningful
  // on the no-roster path — with reviewers configured the review loop already
  // runs — and never on a `merge-on-green` run, where the caller asked for no
  // review at all rather than for an undelegated one.
  const selfReviewMerge = selfReview && noRosterMerge;
  // ...and with nothing to review AND nothing to merge there is no follow-up at
  // all (a JIRA-tracked task whose reviewers were all stripped). The caller
  // normally catches this; the guard keeps the invariant local to this function.
  if (mergeOnly && leaveOpen) return null;

  // Reviewer-keyed model map, narrowed to the model-selectable reviewers actually
  // in this loop's list (e.g. `{ codex: 'gpt-5.6-sol', ollama: 'qwen2.5:7b' }`).
  // The prompt threads a CLI reviewer's model as `<reviewer> --model <id>` and a
  // local-LLM reviewer's as the `model` field of its `/api/code-review/local` body.
  // `reviewerModels` is already coerced to string values upstream
  // (resolveReviewLoopOptions).
  // Empty → null so the prompt builder's "nothing configured" path is unambiguous.
  const narrowPins = (pins, roster) => {
    const out = Object.fromEntries(effectiveReviewers
      .filter(r => (roster.includes(r) || isProviderReviewer(r)) && pins?.[r])
      .map(r => [r, pins[r]]));
    return Object.keys(out).length ? out : null;
  };
  const narrowedReviewerModels = narrowPins(reviewerModels, MODEL_SELECTABLE_REVIEWERS);
  // Reviewer-keyed reasoning-effort map, narrowed the same way. The prompt turns a
  // CLI reviewer's effort into a flag on its command line (`--effort high` /
  // `-c model_reasoning_effort=high`, or a folded `--model gpt-5[effort=max]` for
  // cursor, whose CLI has no effort flag) and a local-LLM reviewer's into the
  // `reasoning_effort` field of its `/api/code-review/local` body.
  const narrowedReviewerEfforts = narrowPins(reviewerEfforts, EFFORT_SELECTABLE_REVIEWERS);

  // One place that names the mode, so the title, the log line, and the warning
  // can't drift apart as the two follow-up kinds evolve.
  const kind = mergeOnly
    ? (selfReviewMerge
      ? { title: 'Self-Review & Merge', label: 'self-review-merge', reviewers: 'self-review, no delegated reviewer' }
      : { title: 'Merge', label: 'merge', reviewers: 'merge on green CI, no review' })
    : { title: 'Review Loop', label: 'review-loop', reviewers: [...effectiveReviewers, ...effectiveUsernames.map(u => `@${u}`)].join(', ') };

  // Inherit the source task's provider/model/effort pins. A follow-up runs a
  // coding harness (it fixes checks, resolves conflicts, drives reviewer CLIs),
  // so an install whose ACTIVE provider is api-only would permanently reject an
  // unpinned follow-up for lacking a harness — and the PR it was spawned to land
  // would sit open forever. Only copy what's actually pinned; an unpinned source
  // task still resolves through the normal active-provider path.
  //
  // The model pin rides ONLY with its provider: a bare `model` would be treated as
  // explicit against whatever provider resolution later picks, handing e.g. a
  // Claude model id to Codex. Effort is provider-agnostic, so it travels alone.
  const sourceMeta = originalTask?.metadata || {};
  const pinnedProvider = sourceMeta.provider || sourceMeta.providerId || null;
  const providerPins = {};
  if (pinnedProvider) {
    providerPins.provider = pinnedProvider;
    providerPins.providerId = pinnedProvider;
    if (sourceMeta.model) providerPins.model = sourceMeta.model;
  }
  if (sourceMeta.effort) providerPins.effort = sourceMeta.effort;

  // Routing key, and the one field here that turns a serialization slip into a
  // dead PR: a follow-up whose `app` doesn't resolve is BLOCKED by
  // prepareAgentWorkspace before it starts, so the PR it exists to land sits
  // open forever. Left undefined (not `null`) for a PortOS-local task —
  // generateTasksMarkdown drops nullish metadata, so the key never reaches the
  // task file to be re-read as an app literally named "null".
  const appId = originalTask?.metadata?.app;
  const sourceTaskDesc = originalTask?.description || 'CoS automated task';
  const firstLine = sourceTaskDesc.split(/[\r\n]/).find(l => l.trim()) || sourceTaskDesc;
  const followUpTitle = `[${kind.title}] ${firstLine.trim().substring(0, 80)} (${prUrl})`;

  const reviewLoopForkTarget = forkHead && !leaveOpen
    ? await (await import('./forkReviewMergeTarget.js')).captureForkReviewMergeTarget({ prUrl, prBranch, forkHead, sourceWorkspace })
    : null;

  const followUpTaskId = `sys-rl-${Date.now().toString(36)}`;
  const followUpTask = {
    id: followUpTaskId,
    status: 'pending',
    priority: (originalTask?.priority || 'MEDIUM').toUpperCase(),
    priorityValue: 2,
    description: followUpTitle,
    metadata: {
      app: appId,
      ...providerPins,
      // useWorktree is required so the follow-up runs in isolation. Its canonical
      // reviewLoopPRBranch below tells the shared resolver which PR branch to attach.
      useWorktree: true,
      // openPR/reviewLoop must stay false so cleanup doesn't try to create another PR
      // or request another initial review (the agent itself drives the loop)
      openPR: false,
      reviewLoop: false,
      simplify: false,
      // Marker flags consumed by the agent prompt + completion handler
      reviewLoopFollowUp: true,
      ...(mergeGuardTarget ? { pendingMergeGuardTarget: mergeGuardTarget } : {}),
      ...(reviewTarget ? { cleanupReviewTarget: reviewTarget, resumeWorktreePath: reviewTarget.worktreePath } : {}),
      prCompletion,
      // Merge-only run: no reviewers, the prompt is a CI-gate-and-merge procedure.
      reviewLoopMergeOnly: mergeOnly,
      // …and, on that same path, whether the agent owes the change its OWN
      // review first. Read by `buildMergeFollowUpSection`, which is why it sits
      // beside the flag that selects that section rather than in the roster keys
      // below — there is no roster in this mode.
      reviewLoopSelfReview: selfReviewMerge,
      // Review, but do NOT merge — the PR is a human's to land (JIRA hand-off).
      reviewLoopLeaveOpen: leaveOpen,
      reviewLoopPRUrl: prUrl,
      reviewLoopPRBranch: prBranch,
      // Fork coordinates for that branch, or null for a same-repo head. The
      // shared reader is `resolveTaskForkHead`, so this key is the generic
      // `forkHead` rather than a review-loop-specific one.
      forkHead: normalizeForkHead(forkHead),
      reviewLoopForkTarget,
      reviewLoopPRNumber: parsedPr?.number ?? null,
      reviewLoopPRHost: parsedPr?.host ?? null,
      reviewLoopPROwner: parsedPr?.owner ?? null,
      reviewLoopPRRepo: parsedPr?.repo ?? null,
      reviewLoopReviewers: effectiveReviewers,
      // Arbitrary GitHub reviewer usernames the follow-up requests as PR reviewers
      // and gates the merge on (appended to `--review-with` as `@user`).
      reviewLoopReviewerUsernames: effectiveUsernames,
      reviewLoopOptionalReviewers: effectiveOptionalReviewers,
      ...(reviewerIdentityFaults.length ? { reviewLoopReviewerIdentityFaults: reviewerIdentityFaults } : {}),
      // Per-reviewer `~max=<n>` caps, keyed by emitted token. Empty object = no
      // caps (leaves slashdo's per-loop built-in default in place); an absent key
      // is NOT `0`, which slashdo reads as "loop until clean".
      reviewLoopReviewerMaxRounds: effectiveReviewerMaxRounds,
      reviewLoopStopMode: reviewStopMode,
      // Public PR/MR diffs are untrusted input. Review subprocesses stay
      // advisory/read-only; the follow-up agent independently applies fixes.
      reviewLoopReviewerApplies: false,
      reviewLoopReviewerModels: narrowedReviewerModels,
      reviewLoopReviewerEfforts: narrowedReviewerEfforts,
      // Back-compat: older installs' prompt builder reads only the codex-scalar key.
      // Mirror the (already-narrowed) codex entry so a follow-up task persisted by this
      // version still threads a codex model after a downgrade. Remove once no supported
      // peer reads it.
      reviewLoopCodexModel: narrowedReviewerModels?.codex || null,
      sourceTaskId: originalTask?.id || null,
      sourceAgentId: originalAgentId || null,
      // This follow-up may legitimately exit with zero new commits when every
      // reviewer comes back clean — completion handling must not treat a
      // zero-commit exit as a failure.
      readOnly: false
    },
    autoApproved: true,
    section: 'pending'
  };

  // An immediate dispatch owns the spawn, so the automatic dequeue is suppressed:
  // otherwise it races this force-spawn for the same task and whichever loses
  // reports a bogus failure for a run that did start (see the `suppressDequeue`
  // contract on cos.js's `tasks:changed` listener).
  const immediate = dispatch === 'immediate';
  const persisted = await addTask(followUpTask, 'internal', { raw: true, suppressDequeue: immediate });

  if (mergeGuardTarget) {
    const { getTaskById } = await import('./cosTaskStore.js');
    const saved = persisted?.id && await getTaskById(persisted.id).catch(() => null);
    if (!saved || !['pending', 'in_progress'].includes(saved.status)
      || !isDeepStrictEqual(saved.metadata?.pendingMergeGuardTarget ?? saved.metadata?.pendingMergeGuardLaunchEvidence, mergeGuardTarget)) return { deferred: true };
  }

  // A duplicate rejection persisted NOTHING under `followUpTaskId` — an equivalent
  // follow-up is already queued under a different id. Return THAT record so a
  // caller reports (and force-spawns) the task that actually exists instead of the
  // id we just minted, which `forceSpawnTask` would answer with "Task not found".
  if (persisted?.duplicate) {
    emitLog('info', `🔁 ${kind.label} follow-up for PR ${prUrl} matched already-queued task ${persisted.id}`, {
      taskId: persisted.id, prUrl, prBranch, sourceAgentId: originalAgentId, sourceTaskId: originalTask?.id
    });
    return persisted;
  }

  emitLog('info', `🔁 Spawned ${kind.label} follow-up task ${followUpTaskId} (${kind.reviewers}) for PR ${prUrl}`, {
    taskId: followUpTaskId, prUrl, prBranch, sourceAgentId: originalAgentId, sourceTaskId: originalTask?.id
  });
  if (!immediate) return followUpTask;

  // A throw here would 500 an explicit user request whose task IS already
  // persisted — report it the same way a refusal is reported instead.
  const spawn = await forceSpawnTask(followUpTaskId).catch(err => ({ error: err.message }));
  if (spawn?.error) {
    // The task stays `pending` and keeps its place in the queue — say why it has
    // not started rather than letting the caller claim an agent is running.
    emitLog('warn', `⏳ ${kind.label} follow-up ${followUpTaskId} queued but not started — ${spawn.error}`, {
      taskId: followUpTaskId, prUrl
    });
    return { ...followUpTask, dispatch: { started: false, reason: spawn.error } };
  }
  emitLog('info', `⚡ Started ${kind.label} follow-up ${followUpTaskId} immediately for PR ${prUrl}`, {
    taskId: followUpTaskId, prUrl
  });
  return { ...followUpTask, dispatch: { started: true, reason: null } };
}

async function resumeReviewLoopCoordinator(taskId, prUrl, prBranch, reviewTarget = null, mergeGuardTarget = null) {
  const { getTaskById } = await import('./cosTaskStore.js');
  const task = await getTaskById(taskId);
  if (!task || task.taskType !== 'internal' || !isTruthyMeta(task.metadata?.reviewLoopFollowUp)
    || task.metadata.reviewLoopPRUrl !== prUrl || task.metadata.reviewLoopPRBranch !== prBranch) {
    return { id: taskId, blocked: 'Review coordinator identity could not be verified' };
  }
  if (leavesPrForHuman(task) || resolvePrCompletion(task.metadata) === PR_COMPLETIONS.LEAVE_OPEN
    || isTruthyMeta(task.metadata.readOnly) || isTruthyMeta(task.metadata.reviewLoopLeaveOpen)) {
    return { id: taskId, blocked: 'Review coordinator leaves this PR for its human owner' };
  }
  // Finalization can mark the task complete before its worker finishes cleanup.
  // Keep the receipt until that owner releases, including across daemon restarts.
  const { readClaimOwnershipAgents } = await import('./cosClaimOwnership.js');
  const agents = await readClaimOwnershipAgents();
  if (!agents) return { id: taskId, deferred: true };
  if (task.status === 'in_progress' || agents.some(agent => (agent.taskId === taskId
    || agent.metadata?.reviewLoopMergeTarget?.url === prUrl)
    && ['running', 'paused', 'orphaned', 'interrupted'].includes(agent.status))) {
    return { id: taskId, deferred: true };
  }
  if (task.status === 'pending') return { id: taskId, duplicate: true };
  if (task.status !== 'completed') return { id: taskId, blocked: `Review coordinator is ${task.status}` };
  const { MAX_TOTAL_SPAWNS } = await import('../lib/cosValidation.js');
  const count = Number(task.metadata.totalSpawnCount);
  if (!Number.isInteger(count) || count < 1 || count >= MAX_TOTAL_SPAWNS) {
    return { id: taskId, blocked: 'Review coordinator retry budget exhausted or unreadable' };
  }
  const result = await updateTask(taskId, {
    status: 'pending',
    metadata: { reviewLoopRecoveryReason: 'The handed-off PR needs fresh validation, review or conflict resolution',
      ...(mergeGuardTarget ? { pendingMergeGuardTarget: mergeGuardTarget } : {}),
      ...(reviewTarget ? { cleanupReviewTarget: reviewTarget, resumeWorktreePath: reviewTarget.worktreePath } : {}) },
  }, 'internal', {
    expectedStatus: 'completed',
    expectedMetadata: Object.fromEntries([
      'totalSpawnCount', 'reviewLoopFollowUp', 'reviewLoopPRUrl', 'reviewLoopPRBranch',
      'prCompletion', 'reviewLoopLeaveOpen', 'readOnly', 'jiraTicketId', 'analysisType', 'updatedAt',
    ].map(key => [key, task.metadata[key]])),
  });
  if (result?.error) throw new Error(result.error);
  if (result?.statusChanged) return { id: taskId, deferred: true };
  emitLog('info', `🔁 Resumed review coordinator ${taskId} for PR ${prUrl} (${count}/${MAX_TOTAL_SPAWNS} runs used)`, { taskId, prUrl });
  return { id: taskId, resumed: true };
}

/** Retain warning recovery on the original completion receipt. No new agent,
 * retry budget or personal obligation is created by a cleanup warning. */
export async function spawnMergeRecoveryTask(cleanupWarnings, agentId, task, appName, sourceWorkspace) {
  if (!cleanupWarnings?.length || !agentId || !sourceWorkspace) return null;
  // Draft/review-only delivery remains with its explicit owner. A warning
  // cannot grant the completion sweep authority to retire that checkout.
  if (resolvePrCompletion(task?.metadata) === PR_COMPLETIONS.LEAVE_OPEN) return null;
  const { getAgentRecord, recordCleanupOutcome, recordRepoStateVerification } = await import('./cosAgentLifecycle.js');
  const agent = await getAgentRecord(agentId);
  const branch = agent?.metadata?.worktreeBranch || agent?.metadata?.claimBranch
    || cleanupWarnings.map(warning => warning.match(/(?:Auto-merge failed|PR creation failed) for branch (\S+?)(?=:|\s|$)/)?.[1]).find(Boolean);
  if (branch) {
    const recorded = await recordCleanupOutcome(agentId, { status: 'pending', reason: 'cleanup-warning-pending', branch,
      path: agent?.metadata?.worktreePath || null, warnings: cleanupWarnings, sourceWorkspace, taskId: task?.id || null });
    if (!recorded) throw new Error('cleanup-warning-receipt-unavailable');
  }
  const pending = await recordRepoStateVerification(agentId, { status: 'pending', reasons: ['cleanup-warning-pending'] });
  if (!pending) throw new Error('cleanup-warning-replay-unavailable');
  emitLog('info', 'Cleanup warning retained for deterministic completion recovery', { agentId, appName });
  return null;
}

// A verification continuation deliberately retains even an already-merged
// branch. Ordinary failed-task retry correctly discards those resume pointers.
async function runtimeResumePatch({ task, agentId, agentMetadata }) {
  const claim = await resolveClaimContinuationPatch({ task, agentId, agentMetadata });
  if (claim) return claim;
  if (hasClaimFlowContract(task)) throw new Error('Runtime verification claim checkout identity is unavailable; retain the prerequisite');
  if (!agentMetadata?.isWorktree || agentMetadata.isPersistentWorktree) return {};
  const branch = agentMetadata.worktreeBranch;
  const path = agentMetadata.workspacePath || join(PATHS.worktrees, agentId);
  if (!branch || !existsSync(path) || await git.getBranch(path) !== branch) {
    throw new Error('Runtime verification checkout identity is unavailable; retain the prerequisite');
  }
  return { existingBranch: branch, resumeWorktreePath: path, resumedFromAgentId: agentId };
}