@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/workspace/startup/__tests__/beside-checkout.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { BESIDE_CHECKOUT_NOTE, noteBesideCheckout } from '../beside-checkout.js';
+
+/**
+ * Strays that already exist on a running deployment are NAMED at boot and
+ * touched by nothing. The normaliser stops new ones being made; this scan is
+ * the only way anyone learns about the old ones, now that the explorer reads
+ * its roots from the checkout and no longer shows them.
+ */
+
+const KB = 'knowledge-base';
+
+let root = '';
+let notes: string[] = [];
+
+const scan = () => noteBesideCheckout(root, KB, (line) => notes.push(line));
+
+/** A workspace directory holding a checkout, plus whatever `strays` name. */
+async function workspace(id: string, strays: { dirs?: string[]; files?: string[] } = {}): Promise<string> {
+  const dir = path.join(root, id);
+  await fs.mkdir(path.join(dir, KB, '.git'), { recursive: true });
+  for (const d of strays.dirs ?? []) await fs.mkdir(path.join(dir, d), { recursive: true });
+  for (const f of strays.files ?? []) await fs.writeFile(path.join(dir, f), 'x', 'utf-8');
+  return dir;
+}
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'beside-checkout-'));
+  notes = [];
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+describe('noteBesideCheckout', () => {
+  it('names every file and folder beside the checkout in one note, and deletes nothing', async () => {
+    // Exactly what was found on core-staging on 2026-09-22.
+    const dir = await workspace('main', {
+      dirs: ['KnowledgeBase', 'Plugins'],
+      files: ['TestJpg.jpg'],
+    });
+
+    await scan();
+
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "KnowledgeBase/", "Plugins/", "TestJpg.jpg"`);
+    expect(notes[0]).toContain('"main"');
+    // Named, not touched.
+    for (const entry of ['KnowledgeBase', 'Plugins', 'TestJpg.jpg', KB]) {
+      await expect(fs.stat(path.join(dir, entry))).resolves.toBeTruthy();
+    }
+  });
+
+  it('says nothing when the checkout is all there is', async () => {
+    await workspace('main');
+    await scan();
+    expect(notes).toEqual([]);
+  });
+
+  it('marks the folders with a trailing slash so one line says which is which', async () => {
+    await workspace('main', { dirs: ['Reports'], files: ['Reports.md'] });
+    await scan();
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "Reports.md", "Reports/"`);
+  });
+
+  it('gives each workspace its own note, and none to the clean ones', async () => {
+    await workspace('main', { files: ['stray.md'] });
+    await workspace('alice%2Fdraft');
+    await workspace('bob%2Fdraft', { dirs: ['Uploads'] });
+
+    await scan();
+
+    expect(notes).toHaveLength(2);
+    expect(notes.some((n) => n.includes('"stray.md"') && n.includes('"main"'))).toBe(true);
+    expect(notes.some((n) => n.includes('"Uploads/"') && n.includes('"bob%2Fdraft"'))).toBe(true);
+  });
+
+  it('names the checkout folder itself never, whatever the deployment calls it', async () => {
+    const dir = path.join(root, 'main');
+    await fs.mkdir(path.join(dir, 'kb', '.git'), { recursive: true });
+    await fs.mkdir(path.join(dir, KB), { recursive: true });
+
+    // With `kb` configured as the clone folder, a `knowledge-base/` directory
+    // IS a stray — ordinary content nobody commits — and is named as one.
+    await noteBesideCheckout(root, 'kb', (line) => notes.push(line));
+
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "${KB}/"`);
+  });
+
+  // A stray's name is disk-controlled text going into an operator's log, and
+  // the filesystem allows a newline or a raw CSI in it. Escaped, the note stays
+  // ONE line and cannot forge a second or paint the terminal — the reason every
+  // name goes through `printable`, asserted here rather than left to the
+  // incidental quoting the other cases see.
+  it.runIf(process.platform !== 'win32')('escapes a stray name that could forge a line or steer the terminal', async () => {
+    await workspace('main', { files: ['bad\nname.md'], dirs: ['CSI\u009Bdir'] });
+
+    await scan();
+
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain('"CSI\\u009bdir/"');
+    expect(notes[0]).toContain('"bad\\nname.md"');
+    // Nothing raw survived into the line, and the line is still one line.
+    expect(notes[0]).not.toContain('\u009B');
+    expect(notes[0].split('\n')).toHaveLength(1);
+  });
+
+  it('names a FILE squatting the checkout name — it is not a clone', async () => {
+    // The exemption belongs to the checkout, not to the name. A regular file
+    // called `knowledge-base` is the state `WorkspaceService` refuses the
+    // workspace over ("exists but is not a directory"), and the operator only
+    // learns it is there if the note says so.
+    const dir = path.join(root, 'main');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, KB), 'not a clone', 'utf-8');
+
+    await scan();
+
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "${KB}"`);
+    // Named, not touched.
+    expect(await fs.readFile(path.join(dir, KB), 'utf-8')).toBe('not a clone');
+  });
+
+  it.runIf(process.platform !== 'win32')('says nothing when the checkout is a link to a clone elsewhere', async () => {
+    // Links are followed, as the service follows them: a clone mounted
+    // elsewhere is the operator's business, not a stray.
+    const elsewhere = await fs.mkdtemp(path.join(os.tmpdir(), 'beside-checkout-clone-'));
+    await fs.mkdir(path.join(elsewhere, '.git'), { recursive: true });
+    const dir = path.join(root, 'main');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.symlink(elsewhere, path.join(dir, KB), 'dir');
+
+    await scan();
+
+    expect(notes).toEqual([]);
+    await fs.rm(elsewhere, { recursive: true, force: true });
+  });
+
+  it.runIf(process.platform !== 'win32')('names a DANGLING link where the checkout should be', async () => {
+    // Absence is an answer: a link to nothing is not a clone, and the operator
+    // needs to know the workspace has no checkout in it.
+    const dir = path.join(root, 'main');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.symlink(path.join(root, 'gone'), path.join(dir, KB), 'dir');
+
+    await scan();
+
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain(`${BESIDE_CHECKOUT_NOTE} "${KB}"`);
+  });
+
+  it.runIf(process.platform !== 'win32')('refuses to guess about a checkout it cannot read', async () => {
+    // A self-referential link answers ELOOP, not "absent". Swallowing that
+    // would publish "the checkout is a stray" about a path this process could
+    // not read — so the scan throws and the boot's handler names it instead.
+    const dir = path.join(root, 'main');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.symlink(path.join(dir, KB), path.join(dir, KB));
+
+    await expect(scan()).rejects.toMatchObject({ code: 'ELOOP' });
+    expect(notes).toEqual([]);
+  });
+
+  it('is quiet on a cold start, with no workspaces root on disk yet', async () => {
+    await noteBesideCheckout(path.join(root, 'not-yet'), KB, (line) => notes.push(line));
+    expect(notes).toEqual([]);
+  });
+
+  it('ignores a file sitting in the workspaces root itself — a workspace is a directory', async () => {
+    await fs.writeFile(path.join(root, '.DS_Store'), '', 'utf-8');
+    await workspace('main');
+    await scan();
+    expect(notes).toEqual([]);
+  });
+});

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

