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

43.1 KB
Raw Blame
/**
 * Primary-checkout branch-jack detector (#3680).
 *
 * A CoS agent spawned with a worktree must only ever write inside that
 * worktree. On 2026-08-09 one didn't: running `/do:pr` from its worktree it
 * applied its three commits onto the PRIMARY checkout's local `main`, where
 * they sat unpushed and unreviewed. `main` is unprotected on this repo, so a
 * later `git push` from the primary would have landed them without a PR.
 *
 * The chosen remedy is DETECT-AND-REPORT, not prevention and not auto-repair:
 *
 *   - Prevention (making the primary read-only for the duration of a run) would
 *     break the many legitimate flows that read and write the primary checkout.
 *   - Auto-repair means `git reset --hard`, which DISCARDS commits. That stays a
 *     human decision, so the failure message states the recovery command instead
 *     of running it — and notes that the same work also exists on the agent's
 *     own branch, which is what makes the reset safe.
 *
 * Movement alone is NOT the signal. The primary checkout legitimately moves
 * during a run — a `git pull` on `main`, another PortOS flow fast-forwarding it
 * to commits that already merged upstream. Reporting those as branch-jacks fired
 * a false failure whose recovery prose ("commits PortOS never reviewed", `reset
 * --hard origin/main`) was actively wrong: the commits WERE `origin/main`. So the
 * guard reports only what a branch-jack actually leaves behind — commits the
 * branch's upstream does not have, or the checkout parked on a different branch.
 * A branch with no upstream to compare against falls back to the remote's default
 * branch, and a checkout with no remote at all can't be cleared, so it still
 * reports (an unpushed commit is unreviewed by definition). See #4717 below.
 *
 * "The upstream does not have it" is a question about CONTENT, not SHAs (#3744).
 * This repo rebase-merges PRs, so a commit that merged upstream carries a
 * DIFFERENT sha there than the copy a local `git merge --ff-only <branch>` put on
 * the primary. Comparing shas alone reads that copy as unpushed, and the
 * patch-id attribution below then blames whichever agent's branch also carries
 * the same upstream commit — which, after a `/do:pr` rebase, is most of them.
 * That is how a run whose PR had already MERGED was failed for branch-jacking a
 * commit it did not author and that was never stranded. So the upstream
 * exclusion asks `git cherry`, matching the patch-id precision already used on
 * the attribution side; the two must agree, or the mismatch itself manufactures
 * failures.
 *
 * They did not agree, and it did (#4098). Attribution asked its patch-id question
 * over the whole `upstream..head` window instead of over the stranded set the
 * exclusion had just computed. Once an agent's PR MERGES, its branch is an ancestor
 * of the upstream, so `git cherry <agentBranch> …` marks every commit whose patch is
 * anywhere in upstream history — including the primary's own local copies of merged
 * work, which the exclusion had already cleared. A human's unpushed WIP branch was
 * failed as a branch-jack on two such commits, with recovery prose pointing at an
 * `origin/<branch>` that does not exist (the branch tracked `origin/main`), while the
 * accurate reset would have discarded 41 of the human's commits. Attribution now
 * intersects with the stranded set, which is also what makes the patch test sound
 * without a freshness filter: a stranded commit has no patch-equivalent upstream, so
 * a patch-equivalent on the agent's branch can only be the agent's own commit.
 *
 * Movement that survives the checks above is still not enough to FAIL the run.
 * The primary checkout is a shared global resource — a concurrent coding-on-main
 * agent, the human's own terminal, `update.sh`'s `git pull --rebase --autostash`,
 * or any background flow can strand commits on it — so before blaming the run,
 * the guard asks whether THIS agent could have produced them (#3703). When a run
 * strands commits, they are attributed to the agent's own worktree branch by
 * PATCH-ID (`git cherry`, not raw SHA, so a cherry-picked or rebased copy still
 * matches). Stranded commits the agent demonstrably did not author — a read-only
 * reasoner that never branched, commits with no patch-equivalent on the agent's
 * branch, or commits the agent merely REBASED ONTO (#3725: `/do:pr` rebases on
 * `main` before pushing, so any run that outlives a concurrent commit to `main`
 * inherits it into its branch's base) — are carried as `{ drifted: false, unattributed: true }`:
 * warn-logged (unreviewed commits on `main` are worth surfacing) but not failed.
 * The asymmetry is deliberate — a missed branch-jack still leaves a warn log and
 * recoverable commits, while a false failure escalates to a human and dents the
 * task type's success rate.
 *
 * A checkout left on the WRONG BRANCH with nothing local-only strands no commit to
 * attribute, and for a long time that exempted it from the gate entirely: it failed
 * the run outright, because there was supposedly "nothing to blame on anyone"
 * (#4231). That inverted the gate — the shape carrying the LEAST evidence of a
 * branch-jack was the only one never asked to prove authorship. The primary is
 * shared, and a human running `git checkout -b my-feature` in it is ordinary work,
 * so it failed every agent alive at that moment, with prose that contradicted
 * itself: "No commits were stranded" as the recovery for "A worktree agent
 * committed to the primary". With nothing stranded the only signal left is
 * WHICH branch it landed on, so the agent's OWN worktree branch still fails (a
 * shape only the agent produces) and every other branch is `unattributed` —
 * worth surfacing, since the next spawn baselines against it, but not a failure.
 *
 * All of the above rests on there BEING an upstream to compare against, and the
 * no-upstream fallback quietly kept the pre-#4098 behavior (#4717). A branch with no
 * upstream is not a branch with nothing pushed: `git checkout -b my-feature` off
 * `origin/main` leaves the whole of `main` underneath it. Reading that as "no
 * comparison available" makes every commit since the baseline a stranded candidate,
 * which stays harmless only while the baseline is ITSELF at `origin/main` — the
 * `^runBase` exclusion then covers the shared history by accident. A primary parked
 * on `release` broke that accident: the baseline sat 28 commits behind `main`, the
 * human cut an unpushed feature branch off `main` mid-run, and the guard reported 39
 * stranded commits. Attribution then matched, because the agent had branched from
 * `main` and its PR had MERGED — so `main`'s own history was, commit for commit,
 * also on the agent's branch. A run whose work was merged and reviewed was failed
 * for the contents of `main`. The fix is to stop treating "this branch has no
 * upstream" as "nothing here is pushed": the frontier falls back to the remote's
 * default branch (`resolveRemoteDefaultRef`), which can only ever CLEAR content,
 * since every commit it reaches is on the remote by definition. Only a checkout with
 * no remote at all still has no frontier, and there an unpushed commit really is
 * unreviewed by definition.
 *
 * Two halves, deliberately split so they can sit on opposite ends of a run:
 * `capturePrimaryCheckoutState` stamps a baseline at spawn time (onto the agent
 * metadata, in `agentLifecycle.js`), and `detectPrimaryCheckoutDrift` re-reads it
 * in the shared finalize path (`agentFinalization.js`) — the one chokepoint all
 * three spawn modes (TUI, direct CLI, runner) already funnel through, so the
 * guard is not TUI-only without triplicating it.
 *
 * Every function here is NON-THROWING, for the same reason `gitCommitProbe.js`
 * is: it runs on the agent-completion path, outside the Express request
 * lifecycle, where a rejection has nothing to bubble to. An unreadable or
 * missing checkout, or a wedged git, degrades to "no drift observed" — the guard
 * never manufactures a failure out of a check that could not run.
 */

