@bevel-software/platform-core-backend 0.20.0 → 0.21.0

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -2,7 +2,8 @@ import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
@@ -24,6 +25,8 @@ import { registerWorkspaceTools } from '../workspace.tools.js';
  * for it.
  */
 const KB_DIR = 'knowledge-base';
+/** The context the tools read; a case applies a deployment's own names to it. */
+const kb = testKbContext({ kbDirName: KB_DIR });
 
 /** Every workspace tool's description, keyed by name, under the layout in effect. */
 async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promise<Map<string, string>> {
@@ -37,11 +40,11 @@ async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promis
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
     new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
     {} as unknown as IAccessControl,
-    KB_DIR,
+    kb,
     {
       service: {} as never,
       enabled: false,
-      kbDirName: KB_DIR,
+      kb,
       recoveryBotEmail: 'recovery-bot@bevel.local',
       hooks: new WorkflowHooks(),
     },
@@ -57,7 +60,7 @@ async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
   return new Map(tools.map((t) => [t.name, t.description ?? '']));
 }
 
-afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
+afterEach(() => kb.applyLayout({ ...DEFAULT_KB_LAYOUT }));
 
 describe('the conventions note every workspace tool carries', () => {
   it('names AGENTS.md, and CLAUDE.md beside it, under the default name', async () => {
@@ -71,7 +74,7 @@ describe('the conventions note every workspace tool carries', () => {
   });
 
   it('names the configured file first and the organisation\'s own AGENTS.md second', async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const byName = await descriptions();
     const note = byName.get('grep') ?? '';
     expect(note).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
@@ -83,7 +86,7 @@ describe('the conventions note every workspace tool carries', () => {
   });
 
   it('describes the platform files under the configured name, and no longer under AGENTS.md', async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const byName = await descriptions();
     const stat = byName.get('file_stat') ?? '';
     expect(stat).toContain('`access.md`, `roles.yaml`, `.bevelignore`, `HEXIS.md`');
@@ -117,7 +120,7 @@ describe('the conventions note every workspace tool carries', () => {
     const atMount = await descriptions(registry);
     expect(atMount.get('grep')).toContain('read `AGENTS.md` at the KB root');
 
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
 
     const now = await listed(registry);
     expect(now.get('grep')).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');

package/src/modules/workspace/__tests__/workspace.tools.branch-errors.test.ts

@@ -6,6 +6,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -109,7 +110,7 @@ describe('workspace tools — a branch that cannot be opened', () => {
     workspaces = new WorkspaceService(
       workspacesRoot,
       opts.repoUrl === 'unreachable' ? join(root, 'no-such-repo.git') : upstream,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       new NodeFs(),
     );
 
@@ -138,11 +139,11 @@ describe('workspace tools — a branch that cannot be opened', () => {
       new SpillStore(spillRoot),
       new DocExtractService(docCacheDir),
       allowAll,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       {
         service: {} as never,
         enabled: false,
-        kbDirName: KB_DIR,
+        kb: testKbContext({ kbDirName: KB_DIR }),
         recoveryBotEmail: 'recovery-bot@bevel.local',
         hooks: new WorkflowHooks(),
       },

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

@@ -7,6 +7,7 @@ import { promisify } from 'node:util';
 import AdmZip from 'adm-zip';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -218,10 +219,10 @@ async function start(
   const app = express();
   app.use(express.json());
   const router = express.Router();
-  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, KB_DIR, {
+  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, testKbContext({ kbDirName: KB_DIR }), {
     service: {} as never,
     enabled: false, // these tests predate and don't exercise the ontology boundary
-    kbDirName: KB_DIR,
+    kb: testKbContext({ kbDirName: KB_DIR }),
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
   }, writePolicy, {} as never /* sessionSink — start_session not exercised here */);
@@ -1831,8 +1832,8 @@ describe('start_session', () => {
     const router = express.Router();
     registerWorkspaceTools(
       registry, router, auth, toolHandler,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       sink ?? fakeSessionSink,
     );
@@ -1956,8 +1957,8 @@ describe('start_session', () => {
     const noopAuth: express.RequestHandler = (_req, _res, next) => next();
     registerWorkspaceTools(
       registry, router, noopAuth, (() => () => {}) as never,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );
@@ -1998,8 +1999,8 @@ describe('branch is a required parameter in the tool contract', () => {
       new SpillStore(join(tmpdir(), 'bevel-test-spills')),
       new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
       allowAll,
-      KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );

package/src/modules/workspace/__tests__/write-denial.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { writeDenial } from '../write-denial.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
@@ -34,7 +35,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
       eligibleUsers: [],
       targetKind: 'dir',
     });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(judge).toHaveBeenCalledWith(
       'target-company-state',
       'alice@example.com',
@@ -48,7 +49,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('a refusal that says nothing about its kind is judged as a file', async () => {
     const { gate, judge } = gateThat({ allowed: false, unreadable: 'KnowledgeBase' });
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/loose.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(judge).toHaveBeenCalledWith(expect.any(String), 'alice@example.com', `${KB}/KnowledgeBase/loose.md`, 'file');
     expect(out.details).toMatchObject({
       kind: 'write-denied',
@@ -60,7 +61,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('without a gate the read verdict alone decides, as before', async () => {
     const accessControl = { canRead: vi.fn(async () => true) } as unknown as IAccessControl;
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, accessControl, KB);
+    const out = await writeDenial(err, INPUT, accessControl, testKbContext({ kbDirName: KB }));
     expect(accessControl.canRead).toHaveBeenCalledWith('target-company-state', 'alice@example.com', 'KnowledgeBase/Sales/deal.md');
     expect(out.details).toMatchObject({ kind: 'write-denied', canPropose: true });
   });
@@ -68,7 +69,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('a gate that cannot answer refuses to offer the route', async () => {
     const gate: IChangeReadGate = { judge: vi.fn(async () => { throw new Error('git down'); }), assertMayChange: vi.fn() };
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(out.details).toMatchObject({ canPropose: false });
     expect(out.details?.cannotProposeReason).toContain('could not be determined');
   });

package/src/modules/workspace/session-ontology.gate.ts

@@ -22,6 +22,7 @@
  */
 
 import { ontologyOf } from '../../shared/kb-layout.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { JsonSchema } from '../tool-registry/tool.contract.js';
 import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
 import type { ISessionOntologyService } from '../workflow/session-ontology.service.js';
@@ -75,7 +76,8 @@ export class MissingSessionError extends ToolError {
 export interface SessionOntologyGate {
   service: ISessionOntologyService;
   enabled: boolean;
-  kbDirName: string;
+  /** The checkout folder and the layout a path is classified under. */
+  kb: Pick<KbContext, 'kbDirName' | 'layout'>;
   /** Lowercased email of the recovery/merge bot, which is exempt. */
   recoveryBotEmail: string;
   /**
@@ -103,7 +105,7 @@ function isAgentSource(ctx: ToolContext): boolean {
 function resolveGatedSession(gate: SessionOntologyGate, ctx: ToolContext, wsPath: string): string | 'skip' {
   if (!gate.enabled) return 'skip';
   // Neutral paths never pin/record/block — skip before any identity work.
-  if (ontologyOf(wsPath, gate.kbDirName) === null) return 'skip';
+  if (ontologyOf(wsPath, gate.kb.layout, gate.kb.kbDirName) === null) return 'skip';
   // Humans (UI routes) and browser-JWT callers never hit these tools; only
   // agent tool calls are gated.
   if (!isAgentSource(ctx)) return 'skip';
@@ -125,7 +127,7 @@ export async function recordOntologyRead(gate: SessionOntologyGate, ctx: ToolCon
   const sessionId = resolveGatedSession(gate, ctx, wsPath);
   if (sessionId === 'skip') return;
   // checkOperation(isWrite=false) records the touch and always allows.
-  await gate.service.checkOperation(sessionId, wsPath, false, gate.kbDirName);
+  await gate.service.checkOperation(sessionId, wsPath, false, gate.kb.kbDirName);
 }
 
 /**
@@ -155,7 +157,7 @@ export async function assertOntologyWriteAllowed(
   // Tracking stays core: record the (now-allowed) write's ontology touch.
   // A blocked write never reaches this line, so it records nothing — same as
   // before the hook split.
-  await gate.service.checkOperation(sessionId, wsPath, false, gate.kbDirName);
+  await gate.service.checkOperation(sessionId, wsPath, false, gate.kb.kbDirName);
 }
 
 /**

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

@@ -6,7 +6,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { KbRemoteUnreachableError, KbStartupRunner } from '../kb-startup-runner.js';
 import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
-import { GitRunError, type IGitRunner } from '../../../../shared/git.contract.js';
+import { GitRunError, NO_GIT_CREDENTIALS, type IGitRunner } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**
@@ -69,7 +69,6 @@ function makeRunner(steps: OnServerStart[], url: () => string, gitRunner: IGitRu
   return new KbStartupRunner({
     gitRunner,
     kbRepoUrl: url,
-    gitUsername: () => 'x-access-token',
     workspacesRoot,
     kbDirName: 'knowledge-base',
     templateDir: path.join(root, 'template'),
@@ -101,6 +100,7 @@ describe('KbStartupRunner with an unreachable remote', () => {
   it('a git that never ran is not "unreachable" either: that failure is this host, and it stops the boot', async () => {
     const noGit: IGitRunner = {
       defaultTimeoutMs: 1000,
+      credentials: NO_GIT_CREDENTIALS,
       run: (async () => {
         throw new GitRunError('git ls-remote failed: spawn git ENOENT');
       }) as IGitRunner['run'],
@@ -251,6 +251,7 @@ describe('KbStartupRunner with a remote that rejects the credentials', () => {
     // re-dial a host that will never accept the token.
     const rejecting: IGitRunner = {
       defaultTimeoutMs: 1000,
+      credentials: NO_GIT_CREDENTIALS,
       run: (async () => {
         // The shape `NodeGitRunner` throws: git's words in the message (that
         // is what the boot classifies) and again in `stderr`.
@@ -275,6 +276,7 @@ describe('KbStartupRunner retry after a boot that survived a rejected token', ()
     let dials = 0;
     const rejecting: IGitRunner = {
       defaultTimeoutMs: 1000,
+      credentials: NO_GIT_CREDENTIALS,
       run: (async () => {
         dials += 1;
         const said = "fatal: Authentication failed for 'https://example.com/acme/kb.git/'";
@@ -319,6 +321,7 @@ describe('KbStartupRunner retry when the token is rejected while it sleeps', ()
     let dials = 0;
     const rejecting: IGitRunner = {
       defaultTimeoutMs: 1000,
+      credentials: NO_GIT_CREDENTIALS,
       run: (async () => {
         dials += 1;
         const said = "fatal: Authentication failed for 'https://example.com/acme/kb.git/'";
@@ -331,6 +334,7 @@ describe('KbStartupRunner retry when the token is rejected while it sleeps', ()
     let current: IGitRunner = new NodeGitRunner();
     const switching: IGitRunner = {
       defaultTimeoutMs: 1000,
+      credentials: NO_GIT_CREDENTIALS,
       run: ((...args: Parameters<IGitRunner['run']>) => current.run(...args)) as IGitRunner['run'],
     };
     let url = path.join(root, 'nowhere.git');

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
 import { NodeFs } from '../../../kb-fs/node-fs.js';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -9,8 +10,18 @@ import { KbStartupRunner } from '../kb-startup-runner.js';
 import { WorkspaceService } from '../../workspace.service.js';
 import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
 import { ClassifiedFailure, classifyGitFailure, failureOf } from '../../../../shared/git-failure.js';
+import { gitCredentials } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
+/**
+ * The token in effect for the runners these suites build, changed by the
+ * cases that need one — the way the setup screen changes it on a running
+ * deployment: through the provider the runner reads on every call, never
+ * through this process's environment.
+ */
+let token: string | null = null;
+const credentials = gitCredentials('x-access-token', () => token);
+
 const execFileAsync = promisify(execFile);
 
 const PROTECTED = ['current-company-state', 'target-company-state'];
@@ -65,9 +76,8 @@ function makeRunner(steps: OnServerStart[], overrides: Partial<Parameters<typeof
 
 function runnerOpts(steps: OnServerStart[], overrides: Record<string, unknown> = {}) {
   return {
-    gitRunner: new NodeGitRunner(),
+    gitRunner: new NodeGitRunner(undefined, credentials),
     kbRepoUrl: () => upstream,
-    gitUsername: () => 'x-access-token',
     workspacesRoot,
     kbDirName: 'knowledge-base',
     templateDir: path.join(root, 'template'),
@@ -486,7 +496,7 @@ describe('KbStartupRunner — what a failed phase throws', () => {
     try {
       const err = await makeRunner([step('noop', async () => ({ outcome: 'ok' }))], {
         kbRepoUrl: () => 'https://127.0.0.1:1/kb.git?X-Amz-Signature=SECRETSIG',
-        gitToken: () => 'access',
+        gitRunner: new NodeGitRunner(undefined, gitCredentials('x-access-token', 'access')),
       })
         .runAll()
         .then(
@@ -518,7 +528,7 @@ describe('KbStartupRunner redaction', () => {
             throw new Error('the host said ghp_settingsonly42 is not welcome');
           }),
         ],
-        { gitToken: () => 'ghp_settingsonly42' },
+        { gitRunner: new NodeGitRunner(undefined, gitCredentials('x-access-token', 'ghp_settingsonly42')) },
       );
       const err = await runner.runAll().then(
         () => null,
@@ -540,10 +550,8 @@ describe('KbStartupRunner credentials', () => {
   // 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;
+    token = null;
   });
 
 
@@ -561,7 +569,7 @@ describe('KbStartupRunner credentials', () => {
   }
 
   it('leaves the boot clone able to authenticate a push of its own', async () => {
-    process.env.GITHUB_TOKEN = 'ghp_boot';
+    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.
@@ -585,7 +593,7 @@ describe('KbStartupRunner credentials', () => {
     // 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';
+    token = 'ghp_boot';
     await populatedUpstream();
     const repo = await materializeDefaultBranchClone();
     // App-shaped drift: a second stamp of OURS with a stale username — the
@@ -594,7 +602,7 @@ describe('KbStartupRunner credentials', () => {
     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', new NodeFs(), () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH);
 
     const all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
@@ -607,19 +615,19 @@ describe('KbStartupRunner credentials', () => {
     // 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';
+    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', new NodeFs(), () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     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', new NodeFs(), () => 'x-access-token');
+    token = null;
+    const ws2 =new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     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');
@@ -630,12 +638,12 @@ describe('KbStartupRunner credentials', () => {
     // 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';
+    token = 'ghp_boot';
     await populatedUpstream();
     const repo = await materializeDefaultBranchClone(); // stamped
-    delete process.env.GITHUB_TOKEN;
+    token = null;
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH);
 
     await expect(git(repo, ['config', '--local', '--get', 'credential.helper']))
@@ -646,13 +654,13 @@ describe('KbStartupRunner credentials', () => {
     // 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;
+    token = null;
     await populatedUpstream();
     const repo = await materializeDefaultBranchClone(); // no helper
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // adopt, tokenless
-    process.env.GITHUB_TOKEN = 'ghp_late';
+    token = 'ghp_late';
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // cached fast path
 
     const helper = (await git(repo, ['config', '--local', '--get', 'credential.helper'])).trim();
@@ -661,7 +669,7 @@ describe('KbStartupRunner credentials', () => {
   });
 
   it('clones without a helper when the deployment has no token — an open remote still boots', async () => {
-    delete process.env.GITHUB_TOKEN;
+    token = null;
     await populatedUpstream();
     const repo = await materializeDefaultBranchClone();
     // `--get` exits 1 when the key is unset. Assert on that exit code rather

package/src/modules/workspace/startup/kb-git.ts

@@ -29,12 +29,13 @@ const STARTUP_GIT_TIMEOUT_MS = 600_000;
 
 /**
  * Per-invocation `-c` config. Long paths always (Windows checkouts of deep
- * KB trees); when a token is present, an inline credential helper that reads
- * it from the environment at call time — the secret never appears in argv.
+ * KB trees); when the runner carries a token, an inline credential helper
+ * that reads it from the child's environment at call time — the secret never
+ * appears in argv.
  */
-function credArgs(gitUsername: string): string[] {
+function credArgs(runner: IGitRunner): string[] {
   const args = ['-c', 'core.longpaths=true'];
-  const helper = credentialHelperValue(gitUsername);
+  const helper = credentialHelperValue(runner.credentials);
   if (helper) args.push('-c', `credential.helper=${helper}`);
   return args;
 }
@@ -49,18 +50,14 @@ function credArgs(gitUsername: string): string[] {
  * clone to carry its own credentials. Persist them with `clone --config` (which
  * only means "write into the new repo" after the subcommand) so it does.
  */
-function withPersistedCloneConfig(gitUsername: string, args: string[]): string[] {
+function withPersistedCloneConfig(runner: IGitRunner, args: string[]): string[] {
   if (args[0] !== 'clone') return args;
-  return [args[0], ...cloneCredentialArgs(gitUsername), ...args.slice(1)];
+  return [args[0], ...cloneCredentialArgs(runner.credentials), ...args.slice(1)];
 }
 
-export async function git(
-  runner: IGitRunner,
-  cwd: string,
-  gitUsername: string,
-  args: string[],
-): Promise<string> {
-  const argv = [...credArgs(gitUsername), ...withPersistedCloneConfig(gitUsername, args)];
+/** Run one git command of the phase, authenticated with the runner's own credentials. */
+export async function git(runner: IGitRunner, cwd: string, args: string[]): Promise<string> {
+  const argv = [...credArgs(runner), ...withPersistedCloneConfig(runner, args)];
   try {
     // A floor under the configured ceiling, not a replacement for it: an
     // operator who raised GIT_TIMEOUT_MS past ten minutes gets that here too.
@@ -83,18 +80,14 @@ export async function git(
   }
 }
 
-export async function stampIdentity(runner: IGitRunner, repo: string, gitUsername: string): Promise<void> {
-  await git(runner, repo, gitUsername, ['config', 'user.name', BOT_NAME]);
-  await git(runner, repo, gitUsername, ['config', 'user.email', BOT_EMAIL]);
+export async function stampIdentity(runner: IGitRunner, repo: string): Promise<void> {
+  await git(runner, repo, ['config', 'user.name', BOT_NAME]);
+  await git(runner, repo, ['config', 'user.email', BOT_EMAIL]);
 }
 
 /** Branch names present on the remote, from `ls-remote --heads`. */
-export async function lsRemoteHeads(
-  runner: IGitRunner,
-  repoUrl: string,
-  gitUsername: string,
-): Promise<Set<string>> {
-  const out = await git(runner, os.tmpdir(), gitUsername, ['ls-remote', '--heads', repoUrl]);
+export async function lsRemoteHeads(runner: IGitRunner, repoUrl: string): Promise<Set<string>> {
+  const out = await git(runner, os.tmpdir(), ['ls-remote', '--heads', repoUrl]);
   const heads = new Set<string>();
   for (const line of out.split('\n')) {
     const m = /\srefs\/heads\/(.+)$/.exec(line.trim());