flowviant 0.103.0 → 0.104.0

package/bin/lib/workAdoptCarry.mjs

@@ -0,0 +1,94 @@
+/**
+ * ADOPTION'S DIRTY CARRY — a terminal checkout's uncommitted state copied,
+ * read-only, into the fresh worktree a tab adopts it into.
+ *
+ * Split out of work.mjs (2026-09-26, SOLID F037). It is git plumbing with a
+ * promise of its own (the source is never written, a problem becomes one line
+ * for the agent to say), reached once, from the session lane's adopt path.
+ */
+import { execFileSync } from 'node:child_process';
+import { cpSync, lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { git, gitRaw, splitNul } from './git.mjs';
+
+export function createAdoptCarry({ sessionMetaPath }) {
+  /**
+   * Carry a terminal checkout's DIRTY state into a fresh adopt worktree. The
+   * source is strictly READ-ONLY — nothing here writes to it, because it is
+   * the human's own checkout and adoption promises to leave it exactly as the
+   * closed terminal did. Tracked changes travel as one binary patch staged
+   * through the worktree's PRIVATE git dir (invisible to status, dies with the
+   * tree); untracked files are copied one by one, skipping anything over 5MB.
+   *
+   * Returns '' or ONE bracketed line for the turn's prompt: a carry problem is
+   * the AGENT's to explain to the user, never a reason to fail the adoption —
+   * the conversation is the thing being adopted, and it resumes either way.
+   */
+  const carryDirtyState = (srcCwd, wt, sessionId) => {
+    const problems = [];
+    try {
+      // A Buffer, not utf8: a `--binary` patch (and a hunk from a non-UTF-8
+      // text file) must round-trip byte-exact or the apply corrupts what it
+      // carries. 64MB of headroom — a dirtier tree than that fails the read
+      // here and is SAID, below, rather than half-applied.
+      const patch = execFileSync('git', ['diff', 'HEAD', '--binary'], {
+        cwd: srcCwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      if (patch.length) {
+        const patchPath = sessionMetaPath(wt, 'flowviant-adopt.patch', sessionId);
+        if (!patchPath) throw new Error('no private git dir to stage the patch in');
+        try {
+          writeFileSync(patchPath, patch);
+          git(['apply', '--whitespace=nowarn', patchPath], wt);
+        } finally {
+          try {
+            rmSync(patchPath, { force: true });
+          } catch {
+            /* best-effort — the private git dir dies with the worktree anyway */
+          }
+        }
+      }
+    } catch {
+      problems.push(
+        'their uncommitted TRACKED changes did not carry over (they are still in the terminal checkout, untouched)'
+      );
+    }
+    try {
+      const skipped = [];
+      for (const rel of splitNul(
+        gitRaw(['ls-files', '--others', '--exclude-standard', '-z'], srcCwd)
+      )) {
+        try {
+          const from = join(srcCwd, rel);
+          // lstat, not stat: a symlink is carried as itself, and its own size
+          // is what the 5MB budget judges — never the file it points at.
+          if (lstatSync(from).size > 5 * 1024 * 1024) {
+            skipped.push(rel);
+            continue;
+          }
+          const to = join(wt, rel);
+          mkdirSync(dirname(to), { recursive: true });
+          cpSync(from, to);
+        } catch {
+          skipped.push(rel);
+        }
+      }
+      if (skipped.length) {
+        problems.push(
+          `${skipped.length} untracked file${skipped.length === 1 ? '' : 's'} did not carry (over 5MB or unreadable): ${skipped.slice(0, 5).join(', ')}${skipped.length > 5 ? ', …' : ''}`
+        );
+      }
+    } catch {
+      problems.push(
+        'untracked files could not be listed in the terminal checkout, so none were carried'
+      );
+    }
+    return problems.length
+      ? `[ADOPTION NOTE from the daemon — tell the user plainly at the start of your reply: ${problems.join('; ')}.]`
+      : '';
+  };
+
+  return { carryDirtyState };
+}

package/bin/lib/workAgentCheck.mjs

@@ -0,0 +1,278 @@
+/**
+ * THE PROJECT'S OWN CHECK — the repo's declared command, run in the agent's
+ * worktree the moment its queue empties, and its answer posted as a label.
+ *
+ * Split out of workAgentReview.mjs (SOLID F039): this half changes for
+ * SECURITY reasons (what a repo-controlled command may see and reach — the
+ * artifact-directory fence, the environment without the machine credential,
+ * the process-group kill), the pre-review for MODEL-REPORTING ones. The review
+ * entry beat sequences the two and owns neither.
+ */
+import { readFileSync, lstatSync, rmSync, readdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { FLEET_URL } from './config.mjs';
+import { git } from './git.mjs';
+import { warn } from './ui.mjs';
+import { ARTIFACT_DIR, artifactTypeFor } from './artifacts.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+import { withoutMachineCredentials } from './machineEnv.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+
+/**
+ * CLEAR THE ARTIFACTS DIRECTORY OF ANYTHING THAT IS NOT AN ARTIFACT, BEFORE
+ * THE PROJECT'S CHECK RUNS OVER THE WORKTREE (2026-09-24).
+ *
+ * A design or research turn may write under `.flowviant/artifacts/` and
+ * nowhere else — that posture's whole safety claim is that such a card
+ * changes no repository file. But the check is the repo's own command, run
+ * unattended in the same worktree the moment the queue empties, and a test
+ * runner's DEFAULT discovery reaches into that directory: vitest collected and
+ * ran `.flowviant/artifacts/pwn.test.js` with no include override. So a card
+ * steered by text it read could plant a test and have the machine execute it,
+ * before any person looked — and the directory is git-excluded, so the file
+ * never appears in the diff a reviewer reads.
+ *
+ * What an artifact IS is already a closed list (`ARTIFACT_TYPES`), and the
+ * scan only ever shows TOP-LEVEL regular files: anything else there is
+ * nothing the product will show, so removing it before the check costs
+ * nothing a person could see. Symlinks and subdirectories go whole; a
+ * `.flowviant` that is not a real directory is left alone (that is the
+ * repository's own content, not something a turn wrote). Returns the names
+ * removed, for the log line.
+ */
+export function clearNonArtifacts(wt) {
+  const removed = [];
+  try {
+    const parent = lstatSync(join(wt, '.flowviant'));
+    if (parent.isSymbolicLink() || !parent.isDirectory()) return removed;
+    const dir = join(wt, ARTIFACT_DIR);
+    const st = lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+      rmSync(dir, { force: true, recursive: false });
+      removed.push(ARTIFACT_DIR);
+      return removed;
+    }
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name);
+      let e;
+      try {
+        e = lstatSync(p);
+      } catch {
+        continue; // vanished between the list and the stat
+      }
+      const keep = e.isFile() && !name.startsWith('.') && artifactTypeFor(name) !== null;
+      if (keep) continue;
+      try {
+        rmSync(p, { recursive: true, force: true });
+        removed.push(name);
+      } catch {
+        /* best-effort — reported by omission */
+      }
+    }
+  } catch {
+    /* no artifacts directory — the ordinary case */
+  }
+  return removed;
+}
+
+/**
+ * THE ENVIRONMENT THE PROJECT'S CHECK RUNS UNDER: the daemon's own, minus the
+ * machine credential — the same rule `cliEnv` (runTurn.mjs) applies to a turn,
+ * imported from its one home (machineEnv.mjs) rather than from the CLI
+ * module, so the check never depends on the CLI module's spawn helpers. Nothing a check runs needs the credential the daemon
+ * authenticates with; everything else is what the agent's own turn saw when it
+ * ran the same tests.
+ */
+export function checkEnv(env = process.env) {
+  return withoutMachineCredentials(env);
+}
+
+export function createWorkAgentCheck({ repoRoot, postBestEffort, workChildren, groupKillChildren }) {
+  const AGENT_CHECK_DONE_URL = fleetEndpoint('agent-check-done', FLEET_URL);
+
+  // ── THE PROJECT'S OWN CHECK, and the MERGE ─────────────────────────────────
+  //
+  // The check runs in the agent's own worktree the moment its queue empties, so
+  // a reviewer knows before they start reading whether they are reviewing
+  // working code. It LABELS the review row; it never blocks it.
+  //
+  // IT IS THE REPO'S COMMAND, DECLARED IN THE REPO. `.flowviant/check.json`,
+  // beside `deploy.json`, because a check travels with the code and changes
+  // with it — a setting in the app would go stale the first time somebody
+  // renamed a script. An absent file is a MEASURED answer ('none'), not a nag:
+  // plenty of projects have no single command that means "is this alright".
+  //
+  // It runs through a shell, and that is no wider than what already happens in
+  // that directory: every turn in this worktree spawns a CLI with build
+  // permissions, so a repository that can run arbitrary code during a turn can
+  // run it here too. What this is NOT is the deleted dev-run supervisor —
+  // nothing here resolves a command, guesses a stack, or starts a server.
+  const CHECK_TIMEOUT_MS = 10 * 60_000;
+  const CHECK_OUTPUT_CAP = 4000;
+
+  const readCheckCommand = () => {
+    try {
+      const raw = readFileSync(join(repoRoot, '.flowviant', 'check.json'), 'utf8');
+      const cfg = JSON.parse(raw);
+      const cmd = typeof cfg?.command === 'string' ? cfg.command.trim() : '';
+      return cmd ? cmd.slice(0, 500) : null;
+    } catch {
+      return null; // absent, unreadable or not JSON — all mean "no check"
+    }
+  };
+
+  const postCheck = async (body) => {
+    // Same bounded retry as postAgentPlan — see postBestEffort. On the
+    // final failure the row simply keeps its previous answer, which is
+    // null the first time.
+    await postBestEffort(AGENT_CHECK_DONE_URL, body);
+  };
+
+  const runCheck = async (agentId, wt) => {
+    const cmd = readCheckCommand();
+    const headSha = (git(['rev-parse', 'HEAD'], wt) || '').trim() || undefined;
+    if (!cmd) {
+      await postCheck({ agentId, status: 'none', ...(headSha ? { headSha } : {}) });
+      return;
+    }
+    const cleared = clearNonArtifacts(wt);
+    if (cleared.length)
+      warn(
+        `agent ${agentId}: removed ${cleared.length} non-artifact file(s) from ${ARTIFACT_DIR} before the check — ${cleared.slice(0, 5).join(', ')}`
+      );
+    const out = await new Promise((resolve) => {
+      let text = '';
+      let done = false;
+      const finish = (status) => {
+        if (done) return;
+        done = true;
+        // A check the teardown killed never reports (standDownGate.mjs): the
+        // answer stays pending, as `process.exit` left it before the drain.
+        if (workLanesStopped()) return;
+        resolve({ status, text });
+      };
+      // After the teardown no check starts; this promise stays pending.
+      if (workLanesStopped()) return;
+      let child;
+      try {
+        // DETACHED, so the child's pid is its PROCESS GROUP. A check is almost
+        // always a shell that spawns the real runner, and signalling the shell
+        // alone leaves the runner holding the worktree — and this place's
+        // WRITER lock — for as long as it likes.
+        //
+        // AND WITHOUT THE MACHINE CREDENTIAL. The check is the repo's command
+        // run with nobody watching, and it inherited `FLOWVIANT_MACHINE_TOKEN`
+        // — so anything the check executes (a test a turn wrote, a
+        // dependency's postinstall) could read the credential the whole
+        // machine authenticates with. It is `checkEnv()`, the environment the
+        // agent's own turn ran under (`cliEnv`'s rule), NOT `childEnv`'s
+        // allowlist: the agent runs these same tests in its turn, and a check
+        // stripped of `JAVA_HOME`, `DATABASE_URL` or the rest of the operator's
+        // shell would FAIL where the agent's own run passed — a "Check failed"
+        // the product manufactured and then relayed as the project's verdict.
+        // The planted-file path is closed by `clearNonArtifacts` above.
+        child = spawn(cmd, {
+          cwd: wt,
+          shell: true,
+          detached: true,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: checkEnv(),
+        });
+        /**
+         * …AND IT IS TRACKED, so a stop or a takeover takes it with them.
+         *
+         * A check is a full test or build run in the agent's worktree, and it
+         * was the one long-lived child the daemon spawned without telling its
+         * own teardown about it. `shutdownWork` signalled the CLI children and
+         * left this one — so restarting the daemon, or a same-repo takeover,
+         * orphaned a running test suite inside a worktree the sweep may then
+         * try to remove. The ten-minute timer would eventually kill it, but by
+         * then it belongs to no daemon and nothing on any surface names it.
+         *
+         * Registered for a GROUP kill: with `shell: true` the child is
+         * `/bin/sh`, and signalling it leaves the runner it started behind —
+         * which is the process actually holding the worktree. See
+         * `groupKillChildren` for why this one is exempt from the
+         * never-signal-the-group rule.
+         */
+        workChildren.set(child, agentId);
+        groupKillChildren.add(child);
+      } catch (e) {
+        // TEXT BEFORE FINISH: `finish` captures `text` by value into the
+        // resolved object, so assigning afterwards threw the spawn error away
+        // and the surface showed an empty failure.
+        text = String(e?.message || e);
+        finish('failed');
+        return;
+      }
+      /**
+       * The TAIL, not the head: a failing check says why at the end. And
+       * SCRUBBED BEFORE IT IS CUT, which is the order that matters.
+       *
+       * It used to slice first: `text = (text + buf).slice(-CAP)`, with a
+       * single `envScrub` at the very end. `envScrub` replaces EXACT full
+       * values, so any credential straddling either boundary — the rolling
+       * window's, or a chunk's — was already cut in half by the time it was
+       * looked at, matched nothing, and the surviving tail was written to
+       * `agent.checkOutput` and shown to every member of the project. A failing
+       * integration test that dumps its environment is an ordinary way to reach
+       * that, and the partial is enough where the prefix of the key is a
+       * publicly known constant.
+       *
+       * Scrubbing on every chunk fixes both straddles at once: the accumulated
+       * text always holds the previous kept tail plus the whole new chunk, so a
+       * value split across chunks is whole here, and a value near the window
+       * edge is redacted before anything is discarded. Bounded work — the
+       * string is never longer than the cap plus one chunk.
+       *
+       * The one case it cannot cover is a secret LONGER than the cap itself,
+       * which can never sit in the window whole. The final scrub below stays as
+       * the second pass over what actually ships.
+       */
+      const keep = (buf) => {
+        text = envScrub(text + buf.toString()).slice(-CHECK_OUTPUT_CAP);
+      };
+      child.stdout?.on('data', keep);
+      child.stderr?.on('data', keep);
+      const timer = setTimeout(() => {
+        try {
+          // The GROUP, not the child: killing the shell leaves whatever it
+          // started running, which is the thing actually taking ten minutes.
+          process.kill(-child.pid, 'SIGKILL');
+        } catch {
+          try {
+            child.kill('SIGKILL');
+          } catch {
+            /* already gone */
+          }
+        }
+        text += '\n[flowviant] the check ran past ten minutes and was stopped';
+        // RESOLVE HERE TOO. Waiting for 'close' after a kill is the shape that
+        // hangs: if the group is already gone the event never arrives, and this
+        // promise holds the place's writer lock forever.
+        finish('failed');
+      }, CHECK_TIMEOUT_MS);
+      child.on('error', (e) => {
+        clearTimeout(timer);
+        workChildren.delete(child);
+        text += String(e?.message || e);
+        finish('failed');
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        workChildren.delete(child);
+        finish(code === 0 ? 'passed' : 'failed');
+      });
+    });
+    await postCheck({
+      agentId,
+      status: out.status,
+      output: envScrub(out.text).slice(-CHECK_OUTPUT_CAP),
+      ...(headSha ? { headSha } : {}),
+    });
+  };
+
+  return { runCheck };
+}

package/bin/lib/workAgentMerges.mjs

@@ -1,5 +1,5 @@
 /** Agent merge claims, pull-request approval, and branch cleanup. */
-import { ghFirstLine, PR_URL_RE } from './workPullRequests.mjs';
+import { ensureOpenPr, ghFirstLine, ghReady, mergeAndVerifyTip, PR_URL_RE } from './prWorkflow.mjs';
 import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
@@ -7,8 +7,10 @@ import { FLEET_URL, FLEET_TOKEN, USER_AGENT, DAEMON_INSTANCE } from './config.mj
 import { git, gitNet as gitNetIn, baseBranchName, isSafePathSegment } from './git.mjs';
 import { isPublishRef, publishPushArgs, publishDeleteArgs, publishErrorText } from './agentPublish.mjs';
 import { mergeOutward as shipMergeOutward } from './shipMerge.mjs';
+import { gitMergeIn } from './gitMergeIdentity.mjs';
 import { warn } from './ui.mjs';
-import { scrub as envScrub } from './env.mjs';
+import { scrub as envScrub } from './uplinkScrub.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
 
 export function createWorkAgentMerges({
   repoRoot,
@@ -19,12 +21,11 @@ export function createWorkAgentMerges({
   runReviewEntry,
   onRepoChanged,
   landed,
-  state,
+  agentRemoteAt,
+  agentPublished,
 }) {
-  const AGENT_MERGE_CLAIM_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-merge-claim');
-  const AGENT_MERGE_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/agent-merge-done');
-
-  const { agentRemoteAt, agentPublished } = state;
+  const AGENT_MERGE_CLAIM_URL = fleetEndpoint('agent-merge-claim', FLEET_URL);
+  const AGENT_MERGE_DONE_URL = fleetEndpoint('agent-merge-done', FLEET_URL);
 
   // ── THE MERGE ──────────────────────────────────────────────────────────────
   //
@@ -75,31 +76,9 @@ export function createWorkAgentMerges({
     }
   };
 
-  /**
-   * A merge COMMIT needs a git identity and the machine may have none. Prefer
-   * the operator's own config; fall back to the daemon's, the same fallback
-   * ship's merge keeps, so a bare machine does not fail the fold with
-   * "Please tell me who you are".
-   */
-  const gitMerge = (args, cwd) => {
-    let idEnv = null;
-    try {
-      git(['config', 'user.email'], repoRoot);
-    } catch {
-      idEnv = {
-        GIT_AUTHOR_NAME: 'Flowviant',
-        GIT_AUTHOR_EMAIL: 'daemon@flowviant.com',
-        GIT_COMMITTER_NAME: 'Flowviant',
-        GIT_COMMITTER_EMAIL: 'daemon@flowviant.com',
-      };
-    }
-    return execFileSync('git', args, {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-      ...(idEnv ? { env: { ...process.env, ...idEnv } } : {}),
-    });
-  };
+  // A merge COMMIT needs an identity the machine may not have; the probe and
+  // the daemon's fallback live in gitMergeIdentity.mjs.
+  const gitMerge = gitMergeIn(repoRoot);
 
   const runAgentMerge = async (job) => {
     const agentId = String(job.agentId);
@@ -221,34 +200,23 @@ export function createWorkAgentMerges({
        * agent approval failed at the push and came back to review carrying
        * git's refusal, forever.
        *
-       * PUSH, CREATE, MERGE, in that order, and each step's reasoning is the
-       * session PR job's: push first because GitHub merges the REMOTE tip;
-       * `--fill` titles from the branch's own commits so nothing is invented;
-       * `--merge` and never squash, because the cards' receipts are commit
-       * shas and a squash rewrites them off base, orphaning every receipt and
-       * blinding the landed observer's trailer read. Adopt only an OPEN PR:
-       * gh's branch finder falls back to the most recent merged one, and
-       * adopting a dead PR would report success over work that never moves.
+       * PUSH, then the shared GitHub rules (`prWorkflow.mjs`, the same ones
+       * the session PR job runs): adopt only an OPEN PR into this project's
+       * base or create one with `--fill`, merge with `--merge`, and report ok
+       * only once the tip is measured on base. What is the AGENT's stays
+       * here: which ref is the head, the leased push, and every sentence.
        */
       if (job.prMode) {
-        try {
-          // EVERY `gh` CALL IS TIMED OUT. `execFileSync` blocks the daemon's
-          // whole event loop, and this one runs INSIDE the place writer lock —
-          // so a `gh` that hangs (an expired token prompting, a network black
-          // hole, a hung credential helper) stops every turn on the machine,
-          // not merely this merge, and holds the lock while it does.
-          execFileSync('gh', ['auth', 'status'], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            timeout: 20_000,
-          });
-        } catch (e) {
+        // EVERY `gh` CALL IS TIMED OUT (prWorkflow.mjs) — this one runs
+        // INSIDE the place writer lock.
+        const ghDown = ghReady();
+        if (ghDown) {
           await report({
             agentId,
             ok: false,
-            detail:
-              e?.code === 'ENOENT'
-                ? 'this project merges through pull requests, and the GitHub CLI (gh) is not installed on this machine'
-                : `this project merges through pull requests, and gh is not signed in here: ${ghFirstLine(e)}`,
+            detail: ghDown.missing
+              ? 'this project merges through pull requests, and the GitHub CLI (gh) is not installed on this machine'
+              : `this project merges through pull requests, and gh is not signed in here: ${ghDown.error}`,
           });
           return;
         }
@@ -306,102 +274,46 @@ export function createWorkAgentMerges({
           await report({ agentId, ok: false, detail: envScrub(ghFirstLine(e)) });
           return;
         }
-        let prUrl = null;
-        try {
-          const j = JSON.parse(
-            execFileSync('gh', ['pr', 'view', head, '--json', 'url,state,baseRefName'], {
-              cwd: repoRoot,
-              stdio: ['ignore', 'pipe', 'pipe'],
-              timeout: 30_000,
-            }).toString()
-          );
-          if (j?.state === 'OPEN' && typeof j?.url === 'string') {
-            // Adoptable only when it points at the project's own base. A PR
-            // somebody opened by hand against another branch would otherwise
-            // be merged INTO that branch, and the ok settle would claim work
-            // reached base that landed somewhere else entirely. Refused only
-            // on a MEASURED mismatch — an absent field adopts as before.
-            if (typeof j?.baseRefName === 'string' && j.baseRefName !== prBase) {
-              await report({
-                agentId,
-                ok: false,
-                detail: `the open pull request for ${head} targets ${j.baseRefName}, not ${prBase} — retarget or close it, then approve again`,
-              });
-              return;
-            }
-            prUrl = j.url.trim();
-          }
-        } catch {
-          /* no PR for this branch at all — created below */
+        const pr = ensureOpenPr(head, prBase, { cwd: repoRoot });
+        if (pr.wrongBase) {
+          await report({
+            agentId,
+            ok: false,
+            detail: `the open pull request for ${head} targets ${pr.wrongBase}, not ${prBase} — retarget or close it, then approve again`,
+          });
+          return;
         }
-        if (!prUrl) {
-          try {
-            const out = execFileSync(
-              'gh',
-              // baseBranchName, not baseRef: gh 422s on a remote-tracking name.
-              ['pr', 'create', '--head', head, '--base', prBase, '--fill'],
-              { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }
-            )
-              .toString()
-              .trim();
-            prUrl = out.split('\n').filter(Boolean).pop() ?? null;
-          } catch (e) {
-            await report({ agentId, ok: false, detail: ghFirstLine(e) });
-            return;
-          }
+        if (pr.error) {
+          await report({ agentId, ok: false, detail: pr.error });
+          return;
         }
-        try {
-          execFileSync('gh', ['pr', 'merge', head, '--merge'], {
-            cwd: repoRoot,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            timeout: 120_000,
+        const prUrl = pr.url;
+        const linked = prUrl && PR_URL_RE.test(prUrl);
+        const merged = await mergeAndVerifyTip(head, {
+          cwd: repoRoot,
+          tip,
+          baseRef,
+          repoRoot,
+          fetchOrigin: () => gitNet(['fetch', 'origin', '--quiet'], 60_000),
+        });
+        if (merged.error) {
+          await report({
+            agentId,
+            ok: false,
+            detail: linked ? `${merged.error} — the pull request is at ${prUrl}` : merged.error,
           });
-        } catch (e) {
-          const line = ghFirstLine(e);
-          // Already merged is a SUCCESS: a re-offered job, or somebody merged
-          // it in the browser. The observer closes the cards either way.
-          if (!/already merged/i.test(line)) {
-            await report({
-              agentId,
-              ok: false,
-              detail:
-                prUrl && PR_URL_RE.test(prUrl) ? `${line} — the pull request is at ${prUrl}` : line,
-            });
-            return;
-          }
-        }
-        // VERIFY before reporting ok: modern gh exits 0 on an already-MERGED
-        // PR, and on a repo with a merge queue or auto-merge it exits 0 after
-        // ENQUEUEING — in both, "merged" is a claim about the future. The tip
-        // being an ancestor of base is the fact `ok` asserts, and the server
-        // closes every delivered card on this sha the moment it hears it — so
-        // measure it, with one short retry for the fetch racing GitHub's
-        // merge commit. The same guard the session PR path carries.
-        const tipOnBase = () => {
-          try {
-            git(['merge-base', '--is-ancestor', tip, baseRef()], repoRoot);
-            return true;
-          } catch {
-            return false;
-          }
-        };
-        let landedOnBase = false;
-        for (let attempt = 0; attempt < 2 && !landedOnBase; attempt++) {
-          if (attempt > 0) await new Promise((r) => setTimeout(r, 2000));
-          try {
-            gitNet(['fetch', 'origin', '--quiet'], 60_000);
-          } catch {
-            /* offline — the check below answers from what we have */
-          }
-          landedOnBase = tipOnBase();
+          return;
         }
-        if (!landedOnBase) {
+        if (merged.notOnBase) {
+          // gh said yes and base does not have the tip: a merge queue may
+          // still be running it, or an older PR merged. The server closes
+          // every delivered card on this sha the moment it hears ok.
           await report({
             agentId,
             ok: false,
             detail:
               "GitHub accepted the merge, but this branch's tip is not on the base branch — a merge queue may still be running it, or the PR that merged was an older one. Approve again once it lands." +
-              (prUrl && PR_URL_RE.test(prUrl) ? ` The pull request is at ${prUrl}.` : ''),
+              (linked ? ` The pull request is at ${prUrl}.` : ''),
           });
           return;
         }