@@ -0,0 +1,361 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+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 type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+
+/**
+ * What the runner does when the remote is not there — the one failure a boot
+ * now survives. Real git against a real bare upstream, like the sibling suite;
+ * "unreachable" is a path where no repository exists, which `ls-remote`
+ * refuses at once.
+ */
+
+const execFileAsync = promisify(execFile);
+const PROTECTED = ['current-company-state', 'target-company-state'];
+const DEFAULT_BRANCH = 'current-company-state';
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+  return stdout.toString();
+}
+
+let root: string;
+let upstream: string;
+let workspacesRoot: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-startup-degraded-'));
+  workspacesRoot = path.join(root, 'workspaces');
+  await fs.mkdir(workspacesRoot, { recursive: true });
+  upstream = path.join(root, 'upstream.git');
+  await git(root, ['init', '--bare', '-b', DEFAULT_BRANCH, upstream]);
+  delete process.env.KB_SAFE_BOOT;
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+function step(name: string, run: (ctx: ServerStartContext) => Promise<StepResult>): OnServerStart {
+  return { name, run };
+}
+
+/**
+ * Poll until `condition` holds. Bounded generously: each retry attempt here is
+ * a real clone, which takes well over a second on a machine running the whole
+ * suite, and a bound sized for an idle machine fails the test under load.
+ */
+async function waitFor(condition: () => boolean, timeoutMs = 20_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!condition() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+function makeRunner(steps: OnServerStart[], url: () => string, gitRunner: IGitRunner = new NodeGitRunner()) {
+  return new KbStartupRunner({
+    gitRunner,
+    kbRepoUrl: url,
+    gitUsername: () => 'x-access-token',
+    workspacesRoot,
+    kbDirName: 'knowledge-base',
+    templateDir: path.join(root, 'template'),
+    defaultBranch: () => DEFAULT_BRANCH,
+    protectedBranches: () => PROTECTED,
+    seedAdminEmails: ['admin@example.com'],
+    steps,
+    buildSeedTree: async (dir: string) => {
+      await fs.writeFile(path.join(dir, 'seeded.md'), 'from template', 'utf8');
+      return [];
+    },
+  });
+}
+
+describe('KbStartupRunner with an unreachable remote', () => {
+  it('fails as unreachable, and stands on that failure until a run finishes', async () => {
+    const runner = makeRunner([], () => path.join(root, 'nowhere.git'));
+
+    await expect(runner.runAll()).rejects.toBeInstanceOf(KbRemoteUnreachableError);
+    expect(runner.lastFailure()).toMatch(/could not be reached/);
+
+    // The failure is the runner's own state, not the caller's: the gate reads
+    // it from here, whichever caller ran the phase.
+    const healthy = makeRunner([], () => upstream);
+    await healthy.runAll();
+    expect(healthy.lastFailure()).toBeNull();
+  });
+
+  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,
+      run: (async () => {
+        throw new GitRunError('git ls-remote failed: spawn git ENOENT');
+      }) as IGitRunner['run'],
+    };
+    const runner = makeRunner([], () => upstream, noGit);
+    const err = await runner.runAll().catch((e: unknown) => e);
+    expect(err).not.toBeInstanceOf(KbRemoteUnreachableError);
+    expect((err as Error).message).toMatch(/spawn git ENOENT/);
+  });
+
+  it('records its attempts to reach the remote, for the readiness answer', async () => {
+    const runner = makeRunner([], () => path.join(root, 'nowhere.git'));
+    expect(runner.lastRemoteContact()).toBeNull();
+    await runner.runAll().catch(() => undefined);
+    expect(runner.lastRemoteContact()).toMatchObject({ ok: false });
+
+    const healthy = makeRunner([], () => upstream);
+    await healthy.runAll();
+    expect(healthy.lastRemoteContact()).toMatchObject({ ok: true });
+  });
+
+  it('a broken step is not "unreachable": that failure is the knowledge base being wrong', async () => {
+    const runner = makeRunner(
+      [step('broken', async () => ({ outcome: 'stopBoot', message: 'template is not what it should be' }))],
+      () => upstream,
+    );
+    const err = await runner.runAll().catch((e: unknown) => e);
+    expect(err).not.toBeInstanceOf(KbRemoteUnreachableError);
+    expect(runner.lastFailure()).toMatch(/template is not what it should be/);
+  });
+
+  it('two callers at once share one run rather than racing the clones', async () => {
+    let runs = 0;
+    const runner = makeRunner(
+      [
+        step('count', async () => {
+          runs += 1;
+          await new Promise((resolve) => setTimeout(resolve, 20));
+          return { outcome: 'ok' };
+        }),
+      ],
+      () => upstream,
+    );
+
+    await Promise.all([runner.runAll(), runner.runAll()]);
+    expect(runs).toBe(1);
+    // And a run after the shared one has settled is a new run.
+    await runner.runAll();
+    expect(runs).toBe(2);
+  });
+
+  it('keeps trying, with a growing wait, until the remote is back — then stops', async () => {
+    let url = path.join(root, 'nowhere.git');
+    const runner = makeRunner([], () => url);
+    await runner.runAll().catch(() => undefined);
+    expect(runner.lastFailure()).not.toBeNull();
+
+    const waits: number[] = [];
+    let attempt = 0;
+    const retry = runner.retryUntilMaintained({
+      initialDelayMs: 100,
+      maxDelayMs: 250,
+      log: () => undefined,
+      sleep: async (ms) => {
+        waits.push(ms);
+        attempt += 1;
+        // The remote comes back before the third attempt.
+        if (attempt === 3) url = upstream;
+      },
+    });
+
+    // Let the loop run its attempts to completion.
+    await waitFor(() => runner.lastFailure() === null);
+    expect(runner.lastFailure()).toBeNull();
+    // 100 → 200 → capped at 250; the loop asked three times and then stopped.
+    expect(waits).toEqual([100, 200, 250]);
+
+    // Stopped on success: no further sleeps arrive.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(waits).toHaveLength(3);
+    retry.stop();
+  });
+
+  it('does not run again when another caller finished the phase while it slept', async () => {
+    let url = path.join(root, 'nowhere.git');
+    let runs = 0;
+    const runner = makeRunner(
+      [
+        step('count', async () => {
+          runs += 1;
+          return { outcome: 'ok' };
+        }),
+      ],
+      () => url,
+    );
+    await runner.runAll().catch(() => undefined);
+    expect(runs).toBe(0);
+
+    let slept = 0;
+    runner.retryUntilMaintained({
+      initialDelayMs: 10,
+      log: () => undefined,
+      sleep: async () => {
+        slept += 1;
+        // The setup save, landing while the loop sleeps: the remote is
+        // reachable and the phase finishes through that caller.
+        url = upstream;
+        await runner.runAll();
+      },
+    });
+    await waitFor(() => runs === 1);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    // The loop woke to a finished phase and did not run it a second time.
+    expect(runs).toBe(1);
+    expect(slept).toBe(1);
+  });
+
+  it('stops retrying on a failure that is not the remote — asking again would not change it', async () => {
+    let url = path.join(root, 'nowhere.git');
+    const runner = makeRunner(
+      [step('broken', async () => ({ outcome: 'stopBoot', message: 'the template is wrong' }))],
+      () => url,
+    );
+    await runner.runAll().catch(() => undefined);
+
+    const waits: number[] = [];
+    runner.retryUntilMaintained({
+      initialDelayMs: 10,
+      log: () => undefined,
+      sleep: async (ms) => {
+        waits.push(ms);
+        url = upstream; // reachable now — and the step fails instead
+      },
+    });
+    await waitFor(() => (runner.lastFailure() ?? '').includes('template is wrong'));
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(waits).toHaveLength(1);
+    expect(runner.lastFailure()).toMatch(/template is wrong/);
+  });
+});
+
+describe('KbStartupRunner with a remote that rejects the credentials', () => {
+  it('survives the boot as that failure, not as "unreachable" — the admin is told the token is wrong', async () => {
+    // A rotated token: git exits 128 with the host's refusal. The port
+    // classifies it as credentials-rejected on the way up; a boot must not
+    // re-label it as a network the server cannot reach — the setup screen
+    // would send the admin to check the address and the retry loop would
+    // re-dial a host that will never accept the token.
+    const rejecting: IGitRunner = {
+      defaultTimeoutMs: 1000,
+      run: (async () => {
+        // The shape `NodeGitRunner` throws: git's words in the message (that
+        // is what the boot classifies) and again in `stderr`.
+        const said = "remote: Invalid username or token.\nfatal: Authentication failed for 'https://example.com/acme/kb.git/'";
+        throw new GitRunError(`git ls-remote failed: Command failed: git ls-remote\n${said}`, {
+          exitCode: 128,
+          stderr: said,
+        });
+      }) as IGitRunner['run'],
+    };
+    const runner = makeRunner([], () => 'https://example.com/acme/kb.git', rejecting);
+
+    const err = await runner.runAll().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(KbRemoteUnreachableError);
+    expect((err as KbRemoteUnreachableError).failure.kind).toBe('credentials-rejected');
+    expect(runner.lastFailureKind()?.kind).toBe('credentials-rejected');
+  });
+});
+
+describe('KbStartupRunner retry after a boot that survived a rejected token', () => {
+  it('does not re-dial on a timer: only an unreachable remote is worth asking again unchanged', async () => {
+    let dials = 0;
+    const rejecting: IGitRunner = {
+      defaultTimeoutMs: 1000,
+      run: (async () => {
+        dials += 1;
+        const said = "fatal: Authentication failed for 'https://example.com/acme/kb.git/'";
+        throw new GitRunError(`git ls-remote failed: Command failed: git ls-remote\n${said}`, {
+          exitCode: 128,
+          stderr: said,
+        });
+      }) as IGitRunner['run'],
+    };
+    const runner = makeRunner([], () => 'https://example.com/acme/kb.git', rejecting);
+    await runner.runAll().catch(() => undefined);
+    expect(runner.lastFailureKind()?.kind).toBe('credentials-rejected');
+    expect(dials).toBe(1);
+
+    const waits: number[] = [];
+    const logged: string[] = [];
+    const retry = runner.retryUntilMaintained({
+      initialDelayMs: 5,
+      log: (m) => logged.push(m),
+      sleep: async (ms) => {
+        waits.push(ms);
+      },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    retry.stop();
+
+    // No timer, no second dial: the standing failure is still there for the
+    // setup screen, and the save that fixes the token runs the phase itself.
+    expect(waits).toEqual([]);
+    expect(dials).toBe(1);
+    expect(runner.lastFailureKind()?.kind).toBe('credentials-rejected');
+    expect(logged.join('\n')).toMatch(/saving the setup form retries/);
+  });
+});
+
+describe('KbStartupRunner retry when the token is rejected while it sleeps', () => {
+  it('stops instead of re-dialing: the setup save that failed with the rejected token owns the retry', async () => {
+    // The boot fails as unreachable, so the loop starts. While it sleeps, a
+    // setup save runs the phase with a token the host refuses: the standing
+    // failure is now one a retry cannot change, and the loop must read that
+    // AFTER the sleep, not only when it started.
+    let dials = 0;
+    const rejecting: IGitRunner = {
+      defaultTimeoutMs: 1000,
+      run: (async () => {
+        dials += 1;
+        const said = "fatal: Authentication failed for 'https://example.com/acme/kb.git/'";
+        throw new GitRunError(`git ls-remote failed: Command failed: git ls-remote\n${said}`, {
+          exitCode: 128,
+          stderr: said,
+        });
+      }) as IGitRunner['run'],
+    };
+    let current: IGitRunner = new NodeGitRunner();
+    const switching: IGitRunner = {
+      defaultTimeoutMs: 1000,
+      run: ((...args: Parameters<IGitRunner['run']>) => current.run(...args)) as IGitRunner['run'],
+    };
+    let url = path.join(root, 'nowhere.git');
+    const runner = makeRunner([], () => url, switching);
+    await runner.runAll().catch(() => undefined);
+    expect(runner.lastFailureKind()?.kind).not.toBe('credentials-rejected');
+
+    const waits: number[] = [];
+    const logged: string[] = [];
+    runner.retryUntilMaintained({
+      initialDelayMs: 5,
+      log: (m) => logged.push(m),
+      sleep: async (ms) => {
+        waits.push(ms);
+        // The setup save, landing while the loop sleeps, with a rotated token.
+        current = rejecting;
+        url = 'https://example.com/acme/kb.git';
+        await runner.runAll().catch(() => undefined);
+      },
+    });
+    await waitFor(() => logged.some((m) => m.includes('asking again cannot change')));
+    expect(runner.lastFailureKind()?.kind).toBe('credentials-rejected');
+    // One dial: the save's. The loop did not add one of its own.
+    expect(dials).toBe(1);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(waits).toHaveLength(1);
+  });
+});

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 { NodeFs } from '../../../kb-fs/node-fs.js';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
@@ -6,7 +7,8 @@ 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 { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
+import { ClassifiedFailure, classifyGitFailure, failureOf } from '../../../../shared/git-failure.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 const execFileAsync = promisify(execFile);
@@ -63,6 +65,7 @@ function makeRunner(steps: OnServerStart[], overrides: Partial<Parameters<typeof
 
 function runnerOpts(steps: OnServerStart[], overrides: Record<string, unknown> = {}) {
   return {
+    gitRunner: new NodeGitRunner(),
     kbRepoUrl: () => upstream,
     gitUsername: () => 'x-access-token',
     workspacesRoot,
@@ -474,24 +477,58 @@ describe('KbStartupRunner', () => {
   });
 });
 
-describe('redactSecret', () => {
-  it('scrubs the configured token wherever it appears', () => {
+describe('KbStartupRunner — what a failed phase throws', () => {
+  it('a scrubbed message (tokens, a presigned query) that still carries what git said', async () => {
     const prev = process.env.GITHUB_TOKEN;
-    process.env.GITHUB_TOKEN = 'ghp_supersecret';
+    // Tokens that spell parts of git's own wording: scrubbing them rewrites the
+    // diagnostic, so the scrubbed message alone would no longer read as unreachable.
+    process.env.GITHUB_TOKEN = 'onnect';
     try {
-      expect(redactSecret('fatal: ghp_supersecret was rejected')).toBe('fatal: *** was rejected');
+      const err = await makeRunner([step('noop', async () => ({ outcome: 'ok' }))], {
+        kbRepoUrl: () => 'https://127.0.0.1:1/kb.git?X-Amz-Signature=SECRETSIG',
+        gitToken: () => 'access',
+      })
+        .runAll()
+        .then(
+          () => null,
+          (e: unknown) => e,
+        );
+      expect(err).toBeInstanceOf(ClassifiedFailure);
+      const message = (err as Error).message;
+      expect(message).not.toContain('SECRETSIG');
+      expect(message).not.toMatch(/onnect|access/);
+      expect(failureOf(err).kind).toBe('unreachable');
+      expect(classifyGitFailure(message).kind).not.toBe('unreachable');
     } finally {
       if (prev === undefined) delete process.env.GITHUB_TOKEN;
       else process.env.GITHUB_TOKEN = prev;
     }
   });
+});
 
-  it('scrubs URL userinfo — a user:pass@ remote must not leak the password', () => {
-    expect(redactSecret("fetch of 'https://alice:hunter2@example.com/kb.git' failed")).toBe(
-      "fetch of 'https://***@example.com/kb.git' failed",
-    );
-    // A plain URL is untouched.
-    expect(redactSecret('https://example.com/kb.git')).toBe('https://example.com/kb.git');
+describe('KbStartupRunner redaction', () => {
+  it('scrubs the token in effect from a failure, even one that never reached the environment', async () => {
+    const saved = process.env.GITHUB_TOKEN;
+    delete process.env.GITHUB_TOKEN;
+    try {
+      await populatedUpstream();
+      const runner = makeRunner(
+        [
+          step('leaky', async () => {
+            throw new Error('the host said ghp_settingsonly42 is not welcome');
+          }),
+        ],
+        { gitToken: () => 'ghp_settingsonly42' },
+      );
+      const err = await runner.runAll().then(
+        () => null,
+        (e: unknown) => e as Error,
+      );
+      expect(err?.message).toContain('KB startup step "leaky" failed');
+      expect(err?.message).not.toContain('ghp_settingsonly42');
+    } finally {
+      if (saved !== undefined) process.env.GITHUB_TOKEN = saved;
+    }
   });
 });
 
@@ -557,7 +594,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', () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => 'x-access-token');
     await ws.getOrCreateForBranch(DEFAULT_BRANCH);
 
     const all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
@@ -575,14 +612,14 @@ describe('KbStartupRunner credentials', () => {
     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');
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => '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');
+    const ws2 = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => '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');
@@ -598,7 +635,7 @@ describe('KbStartupRunner credentials', () => {
     const repo = await materializeDefaultBranchClone(); // stamped
     delete process.env.GITHUB_TOKEN;
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => 'x-access-token');
     await ws.getOrCreateForBranch(DEFAULT_BRANCH);
 
     await expect(git(repo, ['config', '--local', '--get', 'credential.helper']))
@@ -613,7 +650,7 @@ describe('KbStartupRunner credentials', () => {
     await populatedUpstream();
     const repo = await materializeDefaultBranchClone(); // no helper
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', () => 'x-access-token');
+    const ws = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs(), () => 'x-access-token');
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // adopt, tokenless
     process.env.GITHUB_TOKEN = 'ghp_late';
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // cached fast path