@bevel-software/platform-core-backend 0.12.0 → 0.12.1

package/src/modules/workflow/__tests__/workflow.service.commitFileWhileLocked.test.ts

@@ -220,7 +220,12 @@ describe('WorkflowService.commitFileWhileLocked', () => {
     const change = await svc.commitFileWhileLocked('ws-1', 'feat/x', 'foo.md', USER);
     expect(change).toEqual(CHANGE);
     expect(git.pull).not.toHaveBeenCalled();
+    // Best-effort no longer means invisible: the sync banner goes out ahead of
+    // file-changed, because "the push catches up later" is a hope, not a fact —
+    // an auth failure never catches up, and silently hoping is how a broken
+    // deployment stacked 136 local commits before anyone found out.
     expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'git-sync-failed',
       'file-changed',
     ]);
   });
@@ -243,20 +248,21 @@ describe('WorkflowService.commitFileWhileLocked', () => {
     ]);
   });
 
-  it('best-effort: still emits file-changed when non-fast-forward recovery itself fails', async () => {
+  it('best-effort: still emits file-changed when non-fast-forward recovery itself fails — and NO banner', async () => {
     // Pull rebase failed (conflicts) or retry-push got rejected again.
     // Autosave must NOT throw — the user is mid-edit and would see a
     // baffling error banner for something they didn't even trigger.
-    // The local commit landed; the next checkpoint or final release
-    // will retry the push.
+    // The local commit landed; the release push retries, and if THAT
+    // fails the banner comes from pushWithRecovery. A background
+    // autosave losing a routine two-editors race is not an outage, so
+    // no git-sync-failed here — that stays reserved for auth/host
+    // failures, which never clear themselves (previous test).
     const git = makeGit({ pushBehavior: 'nff', pullBehavior: 'fail' });
     const locks = makeFileLocks(USER.id);
     const svc = makeFacade(git, locks, events);
 
     const change = await svc.commitFileWhileLocked('ws-1', 'feat/x', 'foo.md', USER);
     expect(change).toEqual(CHANGE);
-    // Even though push never succeeded, file-changed still emits so the
-    // local commit is visible to other tabs of the same user.
     expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
       'file-changed',
     ]);

package/src/modules/workflow/__tests__/workflow.service.releaseLock.test.ts

@@ -452,7 +452,12 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     await expect(svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
       PushNeedsAgentResolutionError,
     );
-    expect(emitSpy).not.toHaveBeenCalled();
+    // `file-changed` still does NOT go out — other clients would refetch a
+    // SHA that isn't on origin yet. What DOES go out is the sync banner: the
+    // commit is sitting locally, and someone has to be able to see that.
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'git-sync-failed',
+    ]);
   });
 
   it('recovers from non-fast-forward push via pull --rebase + retry, emits file-changed exactly once', async () => {
@@ -481,10 +486,12 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     );
     expect(git.pull).not.toHaveBeenCalled();
     expect(git.push).toHaveBeenCalledTimes(1);
-    // The commit landed locally but we do NOT emit file-changed — other
-    // clients would refetch a SHA that's not yet on origin. Recovery
-    // (or the next worker pass) emits it when the push actually lands.
-    expect(emitSpy).not.toHaveBeenCalled();
+    // `file-changed` still does NOT go out — other clients would refetch a
+    // SHA that isn't on origin yet. What DOES go out is the sync banner: the
+    // commit is sitting locally, and someone has to be able to see that.
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'git-sync-failed',
+    ]);
   });
 
   it('throws PushNeedsAgentResolutionError when pull --rebase itself fails (textbook conflict case)', async () => {
@@ -500,7 +507,12 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     expect((err as PushNeedsAgentResolutionError).path).toBe('foo.md');
     expect(git.pull).toHaveBeenCalledTimes(1);
     expect(git.push).toHaveBeenCalledTimes(1);
-    expect(emitSpy).not.toHaveBeenCalled();
+    // `file-changed` still does NOT go out — other clients would refetch a
+    // SHA that isn't on origin yet. What DOES go out is the sync banner: the
+    // commit is sitting locally, and someone has to be able to see that.
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'git-sync-failed',
+    ]);
   });
 
   it('throws PushNeedsAgentResolutionError when post-pull retry also fails (origin moved twice)', async () => {
@@ -512,7 +524,160 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     );
     expect(git.pull).toHaveBeenCalledTimes(1);
     expect(git.push).toHaveBeenCalledTimes(2);
-    expect(emitSpy).not.toHaveBeenCalled();
+    // `file-changed` still does NOT go out — other clients would refetch a
+    // SHA that isn't on origin yet. What DOES go out is the sync banner: the
+    // commit is sitting locally, and someone has to be able to see that.
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'git-sync-failed',
+    ]);
+  });
+});
+
+describe('WorkflowService — git-sync visibility events', () => {
+  let events: WorkflowEventBus;
+  let emitSpy: MockInstance;
+
+  beforeEach(() => {
+    events = new WorkflowEventBus();
+    emitSpy = vi.spyOn(events, 'emit');
+  });
+
+  function kinds(): string[] {
+    return emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind);
+  }
+
+  it('stays silent while pushes succeed — the healthy path must not broadcast', async () => {
+    // A push runs on every save. If the healthy case announced itself, every
+    // keystroke-driven autosave would fan an event out to every session on
+    // the branch to say that nothing happened.
+    const svc = makeFacade(makeGit(), makeFileLocks(USER.id), makePending(), events);
+
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(kinds()).toEqual(['file-changed', 'file-changed']);
+  });
+
+  it('carries the branch and a sanitised reason for the banner', async () => {
+    const svc = makeFacade(
+      makeGit({ pushBehavior: 'auth-fail' }),
+      makeFileLocks(USER.id),
+      makePending(),
+      events,
+    );
+
+    await expect(svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+    expect(emitSpy.mock.calls[0][0]).toMatchObject({
+      kind: 'git-sync-failed',
+      workspaceId: 'ws-1',
+      branch: 'feat/x',
+    });
+    expect((emitSpy.mock.calls[0][0] as { reason: string }).reason).toContain(
+      'Authentication failed',
+    );
+  });
+
+  it('re-announces on every failure, so a session joining mid-outage still learns of it', async () => {
+    // The banner has no other way in: a client that connects after the first
+    // failure missed the only event that would have told it.
+    // `pushAfterPullBehavior` is what the shared mock serves from the second
+    // push onward, so failing it too is how one broken remote is simulated
+    // across repeated saves rather than just the first.
+    const svc = makeFacade(
+      makeGit({ pushBehavior: 'auth-fail', pushAfterPullBehavior: 'fail' }),
+      makeFileLocks(USER.id),
+      makePending(),
+      events,
+    );
+
+    for (let i = 0; i < 2; i += 1) {
+      await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER).catch(() => undefined);
+    }
+
+    expect(kinds()).toEqual(['git-sync-failed', 'git-sync-failed']);
+  });
+
+  it('emits git-sync-recovered once when a push finally lands, then goes quiet again', async () => {
+    const failing = makeGit({ pushBehavior: 'auth-fail' });
+    const svc = makeFacade(failing, makeFileLocks(USER.id), makePending(), events);
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER).catch(() => undefined);
+    expect(kinds()).toEqual(['git-sync-failed']);
+
+    // Same service instance — the failing/healthy state is per-workspace and
+    // lives on it, so recovery has to be observed through the same object.
+    const healthy = makeGit();
+    const recovered = makeFacade(healthy, makeFileLocks(USER.id), makePending(), events);
+    Object.assign(svc as unknown as Record<string, unknown>, {
+      git: (recovered as unknown as { git: GitService }).git,
+    });
+
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    // Recovery announced exactly once; the second healthy push says nothing.
+    expect(kinds()).toEqual([
+      'git-sync-failed',
+      'git-sync-recovered',
+      'file-changed',
+      'file-changed',
+    ]);
+  });
+
+  it('clears a failure recorded under the encoded id when the decoded id recovers', async () => {
+    // HTTP routes hand the service Express-decoded ids (user/feat); internal
+    // callers hand the encoded form (user%2Ffeat). The tracker must treat
+    // them as one workspace, or a failure recorded by one caller can never
+    // be cleared by the other's success and the banner sticks forever.
+    const svc = makeFacade(
+      makeGit({ pushBehavior: 'auth-fail', pushAfterPullBehavior: 'fail' }),
+      makeFileLocks(USER.id),
+      makePending(),
+      events,
+    );
+    await svc.runPendingCommit('user%2Ffeat', 'user/feat', 'foo.md', USER).catch(() => undefined);
+
+    Object.assign(svc as unknown as Record<string, unknown>, { git: makeGit() });
+    await svc.runPendingCommit('user/feat', 'user/feat', 'foo.md', USER);
+
+    const sync = emitSpy.mock.calls
+      .map((c) => c[0] as { kind: string; workspaceId: string })
+      .filter((e) => e.kind.startsWith('git-sync'));
+    // Both events carry the canonical (decoded) id, and the recovery fired.
+    expect(sync).toEqual([
+      expect.objectContaining({ kind: 'git-sync-failed', workspaceId: 'user/feat' }),
+      expect.objectContaining({ kind: 'git-sync-recovered', workspaceId: 'user/feat' }),
+    ]);
+  });
+
+  it('tracks workspaces independently — one recovering neither clears nor suppresses another', async () => {
+    const failingGit = () => makeGit({ pushBehavior: 'auth-fail', pushAfterPullBehavior: 'fail' });
+    const svc = makeFacade(failingGit(), makeFileLocks(USER.id), makePending(), events);
+
+    // Both workspaces broken.
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER).catch(() => undefined);
+    await svc.runPendingCommit('ws-2', 'feat/y', 'bar.md', USER).catch(() => undefined);
+
+    // ws-1 recovers; ws-2 is still broken and must (a) not be cleared by
+    // ws-1's recovery and (b) still announce its own next failure.
+    Object.assign(svc as unknown as Record<string, unknown>, { git: makeGit() });
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+    Object.assign(svc as unknown as Record<string, unknown>, { git: failingGit() });
+    await svc.runPendingCommit('ws-2', 'feat/y', 'bar.md', USER).catch(() => undefined);
+
+    expect(
+      emitSpy.mock.calls.map((c) => [
+        (c[0] as { kind: string }).kind,
+        (c[0] as { workspaceId: string }).workspaceId,
+      ]),
+    ).toEqual([
+      ['git-sync-failed', 'ws-1'],
+      ['git-sync-failed', 'ws-2'],
+      ['git-sync-recovered', 'ws-1'],
+      ['file-changed', 'ws-1'],
+      ['git-sync-failed', 'ws-2'],
+    ]);
   });
 });
 

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

