@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/src/modules/workflow/git/__tests__/node-git-runner.test.ts

@@ -1,9 +1,18 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import fs from 'node:fs/promises';
+import http from 'node:http';
 import os from 'node:os';
 import path from 'node:path';
+import type { AddressInfo } from 'node:net';
 import { NodeGitRunner } from '../node-git-runner.js';
-import { GitRunError, gitCredentials, isGitTimeout } from '../../../../shared/git.contract.js';
+import {
+  GitRunError,
+  gitCredentials,
+  isGitTimeout,
+  type GitCredentials,
+} from '../../../../shared/git.contract.js';
+import { setLogger } from '../../../../shared/logging.js';
+import type { ILogger, LogFields } from '../../../../shared/logger.contract.js';
 
 /**
  * These run REAL git, like the rest of this module's suites: the behaviours
@@ -150,3 +159,223 @@ describe('NodeGitRunner', () => {
     }
   });
 });
+
+/**
+ * A git host that wants a credential, as a real `ls-remote` over HTTP meets
+ * it: a bare repository behind Basic auth, served the dumb way (`info/refs`
+ * as a file), which git falls back to when no smart service answers. Every
+ * refusal below is git's own — "could not read Username" when it had nothing
+ * to offer, "Authentication failed" when what it offered was thrown out.
+ */
+describe('NodeGitRunner: a call the host refuses a credential', () => {
+  let root: string;
+  let clone: string;
+  let server: http.Server;
+  let remote: string;
+  /** The one token the host accepts. */
+  let accepted: string;
+  /** How many times the host was asked, and refused, in order. */
+  let answers: number[];
+  /** No helper from the machine this runs on: the clone's config and the call's `-c` are the whole story. */
+  let env: NodeJS.ProcessEnv;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'git-runner-auth-'));
+    const empty = path.join(root, 'empty-gitconfig');
+    await fs.writeFile(empty, '');
+    env = { GIT_CONFIG_GLOBAL: empty, GIT_CONFIG_NOSYSTEM: '1' };
+    const plain = new NodeGitRunner();
+    const seed = path.join(root, 'seed');
+    await fs.mkdir(seed);
+    await plain.run(seed, ['init', '--initial-branch=main'], { env });
+    await plain.run(seed, ['-c', 'user.name=t', '-c', 'user.email=t@x', 'commit', '--allow-empty', '-m', 'init'], { env });
+    const upstream = path.join(root, 'upstream.git');
+    await plain.run(root, ['clone', '--bare', seed, upstream], { env });
+    await plain.run(upstream, ['update-server-info'], { env });
+    clone = path.join(root, 'clone');
+    await fs.mkdir(clone);
+    await plain.run(clone, ['init', '--initial-branch=main'], { env });
+
+    accepted = 'ghp_good';
+    answers = [];
+    server = http.createServer(async (req, res) => {
+      const expected = `Basic ${Buffer.from(`x-access-token:${accepted}`).toString('base64')}`;
+      if (req.headers.authorization !== expected) {
+        answers.push(401);
+        res.writeHead(401, { 'WWW-Authenticate': 'Basic realm="upstream"' });
+        res.end();
+        return;
+      }
+      answers.push(200);
+      const file = path.join(upstream, new URL(req.url ?? '/', 'http://x').pathname.replace(/^\/upstream\.git\/?/, ''));
+      try {
+        const bytes = await fs.readFile(file);
+        res.writeHead(200, { 'content-type': 'text/plain' });
+        res.end(bytes);
+      } catch {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+    await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+    remote = `http://127.0.0.1:${(server.address() as AddressInfo).port}/upstream.git`;
+    await plain.run(clone, ['remote', 'add', 'origin', remote], { env });
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((r) => server.close(() => r()));
+    await fs.rm(root, { recursive: true, force: true }).catch(() => undefined);
+  });
+
+  /** Credentials whose token a test moves, with a `prepare` that records how it was asked. */
+  function moving(initial: string | null, onRefused: (set: (token: string | null) => void) => void = () => undefined) {
+    let token = initial;
+    const prepare = vi.fn(async (opts?: { refused?: boolean }) => {
+      if (opts?.refused) onRefused((next) => { token = next; });
+    });
+    const credentials: GitCredentials = {
+      username: () => 'x-access-token',
+      token: () => token,
+      prepare,
+    };
+    return { credentials, prepare };
+  }
+  const refusals = (prepare: ReturnType<typeof vi.fn>) => prepare.mock.calls.map((c) => (c[0] as { refused?: boolean } | undefined)?.refused ?? false);
+
+  /** Every line the runner logs during a test. */
+  let logged: string[] = [];
+  let previousLogger: ILogger | undefined;
+  const capturing = (bindings: LogFields = {}): ILogger => {
+    const line = (level: string) => (message: string, fields?: LogFields) =>
+      void logged.push(`${level} ${message} ${JSON.stringify({ ...bindings, ...fields })}`);
+    return { debug: line('debug'), info: line('info'), warn: line('warn'), error: line('error'), child: (m) => capturing({ ...bindings, ...m }) };
+  };
+  beforeEach(() => {
+    logged = [];
+    previousLogger = setLogger(capturing());
+  });
+  afterEach(() => {
+    if (previousLogger) setLogger(previousLogger);
+  });
+
+  it('authenticates a clone whose config carries no helper: the helper rides the call', async () => {
+    const runner = new NodeGitRunner(undefined, gitCredentials('x-access-token', 'ghp_good'));
+    const { stdout } = await runner.run(clone, ['ls-remote', 'origin'], { env });
+    expect(stdout).toContain('refs/heads/main');
+    // Refused once, with nothing offered; then every request carried the token.
+    expect(answers.filter((a) => a === 401)).toHaveLength(1);
+    expect(answers).toContain(200);
+  });
+
+  it('with nothing to offer, insists on a token and runs the command once more', async () => {
+    const { credentials, prepare } = moving(null, (set) => set('ghp_good'));
+    const runner = new NodeGitRunner(undefined, credentials);
+    const { stdout } = await runner.run(clone, ['ls-remote', 'origin'], { env });
+    expect(stdout).toContain('refs/heads/main');
+    // The ordinary renewal before the call, then the one that reports the refusal.
+    expect(refusals(prepare)).toEqual([false, true]);
+    expect(logged.some((l) => l.includes('the token was renewed and the command runs again'))).toBe(true);
+    // The first attempt never got to offer anything (one refusal, and git
+    // gave up); the second was refused once more before it offered the token.
+    expect(answers.filter((a) => a === 401)).toHaveLength(2);
+    expect(answers).toContain(200);
+  });
+
+  it('with a token the host throws out, renews it and runs the command once more', async () => {
+    const { credentials, prepare } = moving('ghp_stale', (set) => set('ghp_good'));
+    const runner = new NodeGitRunner(undefined, credentials);
+    const { stdout } = await runner.run(clone, ['ls-remote', 'origin'], { env });
+    expect(stdout).toContain('refs/heads/main');
+    expect(refusals(prepare)).toEqual([false, true]);
+  });
+
+  it('runs the command again ONCE: a refusal with a token just issued is the answer', async () => {
+    const { credentials, prepare } = moving('ghp_stale', (set) => set('ghp_still_stale'));
+    const runner = new NodeGitRunner(undefined, credentials);
+    const err = await runner.run(clone, ['ls-remote', 'origin'], { env }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(`${(err as GitRunError).stderr}`).toMatch(/Authentication failed/);
+    expect(refusals(prepare).filter(Boolean)).toHaveLength(1);
+    // One attempt with a credential offered is two refusals: git asks bare
+    // first, then with the token. Two attempts, four — and no third.
+    expect(answers).toEqual([401, 401, 401, 401]);
+  });
+
+  it('does not run the command again when no token can be had, and keeps the refusal', async () => {
+    const { credentials, prepare } = moving(null, (set) => set(null));
+    const runner = new NodeGitRunner(undefined, credentials);
+    const err = await runner.run(clone, ['ls-remote', 'origin'], { env }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(`${(err as GitRunError).stderr}`).toMatch(/could not read Username/);
+    expect(refusals(prepare).filter(Boolean)).toHaveLength(1);
+    // One attempt: with nothing to offer, running it again would only repeat the refusal.
+    expect(answers).toEqual([401]);
+    expect(logged.some((l) => l.includes('no other token could be had'))).toBe(true);
+  });
+
+  it('does not run the command again with the SAME token the host just refused', async () => {
+    // A provider that cannot replace it: the fixed token of a token-mode
+    // deployment, whose `prepare` is absent. Running the command again would
+    // only be refused again.
+    const runner = new NodeGitRunner(undefined, gitCredentials('x-access-token', 'ghp_stale'));
+    const err = await runner.run(clone, ['ls-remote', 'origin'], { env }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(`${(err as GitRunError).stderr}`).toMatch(/Authentication failed/);
+    // One attempt: the bare ask, then the token, refused. Nothing after.
+    expect(answers).toEqual([401, 401]);
+    // And one whose renewal hands back what it had.
+    answers = [];
+    const { credentials, prepare } = moving('ghp_stale', (set) => set('ghp_stale'));
+    await expect(new NodeGitRunner(undefined, credentials).run(clone, ['ls-remote', 'origin'], { env })).rejects.toBeInstanceOf(GitRunError);
+    expect(refusals(prepare).filter(Boolean)).toHaveLength(1);
+    expect(answers).toEqual([401, 401]);
+  });
+
+  it('keeps the refusal, and logs why, when the renewal itself fails', async () => {
+    let token: string | null = 'ghp_stale';
+    const credentials: GitCredentials = {
+      username: () => 'x-access-token',
+      token: () => token,
+      prepare: async (opts) => {
+        if (!opts?.refused) return;
+        // What the host refused is dropped, and GitHub will not replace it.
+        token = null;
+        throw new Error('GitHub answered 401 to the app: bad private key');
+      },
+    };
+    const runner = new NodeGitRunner(undefined, credentials);
+    const err = await runner.run(clone, ['ls-remote', 'origin'], { env }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(`${(err as GitRunError).stderr}`).toMatch(/Authentication failed/);
+    expect(answers).toEqual([401, 401]);
+    const why = logged.find((l) => l.includes('no other token could be had'));
+    expect(why).toBeDefined();
+    expect(why).toContain('bad private key');
+  });
+
+  it("leaves a credential the caller laid over the call to the caller: the probe's own token is not renewed", async () => {
+    const { credentials, prepare } = moving('ghp_good', (set) => set('ghp_good'));
+    const runner = new NodeGitRunner(undefined, credentials);
+    const err = await runner
+      .run(clone, ['ls-remote', 'origin'], { env: { ...env, GITHUB_TOKEN: 'ghp_being_checked' } })
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(refusals(prepare).filter(Boolean)).toHaveLength(0);
+    expect(answers).toEqual([401, 401]);
+  });
+
+  it('names the command the caller asked for in a failure, never its own helper', async () => {
+    const runner = new NodeGitRunner(undefined, gitCredentials('x-access-token', 'ghp_stale'));
+    const err = await runner.run(clone, ['ls-remote', 'origin'], { env }).catch((e: unknown) => e);
+    expect((err as Error).message).toContain('git ls-remote failed');
+    expect((err as Error).message).not.toContain('credential.helper');
+    expect(`${(err as GitRunError).stderr}`).not.toContain('credential.helper');
+  });
+
+  it('leaves every other failure alone', async () => {
+    const { credentials, prepare } = moving('ghp_good');
+    const runner = new NodeGitRunner(undefined, credentials);
+    await expect(runner.run(clone, ['checkout', 'no-such-branch'], { env })).rejects.toBeInstanceOf(GitRunError);
+    expect(refusals(prepare).filter(Boolean)).toHaveLength(0);
+  });
+});

package/src/modules/workflow/git/git.service.ts

@@ -35,6 +35,7 @@ import type { KbContext } from '../../../shared/kb-context.js';
 import {
   AppliedChangeMismatchError,
   BranchAuthorshipError,
+  BranchDeleteRefusedError,
   WorkflowDomainError,
   WorkflowValidationError,
   ProtectedBranchError,
@@ -743,12 +744,22 @@ export class GitService implements IGitService {
   //     fresh per-branch workspace gets its backup seeded by the workspace
   //     bootstrap path, not by a branch switch on an existing one.
 
+  /**
+   * Delete a branch, here and on origin. Answers the tip it had — origin's
+   * when origin had it, else the local head's; null when neither existed —
+   * so the caller can say which commit a restore would start from.
+   *
+   * `expectTip`, when given, is the tip the caller's checks were made
+   * against: the remote delete is then leased on it, and a branch that moved
+   * since (a colleague pushed) is refused by the host rather than deleted
+   * with work nobody looked at.
+   */
   async deleteBranch(
     workspaceId: string,
     name: string,
     user: AuthUser,
-    opts: { onlyIfNoRemote?: boolean; systemCleanup?: boolean } = {},
-  ): Promise<void> {
+    opts: { onlyIfNoRemote?: boolean; systemCleanup?: boolean; expectTip?: string } = {},
+  ): Promise<{ lastCommit: string | null }> {
     assertValidBranchName(name);
     if (this.kb.isProtectedBranch(name)) {
       throw new ProtectedBranchError(name, 'deleting a protected branch');
@@ -777,28 +788,33 @@ export class GitService implements IGitService {
             `Branch "${name}" still exists on origin — refusing to auto-prune.`,
           );
         }
-      } else {
-        // Authored-or-admin delete path. The branch's author (per the
-        // `<email-localpart>/...` naming convention — see `isBranchAuthoredBy`)
-        // can always delete their own draft. Admins (per the workspace's
-        // `roles.yaml`) can additionally clean up anyone's branch, including
-        // unprefixed CLI branches like `fix/...` that have no recognisable
-        // author. We detect admin via `canWrite(_, _, 'roles.yaml')` because
-        // that predicate is the existing source of truth for `Admin`-role
-        // membership inside the access model — no separate `isAdmin()` plumbing
-        // needed.
-        // Two authorship conventions: `<localpart>/…` UI drafts, and the
-        // `suggestions/<who>-<id8>/…` namespace the propose flow files its
-        // branches under — a user resetting THEIR OWN suggestion bundle is
-        // deleting their own branch.
-        const isAuthor =
-          isBranchAuthoredBy(name, user.email) ||
-          isOwnSuggestionsBranch(name, { email: user.email, id: user.id });
-        const isAdmin = this.accessControl
-          ? await this.accessControl.canWrite(workspaceId, user.email, 'roles.yaml')
-          : false;
-        if (!isAuthor && !isAdmin) {
-          throw new BranchAuthorshipError(name);
+      } else if (!(await this.mayDeleteBranch(workspaceId, name, user))) {
+        throw new BranchAuthorshipError(name);
+      }
+
+      // Remote delete FIRST. Skip in `onlyIfNoRemote` mode (the contract is
+      // local-only cleanup) and skip when origin has no such branch. Origin
+      // is asked, not this clone's remote-tracking ref: a branch pushed from
+      // another clone since the last fetch has no tracking ref here, and
+      // trusting the cache would delete it locally while it lives on.
+      // A refusal by the host — or a host that cannot be asked — fails the
+      // whole delete: the local branch is untouched, so nothing is
+      // half-deleted and the person can try again. Deleting locally first
+      // would leave a branch that vanished here but lives on the remote —
+      // and, unlike a refused write, a deleted branch has no later push to
+      // reconcile it.
+      let remoteTip: string | null = null;
+      if (!opts.onlyIfNoRemote) {
+        try {
+          remoteTip = await this.originBranchTip(cwd, name);
+          if (remoteTip !== null) {
+            const lease = opts.expectTip ? [`--force-with-lease=refs/heads/${name}:${opts.expectTip}`] : [];
+            await this.git(cwd, ['push', ...lease, 'origin', '--delete', name]);
+          }
+        } catch (err) {
+          const detail = sanitizeError(err);
+          log.warn(`the repository host refused to delete branch "${name}"; leaving it in place:`, { detail });
+          throw new BranchDeleteRefusedError(name, detail);
         }
       }
 
@@ -810,19 +826,91 @@ export class GitService implements IGitService {
       // Skip when no local ref exists — the picker can surface branches that
       // exist only as `refs/remotes/origin/<name>` (the user hasn't worked on
       // them locally), and "discard from origin" must still work for those.
+      let localTip: string | null = null;
       if (await this.refExists(cwd, `refs/heads/${name}`)) {
+        localTip = await this.revParseOrNull(cwd, `refs/heads/${name}`);
         await this.git(cwd, ['branch', '-D', name]);
       }
+      return { lastCommit: remoteTip ?? localTip };
+    });
+  }
 
-      // Remote delete. Skip in `onlyIfNoRemote` mode (the contract is
-      // local-only cleanup) and skip when there's no remote ref to delete.
-      // A push failure here surfaces to the caller — the local ref is
-      // already gone, and we don't try to resurrect it because rolling back
-      // a "merged-into-the-deleted-branch" local commit would be even more
-      // confusing than the half-finished state.
-      if (!opts.onlyIfNoRemote
-        && await this.refExists(cwd, `refs/remotes/origin/${name}`)) {
-        await this.git(cwd, ['push', 'origin', '--delete', name]);
+  /**
+   * The author-or-Admin rule for deleting `name`. The branch's author (per
+   * the `<email-localpart>/...` naming convention — see `isBranchAuthoredBy`)
+   * can always delete their own draft. Admins (per the workspace's
+   * `roles.yaml`) can additionally clean up anyone's branch, including
+   * unprefixed CLI branches like `fix/...` that have no recognisable author.
+   * Admin is detected via `canWrite(_, _, 'roles.yaml')` because that
+   * predicate is the existing source of truth for `Admin`-role membership
+   * inside the access model — no separate `isAdmin()` plumbing needed.
+   *
+   * Two authorship conventions: `<localpart>/…` UI drafts, and the
+   * `suggestions/<who>-<id8>/…` namespace the propose flow files its branches
+   * under — a user resetting THEIR OWN suggestion bundle is deleting their
+   * own branch.
+   */
+  async mayDeleteBranch(workspaceId: string, name: string, user: AuthUser): Promise<boolean> {
+    const isAuthor =
+      isBranchAuthoredBy(name, user.email) ||
+      isOwnSuggestionsBranch(name, { email: user.email, id: user.id });
+    if (isAuthor) return true;
+    return this.accessControl
+      ? await this.accessControl.canWrite(workspaceId, user.email, 'roles.yaml')
+      : false;
+  }
+
+  /**
+   * Where `name` stands in this clone, read from its refs as the last fetch
+   * left them (the caller fetches first): whether it exists on origin or as a
+   * local head, its tip (origin's when it has one), and how many commits on
+   * it — on either ref — are not on `defaultBranch`.
+   *
+   * The default branch is read from origin's ref, falling back to the local
+   * head on a clone whose default was never pushed. A default that resolves
+   * on neither throws: a count against nothing would call every commit
+   * unmerged, or none.
+   */
+  async branchState(
+    workspaceId: string,
+    name: string,
+    defaultBranch: string,
+  ): Promise<{ exists: boolean; lastCommit: string | null; unmergedCommits: number }> {
+    assertValidBranchName(name);
+    assertValidBranchName(defaultBranch);
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      const remote = await this.revParseOrNull(cwd, `refs/remotes/origin/${name}`);
+      const local = await this.revParseOrNull(cwd, `refs/heads/${name}`);
+      if (remote === null && local === null) return { exists: false, lastCommit: null, unmergedCommits: 0 };
+      const base =
+        (await this.revParseOrNull(cwd, `refs/remotes/origin/${defaultBranch}`)) ??
+        (await this.revParseOrNull(cwd, `refs/heads/${defaultBranch}`));
+      if (base === null) {
+        throw new Error(`the default branch "${defaultBranch}" does not resolve in this clone`);
+      }
+      const tips = [remote, local].filter((sha): sha is string => sha !== null);
+      const { stdout } = await this.git(cwd, ['rev-list', '--count', ...tips, `^${base}`]);
+      return { exists: true, lastCommit: remote ?? local, unmergedCommits: Number(stdout.trim()) || 0 };
+    });
+  }
+
+  /**
+   * Whether commit `ancestor` is contained in commit `descendant`. Exit 1 is
+   * git's "no"; anything else — a commit this clone does not have — throws,
+   * so a caller deciding to delete on a yes never gets one by accident.
+   */
+  async isAncestor(workspaceId: string, ancestor: string, descendant: string): Promise<boolean> {
+    const sha = /^[0-9a-f]{4,64}$/i;
+    if (!sha.test(ancestor) || !sha.test(descendant)) throw new Error('isAncestor takes commit ids');
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      try {
+        await this.git(cwd, ['merge-base', '--is-ancestor', ancestor, descendant]);
+        return true;
+      } catch (err) {
+        if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1) return false;
+        throw err;
       }
     });
   }