import { execGit } from './execGit.js';

/**
 * The completion reason a drifted run is recorded under. Registered in
 * `COMPLETION_REASON_ANALYSES` (agentErrorAnalysis.js) so the analyzer has a
 * verdict for it instead of falling through to a keyword sweep of the
 * transcript.
 */
export const PRIMARY_CHECKOUT_MUTATED_REASON = 'primary-checkout-mutated';

/**
 * The taxonomy token the drift is classified under. Reuses the pre-existing
 * `git-error` category rather than minting a new one, so every downstream
 * consumer (auto-fix tiers, learning buckets, the failure ledger) keeps
 * classifying it with no new token to teach them. Deliberately NOT in
 * `ENVIRONMENTAL_ERROR_CATEGORIES`: this is the run's own misbehavior, and it
 * should dent the task type's measured success rate.
 */
export const PRIMARY_CHECKOUT_MUTATED_CATEGORY = 'git-error';

/**
 * What a human has to do before this task may run again. Lives here so the
 * finalize-path analysis and the `COMPLETION_REASON_ANALYSES` registration can't
 * drift apart on it. A retry cannot repair a mutated checkout, so this
 * deliberately escalates rather than blind-retrying.
 */
export const PRIMARY_CHECKOUT_MUTATED_ESCALATION =
  'A worktree agent committed to the primary checkout. Confirm the commits are preserved (agent branch / open PR), restore the primary, then approve the retry.';

/** Bound on every git call here — this sits on finalize; nothing may wedge it. */
const GIT_TIMEOUT_MS = 10_000;

/** First line of a probe-shaped execGit result, or null. */
function firstLine(result) {
  if (!result || result.exitCode !== 0) return null;
  const value = (result.stdout || '').trim();
  return value || null;
}

/**
 * Read a checkout's current branch + HEAD SHA. Returns null when the path is
 * absent, is not a repo, has no commits yet, or git could not be run.
 *
 * A DETACHED head reports its branch as the literal `HEAD` and is kept as-is
 * (rather than nulled, the way `resolveWorkspaceBranch` does it) — this value is
 * only ever compared against a later reading of itself, and "detached, then on a
 * branch" is exactly the kind of movement worth reporting.
 *
 * @param {string} checkoutPath
 * @returns {Promise<{path: string, branch: string, head: string}|null>}
 */
export async function capturePrimaryCheckoutState(checkoutPath) {
  if (!checkoutPath || typeof checkoutPath !== 'string') return null;
  const options = { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS };
  const [branchResult, headResult] = await Promise.all([
    execGit(['rev-parse', '--abbrev-ref', 'HEAD'], checkoutPath, options).catch(() => null),
    execGit(['rev-parse', 'HEAD'], checkoutPath, options).catch(() => null),
  ]);
  const branch = firstLine(branchResult);
  const head = firstLine(headResult);
  if (!branch || !head) return null;
  return { path: checkoutPath, branch, head };
}