@@ -49,11 +49,12 @@ import type { GitService } from './git/git.service.js';
 import type { PullRequestService } from './git/pull-request.service.js';
 import type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { FileLockService } from './file-lock.service.js';
 import { PendingCommitsService } from './pending-commits.service.js';
 import type { WorkflowEventBus } from './event-bus.js';
+import { sanitizeError } from './sanitize-error.js';
 import type { FileChangeNotifier } from '../kb-fs/file-change-notifier.js';
 import { WorkflowHooks } from './workflow-hooks.js';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
@@ -355,7 +356,7 @@ export class WorkflowService implements IWorkflowService {
   // to discard.
 
   shareCurrentBranch(workspaceId: string, user: AuthUser): Promise<void> {
-    return this.git.push(workspaceId, user);
+    return this.trackedPush(workspaceId, user);
   }
 
   refreshRemotes(workspaceId: string): Promise<void> {
@@ -680,6 +681,7 @@ export class WorkflowService implements IWorkflowService {
     if (change) {
       try {
         await this.git.push(workspaceId, user);
+        this.noteGitSyncOk(workspaceId, branch);
       } catch (err) {
         // Non-fast-forward recovery on the autosave path: try the
         // cooperative `pull --rebase` + retry once. Autosave is
@@ -695,12 +697,15 @@ export class WorkflowService implements IWorkflowService {
         const detail = err instanceof Error ? err.message : String(err);
         const looksLikeNonFastForward = /non-fast-forward|rejected|fetch first|updates were rejected/i.test(detail);
         let recovered = false;
+        let recoveryError: unknown = null;
         if (looksLikeNonFastForward) {
           try {
             await this.git.pull(workspaceId);
             await this.git.push(workspaceId, user);
             recovered = true;
+            this.noteGitSyncOk(workspaceId, branch);
           } catch (recoveryErr) {
+            recoveryError = recoveryErr;
             console.warn(
               '[workflow] autosave cooperative recovery (pull-rebase) failed; leaving the unpushed commit for the next save / releaseLock to surface:',
               recoveryErr instanceof Error ? recoveryErr.message : recoveryErr,
@@ -708,6 +713,20 @@ export class WorkflowService implements IWorkflowService {
           }
         }
         if (!recovered) {
+          // Still best-effort — we don't fail the autosave. What gets the
+          // BANNER is only the class that cannot clear itself: auth or host
+          // failures, which no later attempt fixes. A non-fast-forward here —
+          // recovery attempted or not — is the routine two-editors race the
+          // surrounding flow already handles: the release push retries it,
+          // and if THAT fails the user gets the typed agent hand-off plus the
+          // banner from `pushWithRecovery`. Bannering it from a background
+          // autosave would tell an author mid-keystroke that the deployment
+          // is broken over a race that usually settles on its own — while an
+          // auth failure swallowed into a log line is how a broken deployment
+          // once stacked 136 local commits before anyone found out.
+          if (!looksLikeNonFastForward) {
+            this.noteGitSyncFailed(workspaceId, branch, recoveryError ?? err);
+          }
           console.warn(
             '[workflow] push after autosave commit failed (commit landed locally):',
             detail,
@@ -896,6 +915,87 @@ export class WorkflowService implements IWorkflowService {
     this.fileChanges?.emit({ workspaceId, branch, paths: [targetPath], byUser: user });
   }
 
+  /**
+   * Workspaces whose last push failed. Purely so the recovery event fires on
+   * the transition back to healthy instead of on every subsequent save — a
+   * push runs on every write, and the healthy case must stay silent.
+   *
+   * Process-local and deliberately not persisted: a restart clears it, and the
+   * worst that costs is one redundant `git-sync-recovered` on a workspace that
+   * was already fine, which clients treat as a no-op.
+   */
+  private readonly gitSyncFailing = new Set<string>();
+
+  /**
+   * Announce that a push landed. Emits only when this workspace was previously
+   * failing — see `gitSyncFailing`.
+   */
+  private noteGitSyncOk(workspaceId: string, branch: string): void {
+    // Callers hand this both spellings of a workspace id — HTTP routes pass
+    // the Express-decoded `user/feat`, internal callers (the pending-commits
+    // worker, the agent filesystem) the encoded `user%2Ffeat`. Keyed raw, a
+    // failure recorded by one caller could never be cleared by the other's
+    // success, and the banner would stick. Canonicalize the key AND the
+    // emitted id so every consumer sees one spelling.
+    const id = branchForWorkspaceId(workspaceId);
+    if (!this.gitSyncFailing.delete(id)) return;
+    console.log(`[workflow] git sync recovered for workspace=${id} branch=${branch}`);
+    this.events?.emit({ kind: 'git-sync-recovered', workspaceId: id, branch });
+  }
+
+  /**
+   * Announce that a commit is sitting locally because its push failed.
+   *
+   * This is the visibility half of the failure paths below; it never changes
+   * what they DO. The commit is already safe on disk and the retry / hand-off
+   * machinery is unaffected — all this adds is that someone finds out, rather
+   * than the deployment looking healthy while nothing reaches the remote.
+   */
+  private noteGitSyncFailed(workspaceId: string, branch: string, err: unknown): void {
+    // Same canonicalization as `noteGitSyncOk` — the pair must agree on keys.
+    const id = branchForWorkspaceId(workspaceId);
+    this.gitSyncFailing.add(id);
+    this.events?.emit({
+      kind: 'git-sync-failed',
+      workspaceId: id,
+      branch,
+      // Git stderr can quote a credentialed URL; the banner is user-facing and
+      // the string also lands in client logs, so sanitize before it leaves.
+      reason: sanitizeError(err),
+    });
+  }
+
+  /**
+   * A bare push wrapped in the sync tracker: a failure raises the banner, a
+   * success clears it. For the workflow paths that push directly — sharing a
+   * branch, publishing a CR's source, update-from-base, the decline revert,
+   * the roles.yaml restore — rather than through `pushWithRecovery`'s
+   * cooperative ladder. Behaviour is otherwise unchanged: the error still
+   * propagates to the caller exactly as the bare push's did. Without this,
+   * those pushes could fail invisibly (no banner) and, worse, a successful
+   * share could not CLEAR a banner an earlier save had raised.
+   *
+   * The branch is derived from the workspace id (they are the same string,
+   * URL-encoding aside) so call sites cannot pass a mismatched pair.
+   */
+  private async trackedPush(
+    workspaceId: string,
+    user: AuthUser,
+    opts?: { systemAuthorized?: boolean },
+  ): Promise<void> {
+    const branch = branchForWorkspaceId(workspaceId);
+    try {
+      // Preserve the exact call shape of the bare pushes this replaces — an
+      // explicit `undefined` third argument is a different call signature to
+      // every spy that asserts on it.
+      await (opts ? this.git.push(workspaceId, user, opts) : this.git.push(workspaceId, user));
+      this.noteGitSyncOk(workspaceId, branch);
+    } catch (err) {
+      this.noteGitSyncFailed(workspaceId, branch, err);
+      throw err;
+    }
+  }
+
   /**
    * Shared implementation of "push, and on non-fast-forward try a
    * cooperative pull-rebase + retry, then hand off to the agent if that
@@ -911,20 +1011,24 @@ export class WorkflowService implements IWorkflowService {
   ): Promise<void> {
     try {
       await this.git.push(workspaceId, user, opts);
+      this.noteGitSyncOk(workspaceId, branch);
     } catch (firstPushErr) {
       const firstDetail = firstPushErr instanceof Error ? firstPushErr.message : String(firstPushErr);
       const looksLikeNonFastForward = /non-fast-forward|rejected|fetch first|updates were rejected/i.test(firstDetail);
       let recovered = false;
       let recoveryDetail = '(cooperative path not attempted)';
+      let recoveryError: unknown = null;
       if (looksLikeNonFastForward) {
         try {
           await this.git.pull(workspaceId);
           await this.git.push(workspaceId, user, opts);
           recovered = true;
+          this.noteGitSyncOk(workspaceId, branch);
           console.log(
             `[workflow] non-fast-forward push recovered via pull --rebase for workspace=${workspaceId} branch=${branch} path=${targetPath}`,
           );
         } catch (recoveryErr) {
+          recoveryError = recoveryErr;
           recoveryDetail = recoveryErr instanceof Error ? recoveryErr.message : String(recoveryErr);
           console.warn(
             `[workflow] cooperative recovery (pull-rebase) failed for workspace=${workspaceId} user=${user.id}; handing off to agent:`,
@@ -933,6 +1037,14 @@ export class WorkflowService implements IWorkflowService {
         }
       }
       if (!recovered) {
+        // Banner first, then the typed throw. The throw only reaches a UI that
+        // is still mounted and listening — the release fired as an editor
+        // unmounts has nowhere to surface it — whereas the event reaches every
+        // session on the branch regardless of what triggered the push.
+        // When recovery RAN, its error is the current state of the world (the
+        // first rejection may be a stale non-fast-forward the pull already
+        // cured); when it was skipped, the first error is all there is.
+        this.noteGitSyncFailed(workspaceId, branch, recoveryError ?? firstPushErr);
         console.warn(
           `[workflow] push failed for workspace=${workspaceId} user=${user.id}; throwing PushNeedsAgentResolutionError so the frontend can hand off to the agent:`,
           firstDetail,
@@ -1214,7 +1326,7 @@ export class WorkflowService implements IWorkflowService {
     // Push the source — `gh pr create` against an unpushed branch returns
     // "head branch does not exist on remote". Push *after* the auto-merge
     // so the remote sees the merge commit too.
-    await this.git.push(workspaceId, user);
+    await this.trackedPush(workspaceId, user);
 
     const workspacePath = await this.workspaceService.getWorkspacePath(workspaceId);
     const cwd = path.join(workspacePath, this.kbDirName);
@@ -1367,7 +1479,7 @@ export class WorkflowService implements IWorkflowService {
     // If a new merge commit landed, push so the CR picks it up. When
     // already up to date there's nothing to share — short-circuit the push.
     if (!outcome.alreadyUpToDate) {
-      await this.git.push(workspaceId, user);
+      await this.trackedPush(workspaceId, user);
     }
     this.prs.invalidateDetailCache(number);
     const refreshed = await this.prs.getPrDetail(number, {
@@ -1556,7 +1668,7 @@ export class WorkflowService implements IWorkflowService {
         `Revert ${repoRelPath} (declined in change request #${number})`,
         true, // skipValidator — this restores an already-validated base version
       );
-      await this.git.push(ws.id, user);
+      await this.trackedPush(ws.id, user);
     } finally {
       // Committed inline — drop the lock row directly rather than enqueueing
       // a duplicate commit through releaseLock.
@@ -2105,7 +2217,7 @@ export class WorkflowService implements IWorkflowService {
             'roles.yaml restore produced no commit while origin still diverges from base — source workspace out of sync; refusing to merge',
           );
         }
-        await this.git.push(ws.id, user);
+        await this.trackedPush(ws.id, user);
         this.accessControl.invalidate(ws.id);
         return true;
       } finally {

package/src/modules/workspace/__tests__/workspace.service.test.ts

@@ -454,7 +454,7 @@ describe('WorkspaceService.sweepOrphanedWorkspaces', () => {
 
   beforeEach(async () => {
     root = await mkTmpRoot();
-    // The fake `.git` in seedBranchWorkspace makes normalizeCloneTracking's
+    // The fake `.git` in seedBranchWorkspace makes normalizeCloneConfig's
     // git calls fail; that path only warns, which is noise here.
     vi.spyOn(console, 'warn').mockImplementation(() => {});
   });

package/src/modules/workspace/startup/__tests__/kb-startup-runner.test.ts

@@ -5,6 +5,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { KbStartupRunner } from '../kb-startup-runner.js';
+import { WorkspaceService } from '../../workspace.service.js';
 import { redactSecret } from '../kb-git.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
@@ -493,3 +494,143 @@ describe('redactSecret', () => {
     expect(redactSecret('https://example.com/kb.git')).toBe('https://example.com/kb.git');
   });
 });
+
+describe('KbStartupRunner credentials', () => {
+  // The phase clones the default branch into the very directory
+  // `WorkspaceService` adopts, and `GitService.push` later runs a bare
+  // `git push` from it. Position of the credential config is what decides
+  // whether that works: `git -c … clone` authenticates the clone and leaves
+  // the repo with nothing, so every later push prompts for a username, finds
+  // no tty, and dies — commits pile up locally and reach the remote never.
+  // Only real git tells the two spellings apart, so this drives real git.
+  const ORIGINAL = process.env.GITHUB_TOKEN;
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.GITHUB_TOKEN;
+    else process.env.GITHUB_TOKEN = ORIGINAL;
+  });
+
+
+  /** Run the phase far enough to put the default branch's clone on disk. */
+  async function materializeDefaultBranchClone(): Promise<string> {
+    let repoDir = '';
+    await makeRunner([
+      step('touch', async (ctx) => {
+        repoDir = await (await ctx.defaultBranch()).repoDir();
+        return { outcome: 'ok' };
+      }),
+    ]).runAll();
+    expect(repoDir).toBe(path.join(workspacesRoot, DEFAULT_BRANCH, 'knowledge-base'));
+    return repoDir;
+  }
+
+  it('leaves the boot clone able to authenticate a push of its own', async () => {
+    process.env.GITHUB_TOKEN = 'ghp_boot';
+    await populatedUpstream();
+    // The branch handle clones lazily, so a step has to actually reach for the
+    // repo before there is anything on disk to inspect.
+    const repo = await materializeDefaultBranchClone();
+    const helper = (await git(repo, ['config', '--local', '--get', 'credential.helper'])).trim();
+    expect(helper).toContain('username=x-access-token');
+    // The literal, not the value — the helper resolves it per invocation, so
+    // the secret never lands in a config file we don't control the lifetime of.
+    expect(helper).toContain('password=$GITHUB_TOKEN');
+    expect(helper).not.toContain('ghp_boot');
+
+    // Exactly one value: a re-stamp must collapse, never accumulate, or git
+    // errors with "cannot overwrite multiple values".
+    const all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
+    expect(all.split('\n')).toHaveLength(1);
+  });
+
+  it('adopting an existing clone collapses an accumulated helper back to one value', async () => {
+    // The boot-time assertion above sees a FRESH clone, which only ever has
+    // one value by construction. The collapse guarantee lives in the adoption
+    // path (`--replace-all`), so drift a second value in out of band and let
+    // WorkspaceService adopt the clone — that is the code the guarantee is
+    // about.
+    process.env.GITHUB_TOKEN = 'ghp_boot';
+    await populatedUpstream();
+    const repo = await materializeDefaultBranchClone();
+    // App-shaped drift: a second stamp of OURS with a stale username — the
+    // realistic accumulation (an operator's own helper is a different case,
+    // covered below, and must NOT be collapsed).
+    await git(repo, ['config', '--add', 'credential.helper',
+      '!f() { echo "username=stale-user"; echo "password=$GITHUB_TOKEN"; }; f']);
+
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    await ws.getOrCreateForBranch(DEFAULT_BRANCH);
+
+    const all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
+    expect(all.split('\n')).toHaveLength(1);
+    expect(all).toContain('username=x-access-token');
+    expect(all).not.toContain('stale-user');
+  });
+
+  it('an operator-configured helper survives both the stamp and the token-removal unset', async () => {
+    // git chains every configured helper, so an operator's clone-local
+    // `cache`/`store`/custom helper coexists with ours — and losing it on a
+    // token change would break the very fallback auth they set up.
+    process.env.GITHUB_TOKEN = 'ghp_boot';
+    await populatedUpstream();
+    const repo = await materializeDefaultBranchClone();
+    await git(repo, ['config', '--add', 'credential.helper', 'cache --timeout=300']);
+
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    await ws.getOrCreateForBranch(DEFAULT_BRANCH); // stamp with token
+    let all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
+    expect(all).toContain('cache --timeout=300');
+    expect(all).toContain('password=$GITHUB_TOKEN');
+
+    delete process.env.GITHUB_TOKEN;
+    const ws2 = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    await ws2.getOrCreateForBranch(DEFAULT_BRANCH); // unset OUR helper only
+    all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
+    expect(all).toContain('cache --timeout=300');
+    expect(all).not.toContain('password=$GITHUB_TOKEN');
+  });
+
+  it('adopting a clone after the token was removed unsets the stale helper', async () => {
+    // A deployment that lost its token must not keep a clone-local helper
+    // answering with an empty password — it would shadow whatever fallback
+    // auth the operator switched to.
+    process.env.GITHUB_TOKEN = 'ghp_boot';
+    await populatedUpstream();
+    const repo = await materializeDefaultBranchClone(); // stamped
+    delete process.env.GITHUB_TOKEN;
+
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    await ws.getOrCreateForBranch(DEFAULT_BRANCH);
+
+    await expect(git(repo, ['config', '--local', '--get', 'credential.helper']))
+      .rejects.toMatchObject({ code: 1 });
+  });
+
+  it('a token added after the branch is cached reaches the clone without a restart', async () => {
+    // The rotation gap: the setup screen can supply a token AFTER a branch
+    // was first opened, and the cached fast path returns before the adoption
+    // re-stamp. The fingerprint check must catch the change there.
+    delete process.env.GITHUB_TOKEN;
+    await populatedUpstream();
+    const repo = await materializeDefaultBranchClone(); // no helper
+
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    await ws.getOrCreateForBranch(DEFAULT_BRANCH); // adopt, tokenless
+    process.env.GITHUB_TOKEN = 'ghp_late';
+    await ws.getOrCreateForBranch(DEFAULT_BRANCH); // cached fast path
+
+    const helper = (await git(repo, ['config', '--local', '--get', 'credential.helper'])).trim();
+    expect(helper).toContain('password=$GITHUB_TOKEN');
+    expect(helper).not.toContain('ghp_late');
+  });
+
+  it('clones without a helper when the deployment has no token — an open remote still boots', async () => {
+    delete process.env.GITHUB_TOKEN;
+    await populatedUpstream();
+    const repo = await materializeDefaultBranchClone();
+    // `--get` exits 1 when the key is unset. Assert on that exit code rather
+    // than on "it threw": a missing clone directory throws too, which would
+    // pass this test while proving nothing.
+    await expect(git(repo, ['config', '--local', '--get', 'credential.helper']))
+      .rejects.toMatchObject({ code: 1 });
+  });
+});