@@ -1867,7 +1955,21 @@ export class GitService implements IGitService {
    */
   async remoteBranchExists(workspaceId: string, branch: string): Promise<boolean> {
     assertValidBranchName(branch);
-    const cwd = await this.repoDir(workspaceId);
+    return this.originHasBranch(await this.repoDir(workspaceId), branch);
+  }
+
+  /** Origin's tip of `branch`, asked of origin itself; null when it has no such branch. */
+  private async originBranchTip(cwd: string, branch: string): Promise<string | null> {
+    try {
+      const { stdout } = await this.git(cwd, ['ls-remote', '--exit-code', '--heads', 'origin', `refs/heads/${branch}`]);
+      return /^([0-9a-f]+)\s/.exec(stdout)?.[1] ?? null;
+    } catch (err) {
+      if ((err as { exitCode?: number }).exitCode === 2) return null;
+      throw err;
+    }
+  }
+
+  private async originHasBranch(cwd: string, branch: string): Promise<boolean> {
     try {
       await this.git(cwd, ['ls-remote', '--exit-code', '--heads', 'origin', `refs/heads/${branch}`]);
       return true;
@@ -1962,9 +2064,10 @@ export class GitService implements IGitService {
       // commit the clone holds but origin has not seen into cherry-picks of
       // the commits it merged — the merged branch stops being a parent, so
       // "does the published head contain the target's head" answers no
-      // however many times the update runs. Only the change-request update
-      // asks for it; every other pull replays plain saves, where the two
-      // spellings produce the same history.
+      // however many times the update runs. The change-request update and
+      // every push's cooperative recovery ask for it (a merge a refused push
+      // stranded rides along with the branch's next push); with no merge
+      // among the local commits the two spellings produce the same history.
       await this.git(cwd, [
         'rebase',
         '--autostash',
@@ -2081,7 +2184,12 @@ export class GitService implements IGitService {
         }
         throw err;
       }
-      await this.rebaseOntoRemote(cwd, branch, remoteRef);
+      // `preserveMerges` here too: this sync runs on a timer, so it is the
+      // pull most likely to reach a branch while a merge a refused open or
+      // update left local is still waiting for its push. A plain rebase would
+      // flatten that merge before the push ever ran, and the branch would be
+      // "behind" its target again however many times it was updated.
+      await this.rebaseOntoRemote(cwd, branch, remoteRef, { preserveMerges: true });
       this.accessControl?.invalidate(workspaceId);
       const after = await this.revParseOrNull(cwd, 'HEAD');
       const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
@@ -2140,6 +2248,36 @@ export class GitService implements IGitService {
     return this.mutex.run(workspaceId, async () => this.hasUnpushedCommitsAt(await this.repoDir(workspaceId)));
   }
 
+  /**
+   * Whether this clone's HEAD already holds everything origin has on its
+   * branch: a push would then fast-forward origin to HEAD, and no cooperative
+   * pull-rebase would replay origin's commits INTO HEAD first. Asked after a
+   * fetch, about the fetched ref.
+   *
+   * The roles.yaml preservation asks this before pushing a restore it finds
+   * already committed. "HEAD's roles.yaml is the base version" is only worth
+   * publishing when origin ends up AT HEAD — a clone behind origin would have
+   * origin's divergent copy rebased into it on the way, and the push would
+   * land exactly what the restore exists to keep off the base.
+   *
+   * Exit 1 is git's "not an ancestor". Every other failure propagates — a
+   * tracking ref that does not exist, a broken repository — so a probe that
+   * cannot answer fails the guard closed, never open.
+   */
+  async headContainsOrigin(workspaceId: string): Promise<boolean> {
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      const branch = await this.currentBranch(cwd);
+      try {
+        await this.git(cwd, ['merge-base', '--is-ancestor', `refs/remotes/origin/${branch}`, 'HEAD']);
+        return true;
+      } catch (err) {
+        if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1) return false;
+        throw err;
+      }
+    });
+  }
+
   /**
    * `hasUnpushedCommits` without the workspace reservation — for a caller that
    * already holds one (`mergeChangeRequest`, which has to ask inside the same

package/src/modules/workflow/git/node-git-runner.ts

@@ -9,6 +9,24 @@ import {
   type GitRunResult,
   type IGitRunner,
 } from '../../../shared/git.contract.js';
+import { logger } from '../../../shared/logging.js';
+import { credentialHelperValue } from '../../kb-fs/clone-config.js';
+
+const log = logger('git-runner');
+
+/**
+ * What git says when it had no credential to offer, or offered one the host
+ * threw out. Both happen before a byte of the transfer moves, so a command
+ * that failed this way did nothing, and running it again is safe for every
+ * subcommand — fetch, push, ls-remote and clone alike.
+ */
+const REFUSED_CREDENTIAL_RE = /could not read (?:Username|Password) for|terminal prompts disabled|Authentication failed for/i;
+
+/** Whether this failure is git being refused a credential (see {@link REFUSED_CREDENTIAL_RE}). */
+export function isCredentialRefusal(err: unknown): boolean {
+  if (!(err instanceof GitRunError) || err.timedOut) return false;
+  return REFUSED_CREDENTIAL_RE.test(`${err.stderr ?? ''}\n${err.message}`);
+}
 
 /**
  * The deadline every git call carries unless its caller says otherwise.
@@ -147,7 +165,8 @@ interface CommandFailure extends Error {
  * missing git — a string `code`, which is how callers tell "git never ran"
  * from "git said no"), and cuts off a child whose output passes `maxBuffer`.
  */
-function spawnGit(args: string[], options: SpawnOptions & { maxBuffer: number }): {
+/** `shown` is what a failure message names — the caller's arguments, without the runner's own `-c` pairs. */
+function spawnGit(args: string[], shown: string[], options: SpawnOptions & { maxBuffer: number }): {
   promise: Promise<Captured>;
   child: ChildProcess;
 } {
@@ -195,7 +214,7 @@ function spawnGit(args: string[], options: SpawnOptions & { maxBuffer: number })
         resolve({ stdout, stderr });
         return;
       }
-      const error: CommandFailure = new Error(`Command failed: git ${args.join(' ')}\n${stderr.toString()}`);
+      const error: CommandFailure = new Error(`Command failed: git ${shown.join(' ')}\n${stderr.toString()}`);
       error.code = code ?? undefined;
       error.signal = signal;
       error.stdout = stdout;
@@ -243,21 +262,77 @@ export class NodeGitRunner implements IGitRunner {
     return { ...env, ...overrides, ...FIXED_ENV };
   }
 
+  /**
+   * The credential helper, for THIS invocation, when a token is in hand: the
+   * same inline snippet the clones carry in their config, which reads the
+   * token from the child's environment. Given to every call so that a clone
+   * whose config lost its helper — unstamped while the deployment briefly
+   * had no token, created by a build that authenticated only its own clone,
+   * or touched by hand — still authenticates: the server's calls never
+   * depend on what a `.git/config` on disk happens to say. Nothing for a
+   * runner without a token, and nothing when the username cannot be made
+   * into a helper (the stamp refuses the same one, and says so).
+   */
+  private helperArgs(): string[] {
+    if (!this.credentials.token()) return [];
+    try {
+      const helper = credentialHelperValue(this.credentials);
+      return helper ? ['-c', `credential.helper=${helper}`] : [];
+    } catch {
+      return [];
+    }
+  }
+
   run(cwd: string, args: string[], opts: GitRunOptions & { encoding: 'buffer' }): Promise<GitRunResult<Buffer>>;
   run(cwd: string, args: string[], opts?: GitRunOptions & { encoding?: 'utf8' }): Promise<GitRunResult>;
   async run(cwd: string, args: string[], opts: GitRunOptions = {}): Promise<GitRunResult<string | Buffer>> {
-    const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
-    const timers: NodeJS.Timeout[] = [];
-    let timedOut = false;
-
     // A credential that expires is renewed before it is read. Renewing is
     // the credential's own business and its failure is not this call's:
     // plenty of git never leaves the disk, and a call that does is told by
     // the host what the token in hand is worth.
     await this.credentials.prepare?.().catch(() => undefined);
+    try {
+      return await this.attempt(cwd, args, opts);
+    } catch (err) {
+      if (!isCredentialRefusal(err)) throw err;
+      // A credential the CALLER laid over the provider's (the setup probe
+      // checking a token it was given) is the caller's to judge: nothing
+      // here can replace it, so the refusal is the answer.
+      if (opts.env?.[GIT_TOKEN_ENV] !== undefined) throw err;
+      // Refused a credential: the token in hand was dead, or there was none
+      // to hand over. Tell the provider so — it drops what the host refused
+      // and asks for another, past whatever it remembers about a recent
+      // failure — and run the command once more ONLY with a credential that
+      // is not the one just refused. The same token again would only be
+      // refused again, and a renewal that failed leaves none.
+      const subcommand = subcommandOf(args);
+      const refused = this.credentials.token();
+      const renewal = await this.credentials.prepare?.({ refused: true }).then(
+        () => null,
+        (e: unknown) => (e instanceof Error ? e.message : String(e)),
+      );
+      const renewed = this.credentials.token();
+      if (!renewed || renewed === refused) {
+        log.warn(
+          `git ${subcommand} was refused a credential, and no other token could be had to run it again` +
+            (renewal ? `: ${redactGitToken(renewal, refused)}` : ''),
+        );
+        throw err;
+      }
+      log.warn(`git ${subcommand} was refused a credential; the token was renewed and the command runs again`);
+      return await this.attempt(cwd, args, opts);
+    }
+  }
+
+  private async attempt(cwd: string, args: string[], opts: GitRunOptions): Promise<GitRunResult<string | Buffer>> {
+    const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+    const timers: NodeJS.Timeout[] = [];
+    let timedOut = false;
 
     try {
-      const { promise: pending, child } = spawnGit(args, {
+      // The helper rides the invocation, not the error text: a failure
+      // message names the command the caller asked for.
+      const { promise: pending, child } = spawnGit([...this.helperArgs(), ...args], args, {
         cwd,
         env: this.childEnv(opts.env),
         maxBuffer: MAX_OUTPUT_BYTES,