/**
 * How many commits `head` is ahead of `baseHead`. Returns null (not 0) when the
 * range can't be resolved — a rewritten/pruned baseline commit, or a git that
 * timed out — so the prose can say "moved" without asserting a count it doesn't
 * have.
 */
async function countCommitsAhead(checkoutPath, baseHead, head, { noMerges = false, excludes = [] } = {}) {
  const args = ['rev-list', '--count'];
  if (noMerges) args.push('--no-merges');
  args.push(head, `^${baseHead}`, ...excludes.map(ref => `^${ref}`));
  const result = await execGit(
    args,
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  const value = firstLine(result);
  const count = value === null ? NaN : parseInt(value, 10);
  return Number.isFinite(count) ? count : null;
}

/**
 * The branch's upstream tracking ref (`origin/main`), resolved to an IMMUTABLE
 * SHA — or null when it has none configured, or git could not be run. Pinning to
 * a SHA (rather than returning the symbolic `origin/main`) means the count and the
 * later `git cherry` walk compare against the same history even if a concurrent
 * fetch moves the tracking ref between calls — this guard runs against a shared
 * checkout that other actors are actively moving. Both failure modes collapse to
 * null on purpose: the caller treats "no comparison available" identically.
 */
async function resolveUpstreamSha(checkoutPath, branch) {
  const result = await execGit(
    ['rev-parse', `${branch}@{upstream}`],
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  return firstLine(result);
}

/**
 * The SYMBOLIC name of that same upstream (`origin/main`) — what the recovery prose
 * has to quote, because a branch does NOT necessarily track a remote branch of its
 * own name. A local WIP branch cut from `main` with `branch.autoSetupMerge` on
 * tracks `origin/main`, so the prose's old hardcoded `origin/<branch>` named a ref
 * that does not exist (#4098): the "recovery" command errors out, and the reader who
 * corrects it to the real upstream discards every local commit on the branch.
 * Null when there is no upstream or git could not be run.
 */
async function resolveUpstreamRef(checkoutPath, branch) {
  const result = await execGit(
    ['rev-parse', '--abbrev-ref', `${branch}@{upstream}`],
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  return firstLine(result);
}

/**
 * The remote's DEFAULT-BRANCH tracking ref as `{ ref, sha }` — the pushed frontier
 * to fall back on when `current.branch` has no upstream of its own (#4717).
 *
 * "No upstream" is not "nothing is pushed". A human on the shared primary running
 * `git checkout -b my-feature` has a branch with no upstream sitting on top of the
 * whole of `origin/main`, and treating that as "no comparison available" makes the
 * guard read every commit since the baseline as stranded. That is survivable while
 * the baseline is itself at `origin/main` — `^runBase` then excludes the shared
 * history anyway — and it is exactly what broke when the baseline was NOT: a primary
 * parked on `release` (behind `main`) was read as stranding 39 commits, 28 of which
 * were ordinary merged `main` history. Every one of those was also on the agent's
 * branch, because the agent branched from `main` and its PR had since merged, so
 * attribution matched and the run was failed for `main`'s own history. This is the
 * #4098 shape reached through the no-upstream fallback that #4098 did not touch.
 *
 * `origin/HEAD` first (the remote's own answer), then the conventional names. All
 * three are remote-tracking refs, so anything they reach is by definition pushed —
 * the frontier only ever CLEARS content, never invents a stranded commit. A repo
 * with no remote at all resolves to null and keeps the pre-existing behavior: an
 * unpushed commit is unreviewed by definition, so the guard still attributes it
 * against the run baseline.
 *
 * NON-THROWING, like the rest of the module.
 */
export async function resolveRemoteDefaultRef(checkoutPath) {
  for (const ref of ['origin/HEAD', 'origin/main', 'origin/master']) {
    const result = await execGit(
      ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
      checkoutPath,
      { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
    ).catch(() => null);
    const sha = firstLine(result);
    if (!sha) continue;
    // `origin/HEAD` is a symref; name the branch it points at, since the ref goes
    // into a `reset --hard` command a human types later and `origin/HEAD` reads as
    // a footgun even where it resolves.
    if (ref !== 'origin/HEAD') return { ref, sha };
    return { ref: (await resolveSymbolicRemoteHead(checkoutPath)) || ref, sha };
  }
  return null;
}

/** `origin/HEAD`'s target in `origin/<branch>` form, or null. Non-throwing. */
async function resolveSymbolicRemoteHead(checkoutPath) {
  const result = await execGit(
    ['rev-parse', '--abbrev-ref', 'origin/HEAD'],
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  return firstLine(result);
}

/**
 * Resolve the agent's own worktree branch to an IMMUTABLE commit SHA — trying the
 * local branch first, then its `origin/<branch>` remote-tracking form (the agent
 * may have pushed and had its local ref pruned). Returns the SHA (not the ref
 * name) so the count and the `git cherry` walk pin to the same commit even if the
 * shared branch ref is moved or pruned between the two calls. Returns null when
 * neither resolves, the name is empty, or git could not be run — every one of
 * which the caller treats as "cannot attribute, so do not blame".
 */
async function resolveAgentBranchSha(checkoutPath, agentBranch) {
  if (!agentBranch || typeof agentBranch !== 'string') return null;
  for (const ref of [agentBranch, `refs/remotes/origin/${agentBranch}`]) {
    const result = await execGit(
      ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
      checkoutPath,
      { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
    ).catch(() => null);
    const sha = firstLine(result);
    if (sha) return sha;
  }
  return null;
}

/**
 * The commits `driftedHead` carries that the upstream lacks BY CONTENT (#3744) —
 * `git cherry <upstream> <driftedHead> <runBase>`, keeping only the `+` lines
 * (no patch-equivalent upstream). Merge commits are excluded by `git cherry`
 * itself, matching the `noMerges` counts.
 *
 * This is the sha-based `upstream..head` count made patch-id-precise. It matters
 * because PortOS rebase-merges PRs: the merged commit's sha upstream differs
 * from the copy on the primary, so a sha comparison reports "unpushed" for
 * content that is fully pushed and reviewed.
 *
 * The `runBase` limit keeps a PRE-run unpushed commit out of the set (it is not
 * this run's doing). A limit that no longer exists in the history — the baseline
 * commit rewritten by a mid-run `git pull --rebase` on the primary — widens the
 * walk rather than breaking it, and the patch-equivalence filter still drops
 * every rewritten copy, since a rebase preserves patch-ids.
 *
 * Returns null when there is no upstream to compare against, or `git cherry`
 * could not run — both of which the caller must treat as "no patch-level verdict
 * available" and fall back to the sha counts, never as "verified clean".
 * NON-THROWING.
 */
async function listStrandedByPatch(checkoutPath, { runBase, upstream, driftedHead }) {
  if (!upstream) return null;
  const result = await execGit(
    ['cherry', upstream, driftedHead, runBase],
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  if (!result || result.exitCode !== 0) return null;
  return (result.stdout || '')
    .split('\n')
    .filter(line => line.startsWith('+ '))
    .map(line => line.slice(2).trim())
    .filter(Boolean);
}

/**
 * The commits in `limit..head` that DO have a patch-equivalent somewhere in `of`'s
 * history — the `-` lines of `git cherry -v <of> <head> <limit>`. The mirror of
 * `listStrandedByPatch`, used on the attribution side to ask "is this commit a
 * rebased/cherry-picked copy of one on the agent's branch?".
 *
 * Returns null when the walk could not run, which every caller must treat as "no
 * verdict available" and never as "nothing matched". NON-THROWING.
 */
async function listPatchEquivalentShas(checkoutPath, { of, head, limit }) {
  const result = await execGit(
    ['cherry', '-v', of, head, limit],
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  if (!result || result.exitCode !== 0) return null;
  return (result.stdout || '')
    .split('\n')
    .filter(line => line.startsWith('- '))
    .map(line => line.split(' ')[1])
    .filter(Boolean);
}

/**
 * Is `descendant` STRICTLY ahead of `ancestor` — reachable from it, and not the same
 * commit? Non-throwing; an unresolvable comparison returns false, which the caller
 * treats as "no reason to skip the attribution checks".
 */
async function isStrictlyAhead(checkoutPath, ancestor, descendant) {
  if (!ancestor || !descendant || ancestor === descendant) return false;
  return isAncestorOrSame(checkoutPath, ancestor, descendant);
}

/**
 * Is `ancestor` still reachable from `descendant` (or the same commit)? Used to ask
 * whether the spawn-time baseline survived the run — a mid-run `git pull --rebase`
 * on the primary rewrites its local commits and orphans that sha. Non-throwing; an
 * unresolvable comparison returns false, so an unreadable history reports the
 * baseline as rewritten rather than quoting a commit count derived from it.
 */
async function isAncestorOrSame(checkoutPath, ancestor, descendant) {
  if (!ancestor || !descendant) return false;
  if (ancestor === descendant) return true;
  const result = await execGit(
    ['merge-base', '--is-ancestor', ancestor, descendant],
    checkoutPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  return Boolean(result && result.exitCode === 0);
}

/**
 * Was the drift plausibly THIS agent's doing (#3703)? Looks only at the commits
 * that could actually be this run's branch-jack — reachable from the drifted head,
 * created AFTER spawn (not reachable from `runBase`, the checkout's HEAD at spawn)
 * AND still unpushed (not reachable from the branch's `upstream`) — and asks whether
 * any of them is the agent's own, by SHA or by PATCH-ID (so a cherry-picked / rebased
 * copy still matches — a raw-SHA check would miss the case the #3680 incident could
 * have produced).
 *
 * Excluding BOTH ends of that window is essential. A commit the agent merely inherited
 * from the primary at spawn, and a shared upstream commit a pull brought onto the
 * primary during the run, are each already on the agent's branch — `git cherry` omits
 * them (same SHA) — yet either would otherwise be counted as stranded and silently
 * re-blame the agent for a drift another actor caused: the exact #3703 regression.
 * Only a commit that is new this run AND unpushed can be the agent's branch-jack.
 *
 * Returns true when AT LEAST ONE such commit is the agent's own. Every uncertain
 * outcome — no branch name, a branch that does not resolve, or a failed git call —
 * returns FALSE (unattributed), failing open by design: a missed branch-jack still
 * leaves a warn log and recoverable commits, while a false failure escalates to a
 * human and dents the task type's success rate. NON-THROWING, like the rest of the
 * module.
 *
 * `strandedShas` — the caller's patch-level stranded set — is what makes the second
 * half of that window trustworthy, and its absence is what made #4098 fail a run
 * whose PR had merged. See the comment on the preferred path below.
 */
async function isDriftAttributableToAgent(checkoutPath, { runBase, upstream, driftedHead, agentBranch, strandedShas = null, baselineRewritten = false }) {
  const agentSha = await resolveAgentBranchSha(checkoutPath, agentBranch);
  if (!agentSha) return false;
  // The agent's branch is BUILT ON TOP OF the drifted head, so the stranded commits are
  // part of the branch's BASE — put there by whoever moved the primary first, then
  // inherited when the agent branched from (or rebased onto) the moved `main`. `/do:pr`
  // rebases onto `main` before pushing, so EVERY agent that outlives a concurrent commit
  // to `main` ends in this shape; the reachability check below only asks "is this commit
  // on the agent's branch?", and would read that inherited base as proof of authorship.
  // The causal arrow runs primary → agent here, which is a rebase, not a branch-jack.
  //
  // A real jack leaves the primary AT a commit the agent authored — its branch tip, or a
  // patch-equivalent copy on a divergent history — never strictly BEHIND its own branch,
  // so the #3680 incident shape still fails this test and is still caught. The residual
  // miss (an agent that jacks and then keeps committing to its branch) is the documented
  // fail-open trade in the module header, and its commits are on a pushed branch anyway.
  if (await isStrictlyAhead(checkoutPath, driftedHead, agentSha)) return false;

  // Preferred path (#4098): the caller already resolved WHICH commits are stranded,
  // by patch-id — the set that excludes, by content, everything the upstream has.
  // Attribution then only ever asks about THOSE commits.
  //
  // That restriction is what keeps a MERGED agent branch from indicting the whole of
  // `main`. Once the agent's PR lands, its branch is an ancestor of the upstream, so
  // `git cherry <agentSha> …` marks `-` every commit in the window whose patch is
  // anywhere in upstream history — including the primary's own local copies of
  // already-merged work, which are nobody's branch-jack. The observed run failed on
  // exactly that: two commits the stranded set had ALREADY cleared as upstream
  // content were matched against the agent's merged branch and read as its own. The
  // module header says the two sides must agree; intersecting them is how.
  //
  // Restricted this way, the patch test is sound with no freshness filter: a stranded
  // commit has NO patch-equivalent upstream, so a patch-equivalent on the agent's
  // branch can only be one of the agent's OWN commits.
  if (Array.isArray(strandedShas)) {
    if (strandedShas.length === 0) return false;
    // Literal branch-jack: the agent's branch carries a stranded commit outright.
    for (const sha of strandedShas) {
      if (await isAncestorOrSame(checkoutPath, sha, agentSha)) return true;
    }
    // Patch-equivalent branch-jack: a cherry-picked / rebased copy, different sha.
    const equivalents = await listPatchEquivalentShas(checkoutPath, {
      of: agentSha,
      head: driftedHead,
      limit: upstream || runBase,
    });
    if (!equivalents) return false;
    const stranded = new Set(strandedShas);
    return equivalents.some(sha => stranded.has(sha));
  }

  // Fallback: no patch-level stranded set (no upstream to compare against, or the
  // walk failed). Approximate it with the sha window below.
  // Candidate branch-jack commits (set S): new this run (`^runBase`) AND unpushed
  // (`^upstream`, when there is an upstream to compare against), non-merge only — a
  // merge commit reaches the primary via a human's `git merge` / non-ff pull, never a
  // `/do:pr` branch-jack.
  const strandedExcludes = upstream ? [upstream] : [];
  const strandedTotal = await countCommitsAhead(checkoutPath, runBase, driftedHead, { noMerges: true, excludes: strandedExcludes });
  if (!strandedTotal) return false;
  // Literal branch-jack: a candidate commit also on the agent's branch by SHA (a
  // fast-forward of the agent's own commit onto the primary). `git cherry` omits these,
  // so detect them by reachability: if excluding the agent's branch drops the count,
  // some candidate commit is the agent's.
  const strandedNotOnAgent = await countCommitsAhead(checkoutPath, runBase, driftedHead, { noMerges: true, excludes: [...strandedExcludes, agentSha] });
  // A failed count is null; `null < n` coerces to `0 < n` and would falsely attribute
  // (a false failure), so treat an unresolvable count as "cannot determine" and fail open.
  if (strandedNotOnAgent === null) return false;
  if (strandedNotOnAgent < strandedTotal) return true;
  // Patch-equivalent branch-jack: a cherry-picked / rebased copy (different SHA, missed
  // by the reachability check). `git cherry <upstream> <head> <limit>` marks such a
  // commit `-`. Walk unpushed commits (limit = upstream), then keep only a `-` commit
  // that is new this run — a pre-run copy is a prior run's problem, not this one's.
  //
  // That "new this run" test is reachability against `runBase`, so a mid-run `git pull
  // --rebase` on the primary breaks it: the replayed commits get new shas, the baseline
  // is orphaned, and NOTHING on the current history is an ancestor of it — every `-`
  // commit then reads as fresh, whenever it was really made. An unanswerable check must
  // fail open (the module's contract), not answer "yes" by default.
  if (baselineRewritten) return false;
  const equivalentShas = await listPatchEquivalentShas(checkoutPath, {
    of: agentSha,
    head: driftedHead,
    limit: upstream || runBase,
  });
  if (!equivalentShas) return false;
  for (const sha of equivalentShas) {
    const ancestor = await execGit(
      ['merge-base', '--is-ancestor', sha, runBase],
      checkoutPath,
      { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
    ).catch(() => null);
    // exitCode 1 → sha is NOT an ancestor of runBase → created during the run.
    if (ancestor && ancestor.exitCode === 1) return true;
  }
  return false;
}

/** Short SHA for human-readable prose. */
const short = sha => String(sha || '').slice(0, 9);

/**
 * Re-read the baseline and report whether the primary checkout moved during the
 * run.
 *
 * Outcomes, never collapsed:
 *   - `{ drifted: false }` — it didn't move, OR there was nothing to check, OR
 *     the checkout could not be read (nothing was verified, so nothing is
 *     claimed).
 *   - `{ drifted: false, fastForwarded: true, … }` — HEAD moved on the SAME
 *     branch but every commit is already on that branch's upstream. That is a
 *     `git pull`, not a branch-jack; carried as a distinct shape (rather than a
 *     bare `false`) so a caller can log what it observed.
 *   - `{ drifted: false, unattributed: true, … }` — commits WERE stranded, but
 *     none are patch-equivalent to a commit on the agent's own branch, so this
 *     run demonstrably did not put them there (a concurrent actor did). Carries
 *     the `message` so the caller can warn-log the unreviewed commits without
 *     failing the run. See the module header on the fail-open asymmetry.
 *   - `{ drifted: true, … }` — the checkout ended on a different branch, or it
 *     carries commits the upstream does not have AND those commits are
 *     attributable to the agent's own branch by patch-id.
 *
 * @param {{path: string, branch: string, head: string}|null} baseline stamped by
 *   `capturePrimaryCheckoutState` at spawn time
 * @param {{ agentBranch?: string|null }} [options] the agent's own worktree
 *   branch, used both to ATTRIBUTE the stranded commits by patch-id and, once
 *   attributed, named in the recovery prose because it is where the same commits
 *   almost certainly also live
 */
export async function detectPrimaryCheckoutDrift(baseline, { agentBranch = null } = {}) {
  if (!baseline?.path || !baseline?.branch || !baseline?.head) return { drifted: false };
  const current = await capturePrimaryCheckoutState(baseline.path);
  // Unreadable now (deleted, mid-rebase, git wedged): we verified nothing, so we
  // report nothing rather than inventing a failure.
  if (!current) return { drifted: false };
  if (current.branch === baseline.branch && current.head === baseline.head) return { drifted: false };

  // Pin the upstream to a SHA and count everything against `current.head` (the SHA
  // captured above), never the live `current.branch` — a concurrent commit or
  // fetch on the shared checkout must not make the two counts and the cherry walk
  // read different histories.
  //
  // A branch with no upstream of its own falls back to the remote's default branch
  // (#4717): a freshly-cut local branch is not "nothing is pushed", and reading it
  // that way strands the whole of `main` whenever the baseline sits behind `main`.
  // See `resolveRemoteDefaultRef`. Null only when the checkout has no remote at all.
  const ownUpstream = await resolveUpstreamSha(baseline.path, current.branch);
  const fallbackUpstream = ownUpstream ? null : await resolveRemoteDefaultRef(baseline.path);
  const upstream = ownUpstream || fallbackUpstream?.sha || null;
  const [commitCount, unpushedCount] = await Promise.all([
    countCommitsAhead(baseline.path, baseline.head, current.head),
    // Commits the branch carries that its upstream does not — the only commits a
    // branch-jack actually strands. Null (not 0) when there is no upstream to
    // compare against, so "verified clean" never masquerades as "could not check".
    upstream ? countCommitsAhead(baseline.path, upstream, current.head) : Promise.resolve(null),
  ]);

  // The same question asked by patch-id rather than by sha (#3744) — null when
  // there is no upstream or the walk failed, which must NOT read as "clean".
  // Skipped when the sha count already cleared the checkout: it can only agree.
  const strandedByPatch = unpushedCount === 0
    ? []
    : await listStrandedByPatch(baseline.path, { runBase: baseline.head, upstream, driftedHead: current.head });

  // Same branch, nothing local-only: the checkout was pulled forward onto commits
  // that are already upstream (reviewed, merged, pushed). Nothing was stranded, so
  // there is nothing for a human to recover. An empty patch-level set clears it
  // just as a zero sha count does — a rebase-merged copy is upstream content
  // wearing a local sha, and telling a human to `reset --hard` over it is the
  // false alarm this guard exists to avoid.
  if (current.branch === baseline.branch && (unpushedCount === 0 || strandedByPatch?.length === 0)) {
    return { drifted: false, fastForwarded: true, baseline, current, commitCount };
  }

  // Did the baseline commit survive the run? A `git pull --rebase` on the primary
  // REWRITES the local commits it replays, orphaning the sha stamped at spawn — at
  // which point `commitCount` counts the whole post-fork history rather than the
  // run's movement, and the prose ("16 new commits") badly overstates what moved.
  // Say so instead of quoting a number that no longer means what it says.
  const baselineRewritten = !(await isAncestorOrSame(baseline.path, baseline.head, current.head));
  const driftFacts = { baseline, current, commitCount, baselineRewritten };
  const message = formatDriftMessage(driftFacts);
  const unattributedMessage = async () => withCommitSubject(
    formatDriftMessage({ ...driftFacts, attributed: false }),
    await commitSubject(baseline.path, current.head),
  );

  // Second gate (#3703): stranded commits are only a failure if THIS agent could
  // have produced them. Attribution runs whenever there is (or should be) a
  // stranded commit — a resolvable positive count, OR an UNRESOLVABLE count
  // (`null`: a pruned baseline or a wedged git), which must fail OPEN rather than
  // manufacture a failure out of a check that could not run.
  // Prefer the patch-level verdict when there is one; a resolved empty set means
  // nothing is stranded even where the sha count disagrees. Null falls back to the
  // sha count, and a null THERE falls back to the movement count, which is
  // unresolvable-and-therefore-fail-open below.
  const strandedCount = strandedByPatch
    ? strandedByPatch.length
    : (unpushedCount === null ? commitCount : unpushedCount);

  // A BARE BRANCH SWITCH — the checkout is parked on a different branch and
  // stranded exactly nothing (#4231). This used to skip attribution entirely and
  // fail the run on the theory that there was "nothing to blame on anyone", which
  // inverted the gate: the shape with the LEAST evidence of a branch-jack was the
  // only one that never had to prove authorship. The primary is a shared checkout,
  // and a human running `git checkout -b my-feature` in it is ordinary work — so
  // every agent alive at that moment was failed, with a recovery note that
  // contradicted its own escalation ("No commits were stranded" under "A worktree
  // agent committed to the primary"). agent-8249579a was recorded
  // `success: false` this way while its PR was merging.
  //
  // With nothing stranded there is no commit to attribute by patch-id, so the one
  // signal left is WHICH branch the checkout landed on. The agent's OWN worktree
  // branch is a shape only the agent produces, and it stays a failure. Any other
  // branch is somebody else's business: warn-logged as `unattributed` (the primary
  // being off `main` still matters — the next spawn baselines against it) but never
  // a failure, per the fail-open asymmetry in the module header.
  if (strandedCount === 0 && current.branch !== agentBranch) {
    return { drifted: false, unattributed: true, baseline, current, commitCount, unpushedCount, message: await unattributedMessage() };
  }
  if (strandedCount === null || strandedCount > 0) {
    const attributed = await isDriftAttributableToAgent(baseline.path, {
      runBase: baseline.head,
      upstream,
      driftedHead: current.head,
      agentBranch,
      strandedShas: strandedByPatch,
      baselineRewritten,
    });
    if (!attributed) {
      return { drifted: false, unattributed: true, baseline, current, commitCount, unpushedCount, message: await unattributedMessage() };
    }
  }

  return {
    drifted: true,
    reason: PRIMARY_CHECKOUT_MUTATED_REASON,
    category: PRIMARY_CHECKOUT_MUTATED_CATEGORY,
    baseline,
    current,
    commitCount,
    unpushedCount,
    message,
    suggestedFix: formatDriftRecovery({
      current,
      baseline,
      commitCount,
      unpushedCount,
      strandedCount,
      agentBranch,
      // Symbolic, not the pinned sha: this goes into a command a human runs later.
      // Must name the ref the stranded set was actually computed against, or the
      // reader inspects a different range than the one the count came from — which
      // for a branch with no upstream meant quoting an `origin/<branch>` that does
      // not exist and whose `reset --hard` errors out (the #4098 lesson, reached
      // through the fallback path).
      upstreamRef: (await resolveUpstreamRef(baseline.path, current.branch)) || fallbackUpstream?.ref || null,
      upstreamIsRemoteDefault: !ownUpstream && Boolean(fallbackUpstream),
    }),
  };
}

/**
 * Human-readable "what moved". Pure.
 *
 * `attributed: false` is the unattributed outcome: the checkout moved, and this
 * run's branch does not contain the new commits. The lead must not accuse the
 * worktree agent — the caller is about to say the movement was someone else's.
 */
export function formatDriftMessage({ baseline, current, commitCount, baselineRewritten = false, attributed = true }) {
  const branchPart = current.branch === baseline.branch
    ? `branch ${current.branch}`
    : `branch ${baseline.branch} → ${current.branch}`;
  const countPart = commitCount === null
    ? 'commit count unresolved'
    : baselineRewritten
      // The baseline is off the current history (a rebase replayed it under a new
      // sha), so the count spans the fork point, not the run. Label it as such
      // rather than passing it off as "N new commits".
      ? `baseline rewritten by a rebase; ${commitCount} commit${commitCount === 1 ? '' : 's'} since the abandoned baseline`
      : `${commitCount} new commit${commitCount === 1 ? '' : 's'}`;
  const lead = attributed
    ? `Worktree agent mutated the primary checkout ${baseline.path}`
    : `Primary checkout ${baseline.path} moved during a worktree run`;
  return `${lead}: ${branchPart}, HEAD ${short(baseline.head)} → ${short(current.head)} (${countPart})`;
}

/** One-line subject of `sha`, or '' when git cannot name it. Never throws. */
async function commitSubject(repoPath, sha) {
  if (!repoPath || !sha) return '';
  const result = await execGit(
    ['log', '-1', '--format=%s', sha],
    repoPath,
    { ignoreExitCode: true, timeout: GIT_TIMEOUT_MS },
  ).catch(() => null);
  const subject = firstLine(result);
  if (!subject) return '';
  const oneLine = subject.replace(/[\r\n"]/g, ' ').replace(/\s+/g, ' ').trim();
  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}…` : oneLine;
}

function withCommitSubject(message, subject) {
  return subject ? `${message} — "${subject}"` : message;
}

/**
 * The recovery advice. Names the exact commands and is explicit that the reset
 * discards commits — PortOS deliberately does not run it (see the module header).
 *
 * Two shapes, because the two failures need different commands: a checkout left
 * on the WRONG BRANCH with nothing local-only just needs checking back out (no
 * reset, nothing to discard, no reason to scare the reader with `--hard`), while
 * stranded commits need the inspect-then-reset flow. Pure.
 *
 * `upstreamRef` is the branch's ACTUAL upstream (`git rev-parse --abbrev-ref
 * <branch>@{upstream}`), not an assumption that it is `origin/<branch>`; see
 * `resolveUpstreamRef`. It falls back to `origin/<branch>` only when the caller could
 * not resolve one, which is the pre-#4098 wording.
 *
 * `upstreamIsRemoteDefault` says that ref is the REMOTE'S DEFAULT BRANCH standing in
 * for a branch that has no upstream (#4717), not something the branch tracks — the
 * reset is just as wide either way, but telling a reader their branch "tracks"
 * `origin/main` when it tracks nothing sends them to `git branch -u` to undo a
 * setting that was never there.
 */
export function formatDriftRecovery({ current, baseline = null, commitCount, unpushedCount = null, strandedCount = null, agentBranch, upstreamRef = null, upstreamIsRemoteDefault = false }) {
  if (unpushedCount === 0 && baseline?.branch && baseline.branch !== current.branch) {
    return [
      `A worktree-isolated agent left the PRIMARY checkout on its own worktree branch \`${current.branch}\` instead of \`${baseline.branch}\`.`,
      `No commits were stranded — \`${current.branch}\` carries nothing its upstream lacks — so restore it with \`git -C ${current.path} checkout ${baseline.branch}\`.`,
    ].join(' ');
  }
  const alsoOn = agentBranch
    ? `The same commits were almost certainly pushed on the agent's own branch \`${agentBranch}\` too, so check there (and for an open PR) before discarding anything.`
    : 'Check the agent\'s own branch (and for an open PR) for the same commits before discarding anything.';
  // The actionable number is what the upstream is MISSING, not how far HEAD moved
  // — a pull that also carried the agent's commit moves HEAD further than the
  // damage goes. `strandedCount` is the caller's patch-level tally when it has
  // one; the sha counts are the fallback.
  const stranded = strandedCount === null
    ? (unpushedCount === null ? commitCount : unpushedCount)
    : strandedCount;
  const countPhrase = stranded === null ? 'commits' : `${stranded} commit${stranded === 1 ? '' : 's'}`;
  const resetTarget = upstreamRef || `origin/${current.branch}`;
  // A branch tracking something other than its own remote counterpart (a local WIP
  // branch cut from `main` tracks `origin/main`) rewinds ONTO THAT — which is most of
  // the branch, not just the drift. Say so where the reader is about to type it.
  const trackingCaveat = upstreamRef && upstreamRef !== `origin/${current.branch}`
    ? upstreamIsRemoteDefault
      ? ` Note that \`${current.branch}\` has no upstream of its own, so \`${upstreamRef}\` is the remote's default branch standing in for one — that reset rewinds onto \`${upstreamRef}\` and drops every local commit on the branch, not only the agent's.`
      : ` Note that \`${current.branch}\` tracks \`${upstreamRef}\` rather than a remote branch of its own, so that reset rewinds it onto \`${upstreamRef}\` and drops every local commit on it, not only the agent's.`
    : '';
  return [
    `A worktree-isolated agent committed to the PRIMARY checkout instead of its worktree, leaving \`${current.branch}\` carrying ${countPhrase} PortOS never reviewed.`,
    alsoOn,
    `Inspect them with \`git -C ${current.path} log --oneline ${resetTarget}..${current.branch}\`, and once you have confirmed the content is upstream (or preserved on the agent branch) restore the checkout with \`git -C ${current.path} reset --hard ${resetTarget}\`.`,
    `That reset DISCARDS those commits, so PortOS will not run it for you.${trackingCaveat}`,
  ].join(' ');
}