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

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

@@ -0,0 +1,189 @@
+import { branchAuthorLocalpart, isProtectedBranch, suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { AccessDeniedError } from '../access-model/access-errors.js';
+import type { IChangeReadGate } from '../access-model/change-gate.js';
+import { toKbRelative } from '../access-model/kb-read-filter.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+
+/**
+ * Appended to the description of every workspace tool whose refusal is mapped
+ * by `writeDenial`, so an agent knows before it is refused that a refusal is
+ * not necessarily the end of the road.
+ */
+export const PROPOSAL_ROUTE_NOTE =
+  ' If this is refused for permissions, the `write-denied` error says whether you may propose the change instead (create a branch from this one, repeat this call on it, then `open_change_request` into this branch) and lists those steps.';
+
+/** One step of the proposal route, named by the tool the agent calls. */
+export interface ProposalStep {
+  tool: string;
+  args: Record<string, unknown>;
+  note: string;
+}
+
+/**
+ * The structured body of a permission refusal from a write tool. Carries no
+ * request arguments beyond the tool name and branch: file contents are the
+ * caller's own and may hold anything, so they are never echoed back.
+ */
+export interface WriteDeniedDetails {
+  /**
+   * The discriminator every typed tool refusal carries (`binary_not_writable`
+   * and the rest), which is also what `describeToolFailure` passes an MCP
+   * caller the details on. One name for one job — this answer is not special
+   * enough to introduce a second.
+   */
+  kind: 'write-denied';
+  path: string;
+  reason: string;
+  canPropose: boolean;
+  /** Present exactly when `canPropose` is true. */
+  proposal?: { targetBranch: string; draftBranch: string; steps: ProposalStep[] };
+  /** One sentence, present exactly when `canPropose` is false. */
+  cannotProposeReason?: string;
+}
+
+/**
+ * What the refusal said beyond "you may not write here": the eligible
+ * principals, or the sentence naming a principal excluded at the folder.
+ * Taken from the error's own message so the reason reads exactly as the UI's.
+ */
+function reasonOf(err: AccessDeniedError): string {
+  const lead = `You don't have permission to write to "${err.access.path}".`;
+  return err.message.startsWith(lead) ? err.message.slice(lead.length).trim() || err.message : err.message;
+}
+
+/**
+ * A suggested draft name on the `<email-localpart>/<kebab-slug>` convention.
+ *
+ * The prefix comes from `branchAuthorLocalpart` — the SAME derivation the
+ * platform judges branch authorship by — and not from a second spelling of
+ * it: `branchSegment` (the `suggestions/…` namespace's) keeps `.` and `_`,
+ * so `john.doe@x` would be suggested `john.doe/…` while authorship expects
+ * `john-doe/`, and the agent could not delete the draft it was told to make.
+ *
+ * A caller whose address yields no usable localpart (the helper answers null
+ * rather than inventing one) is given a draft under their own
+ * `suggestions/<who>-<id8>/` prefix instead — the platform's second
+ * authorship convention, the one the propose flow files under. It is keyed
+ * by the user id as well as the address, so it exists for every signed-in
+ * caller, and `isOwnSuggestionsBranch` recognises it as theirs: whichever
+ * convention supplies the name, the draft is one the caller can later
+ * manage and delete.
+ */
+function draftNameFor(user: { email: string; id: string }, path: string): string {
+  const local = branchAuthorLocalpart(user.email);
+  const prefix = local !== null ? `${local}/` : suggestionsBranchPrefixFor(user);
+  const base = path.split('/').filter(Boolean).pop() ?? 'change';
+  const slug = base.toLowerCase().replace(/\.[a-z0-9]+$/, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'change';
+  return `${prefix}propose-${slug}`;
+}
+
+/**
+ * A suggested change-request title, within `open_change_request`'s 256-character
+ * limit. Cut on a code-point boundary, so an emoji at the cut is dropped whole
+ * rather than leaving half a surrogate pair; the result is at most 256 UTF-16
+ * units, so it fits however the limit is counted.
+ */
+export function proposalTitleFor(path: string): string {
+  const title = `Propose a change to ${path}`;
+  if (title.length <= 256) return title;
+  let cut = title.slice(0, 255);
+  if (/[\uD800-\uDBFF]$/.test(cut)) cut = cut.slice(0, -1);
+  return `${cut}…`;
+}
+
+/**
+ * Turn a permission refusal from a write tool into a `write-denied` ToolError
+ * that says whether the caller may propose the change instead, and how.
+ *
+ * `canPropose` follows the rule that routes a UI upload to a suggestion: the
+ * refusal is on a protected branch (the only kind that takes change requests
+ * as a target) and the caller may make the change on a draft — which is the
+ * read-before-write gate's question (`IChangeReadGate`): they can READ the
+ * path, or it starts a new folder directly under one of the three roots.
+ * Nothing is created here — the agent decides whether to follow the steps.
+ *
+ * Without a gate the read verdict alone decides, which is the same answer
+ * everywhere but at a root.
+ */
+export async function writeDenial(
+  err: AccessDeniedError,
+  input: { tool: string; branch: string; userEmail: string; userId: string },
+  accessControl: IAccessControl,
+  kbDirName: string,
+  changeGate?: IChangeReadGate,
+): Promise<ToolError> {
+  const path = err.access.path;
+  const base = { kind: 'write-denied' as const, path, reason: reasonOf(err) };
+  const refuse = (cannotProposeReason: string): ToolError => {
+    const details: WriteDeniedDetails = { ...base, canPropose: false, cannotProposeReason };
+    return new ToolError(`${err.message} ${cannotProposeReason}`, 403, { ...details });
+  };
+
+  if (!isProtectedBranch(input.branch)) {
+    return refuse(`Proposing is not available: "${input.branch}" is not a branch that accepts change requests.`);
+  }
+  // The lock gate reports workspace paths, the git gates repo-relative ones.
+  const rel = toKbRelative(path, kbDirName) ?? path.replace(/^\.?\/+/, '');
+  const workspaceId = workspaceIdForBranch(input.branch);
+  let mayChange: boolean;
+  try {
+    // The refuser says what the path is when it knows (a folder a move or
+    // delete was judged on); a file otherwise. The gate's new-folder exception
+    // turns on exactly that.
+    mayChange = changeGate
+      ? (await changeGate.judge(workspaceId, input.userEmail, `${kbDirName}/${rel}`, err.access.targetKind ?? 'file')).allowed
+      : await accessControl.canRead(workspaceId, input.userEmail, rel);
+  } catch {
+    // Fail closed: offering a route the caller may not take is worse than none.
+    return refuse('Proposing is not offered: whether you can read this path could not be determined; try again.');
+  }
+  if (!mayChange) return refuse('Proposing is not available: you cannot read this path.');
+
+  const draft = draftNameFor({ email: input.userEmail, id: input.userId }, path);
+  const details: WriteDeniedDetails = {
+    ...base,
+    canPropose: true,
+    proposal: {
+      targetBranch: input.branch,
+      draftBranch: draft,
+      steps: [
+        {
+          tool: 'create_branch',
+          args: { name: draft, branch: input.branch },
+          note: `Create a draft from "${input.branch}" (any unused name on the same convention works).`,
+        },
+        {
+          tool: input.tool,
+          args: { branch: draft },
+          note: 'Repeat the same call with `branch` set to the draft; every other argument unchanged.',
+        },
+        {
+          tool: 'open_change_request',
+          args: { sourceBranch: draft, targetBranch: input.branch, title: proposalTitleFor(rel) },
+          note: 'Open a change request from the draft into the target; a sharper title saying what changes is better than the suggested one.',
+        },
+      ],
+    },
+  };
+  return new ToolError(
+    `${err.message} You may propose this change instead: create a branch from "${input.branch}", repeat this call on it, then open_change_request into "${input.branch}" (steps in \`proposal\`).`,
+    403,
+    { ...details },
+  );
+}
+
+/** Rethrow a permission refusal as `write-denied`; anything else passes through untouched. */
+export async function rethrowAsWriteDenial(
+  err: unknown,
+  input: { tool: string; branch: unknown; userEmail: string; userId: string },
+  accessControl: IAccessControl,
+  kbDirName: string,
+  changeGate?: IChangeReadGate,
+): Promise<never> {
+  if (err instanceof AccessDeniedError && typeof input.branch === 'string') {
+    throw await writeDenial(err, { ...input, branch: input.branch }, accessControl, kbDirName, changeGate);
+  }
+  throw err;
+}

package/src/shared/__tests__/canonical-file-identity.test.ts

@@ -0,0 +1,154 @@
+import path from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { assertValidRelativePath } from '@bevel-software/platform-shared';
+import { canonicalFileIdentity } from '../canonical-file-identity.js';
+import { PathTraversalError, WorkflowValidationError } from '../domain-errors.js';
+
+/**
+ * Two properties, and the second is the one worth the file.
+ *
+ * 1. Spellings of one file collapse to one string.
+ * 2. A path the canonicaliser refuses gets the SAME answer the file verbs
+ *    give for that input. The lock routes and `PUT /file` name the same
+ *    file and take the same lock, so answering differently would mean a path
+ *    the editor cannot save to is nonetheless lockable, or the reverse.
+ *
+ * The oracle for (2) is not a hand-written status table. It runs the guard
+ * pair `WorkspaceService.withPathTurn` runs, in its order: the shared
+ * `assertValidRelativePath`, whose `Invalid path: ...` message
+ * `workspace.routes.sendError` maps to 400, then resolution against the
+ * workspace directory, whose `Path traversal detected`
+ * `sendError` maps to 403. The validator is the real one, imported, so a
+ * change to what it accepts moves both sides of the comparison at once.
+ */
+
+const WORKSPACE_DIR = path.resolve('/srv/workspaces/feat%2Fx');
+
+/** The status `PUT /file` answers for `candidate`, or 0 when it accepts it. */
+function fileVerbStatus(candidate: string): number {
+  try {
+    assertValidRelativePath(candidate);
+  } catch {
+    return 400; // `sendError`: a message starting with "Invalid path".
+  }
+  // `WorkspaceService.assertWithinWorkspace`, verbatim.
+  const resolved = path.resolve(WORKSPACE_DIR, candidate);
+  if (!resolved.startsWith(WORKSPACE_DIR + path.sep) && resolved !== WORKSPACE_DIR) {
+    return 403; // `sendError`: the message "Path traversal detected".
+  }
+  return 0;
+}
+
+/** The status the lock surface answers for `candidate`, or 0 when accepted. */
+function lockStatus(candidate: string): number {
+  try {
+    canonicalFileIdentity(candidate);
+    return 0;
+  } catch (err) {
+    return (err as { status: number }).status;
+  }
+}
+
+const ONE_FILE = 'knowledge-base/x/a.md';
+
+describe('canonicalFileIdentity', () => {
+  it.each([
+    ONE_FILE,
+    `./${ONE_FILE}`,
+    'knowledge-base//x/a.md',
+    './knowledge-base//x//a.md',
+    'knowledge-base/x//a.md',
+  ])('reads %s as one file', (spelling) => {
+    expect(canonicalFileIdentity(spelling)).toBe(ONE_FILE);
+  });
+
+  it('is idempotent', () => {
+    const once = canonicalFileIdentity('./knowledge-base//x//a.md');
+    expect(canonicalFileIdentity(once)).toBe(once);
+  });
+
+  it('leaves case alone: on Linux Foo.md and foo.md are two files', () => {
+    expect(canonicalFileIdentity('knowledge-base/Foo.md')).toBe('knowledge-base/Foo.md');
+    expect(canonicalFileIdentity('knowledge-base/Foo.md')).not.toBe(
+      canonicalFileIdentity('knowledge-base/foo.md'),
+    );
+  });
+
+  it('refuses a path that climbs out rather than resolving it away', () => {
+    expect(() => canonicalFileIdentity('../etc/passwd')).toThrow(WorkflowValidationError);
+    expect(() => canonicalFileIdentity('knowledge-base/../../etc/passwd')).toThrow(
+      WorkflowValidationError,
+    );
+  });
+
+  it('refuses a climb that would land back inside, instead of laundering it', () => {
+    // `knowledge-base/x/../y.md` resolves inside the workspace, so a
+    // containment check alone would wave it through under a second identity
+    // for `knowledge-base/y.md`.
+    expect(() => canonicalFileIdentity('knowledge-base/x/../y.md')).toThrow(
+      WorkflowValidationError,
+    );
+  });
+
+  it('refuses an absolute path as traversal, not as a relative one', () => {
+    // Dropping the empty leading segment would turn `/etc/passwd` into the
+    // perfectly ordinary `etc/passwd`, which is exactly the laundering
+    // `canonicalRelativePath` declines to do.
+    expect(() => canonicalFileIdentity('/etc/passwd')).toThrow(PathTraversalError);
+  });
+
+  it('refuses an absolute path however contained it looks', () => {
+    // `validateRelativePath` accepts `/workspace/a.md` (its leading empty
+    // segment is filtered out), and resolved against a root named
+    // `/workspace` it would even read as contained — which is why absolute is
+    // refused as absolute and never by resolving. No real workspace directory
+    // is literally `/workspace` (it is `<workspacesRoot>/<id>`), so the file
+    // verbs resolve that same path outside their workspace and answer 403.
+    expect(() => canonicalFileIdentity('/workspace/a.md')).toThrow(PathTraversalError);
+    expect(() => canonicalFileIdentity('/workspace')).toThrow(PathTraversalError);
+  });
+
+  it('refuses a non-string path as the client mistake it is, not as a 500', () => {
+    // The routes' guard only tests falsiness, so `{"path": 123}` reaches
+    // here. Unguarded, `canonicalRelativePath` calls `.startsWith` on a
+    // number and the bare `TypeError` becomes a 500; `PUT /file` answers
+    // 400 for that same body.
+    for (const notAPath of [123, true, {}, [], ['a.md'], null, undefined]) {
+      expect(() => canonicalFileIdentity(notAPath as unknown as string)).toThrow(
+        WorkflowValidationError,
+      );
+      expect(() => canonicalFileIdentity(notAPath as unknown as string)).toThrow(
+        'Invalid path: Path is required',
+      );
+    }
+  });
+
+  const INPUTS = [
+    ONE_FILE,
+    `./${ONE_FILE}`,
+    'knowledge-base//x/a.md',
+    'knowledge-base/Some [Approved] Node.md',
+    '../etc/passwd',
+    '../../etc/passwd',
+    'knowledge-base/../../etc/passwd',
+    'knowledge-base/x/../y.md',
+    './..',
+    '..',
+    '.',
+    './',
+    '/etc/passwd',
+    // Absolute spellings, including a pair that would read as contained if
+    // any root were named `/workspace` — refused as absolute, never resolved.
+    '/workspace/a.md',
+    '/workspace',
+    '/workspace/',
+    '/',
+    'knowledge-base\\x\\a.md',
+    'C:/Windows/system32',
+    '',
+  ];
+
+  it.each(INPUTS)('answers %j with the status the file verbs answer', (input) => {
+    expect(lockStatus(input)).toBe(fileVerbStatus(input));
+  });
+});

package/src/shared/__tests__/email-identity.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { createHash } from 'node:crypto';
+import { canonicalEmail, hashEmail } from '../email-identity.js';
+
+describe('canonicalEmail', () => {
+  it('trims and lowercases, so one person has one spelling', () => {
+    expect(canonicalEmail('  Mia@X.io ')).toBe('mia@x.io');
+    expect(canonicalEmail('mia@x.io')).toBe('mia@x.io');
+    expect(canonicalEmail('MIA@X.IO')).toBe('mia@x.io');
+  });
+
+  it('leaves everything else alone — no dot-folding, no plus-tag stripping', () => {
+    // Providers disagree about these, and a rule that guessed would merge two
+    // identities the operator's directory treats as distinct.
+    expect(canonicalEmail('m.i.a+reviews@x.io')).toBe('m.i.a+reviews@x.io');
+  });
+});
+
+describe('hashEmail', () => {
+  it('hashes the CANONICAL form — the property PR attribution depends on', () => {
+    // The author id is written into a PR body from one spelling and looked up
+    // from another; if the two normalised differently, every PR the bot opened
+    // would be de-attributed. The access resolver carried its own copy of this
+    // expression, used by the very lookup that has to agree with it.
+    const expected = createHash('sha256').update('mia@x.io').digest('hex');
+    expect(hashEmail('mia@x.io')).toBe(expected);
+    expect(hashEmail('  Mia@X.io ')).toBe(expected);
+    expect(hashEmail('MIA@X.IO')).toBe(expected);
+  });
+
+  it('separates two people who differ by more than spelling', () => {
+    expect(hashEmail('mia@x.io')).not.toBe(hashEmail('sam@x.io'));
+    expect(hashEmail('mia@x.io')).not.toBe(hashEmail('mia+reviews@x.io'));
+  });
+});

package/src/shared/__tests__/frontmatter-id.test.ts

@@ -123,6 +123,11 @@ describe('setFrontmatterField (shared, line-based)', () => {
     expect(out).toBe('---\nid: weather2\nname: weather\n---\n{"type":"http"}\n');
   });
 
+  test('fills an EMPTY block without leaving a blank line before the closing fence', () => {
+    const out = setFrontmatterField('---\n---\n# Body\n', 'id', 'fresh');
+    expect(out).toBe('---\nid: fresh\n---\n# Body\n');
+  });
+
   test('creates a frontmatter block when the file has none', () => {
     const out = setFrontmatterField('{"type":"http","url":"https://x/m"}', 'id', 'tool_x');
     expect(out).toBe('---\nid: tool_x\n---\n{"type":"http","url":"https://x/m"}');

package/src/shared/__tests__/git-failure.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from 'vitest';
+import { ClassifiedFailure, classifyGitFailure, failureOf } from '../git-failure.js';
+
+/**
+ * Representative failures, spelled the way they actually reach the classifier:
+ * `kb-git.ts` prefixes `git <subcommand> failed: ` onto execFile's message,
+ * which is `Command failed: <argv>` followed by git's stderr; the runner
+ * prefixes `KB startup step "<name>" failed: ` onto a step's throw.
+ */
+const gitFailed = (sub: string, url: string, stderr: string) =>
+  `git ${sub} failed: Command failed: git -c core.longpaths=true ${sub} ${url}\n${stderr}`;
+
+const URL = 'https://github.com/acme/kb.git';
+
+describe('classifyGitFailure', () => {
+  it('credentials rejected', () => {
+    expect(
+      classifyGitFailure(
+        gitFailed('ls-remote', URL, "remote: Invalid username or password.\nfatal: Authentication failed for 'https://github.com/acme/kb.git/'"),
+      ).kind,
+    ).toBe('credentials-rejected');
+    expect(
+      classifyGitFailure(
+        gitFailed('ls-remote', URL, "fatal: could not read Username for 'https://github.com': terminal prompts disabled"),
+      ).kind,
+    ).toBe('credentials-rejected');
+    expect(
+      classifyGitFailure(gitFailed('ls-remote', 'https://gitlab.com/acme/kb.git', 'remote: HTTP Basic: Access denied')).kind,
+    ).toBe('credentials-rejected');
+  });
+
+  it('repository not found', () => {
+    expect(
+      classifyGitFailure(
+        gitFailed('ls-remote', URL, "remote: Repository not found.\nfatal: repository 'https://github.com/acme/kb.git/' not found"),
+      ).kind,
+    ).toBe('not-found');
+  });
+
+  it('host unreachable', () => {
+    expect(
+      classifyGitFailure(
+        gitFailed('ls-remote', 'https://nope.invalid/kb.git', "fatal: unable to access 'https://nope.invalid/kb.git/': Could not resolve host: nope.invalid"),
+      ).kind,
+    ).toBe('unreachable');
+    expect(
+      classifyGitFailure(
+        gitFailed('ls-remote', 'https://127.0.0.1:1/kb.git', "fatal: unable to access 'https://127.0.0.1:1/kb.git/': Failed to connect to 127.0.0.1 port 1: Connection refused"),
+      ).kind,
+    ).toBe('unreachable');
+    expect(classifyGitFailure('git clone failed: Command failed: git clone … ETIMEDOUT').kind).toBe('unreachable');
+  });
+
+  it('write refused: a token that can read but not push', () => {
+    // GitHub, classic token without `repo` write / fine-grained without contents:write.
+    expect(
+      classifyGitFailure(
+        gitFailed('push', 'origin main', "remote: Permission to acme/kb.git denied to x-access-token.\nfatal: unable to access 'https://github.com/acme/kb.git/': The requested URL returned error: 403"),
+      ).kind,
+    ).toBe('write-refused');
+    expect(
+      classifyGitFailure(
+        gitFailed('push', 'origin main', "remote: Write access to repository not granted.\nfatal: unable to access 'https://github.com/acme/kb.git/': The requested URL returned error: 403"),
+      ).kind,
+    ).toBe('write-refused');
+    // A bare 403 on a push is a refused write: ls-remote already accepted these credentials.
+    expect(
+      classifyGitFailure(gitFailed('push', 'origin main', 'error: RPC failed; HTTP 403 curl 22 The requested URL returned error: 403')).kind,
+    ).toBe('write-refused');
+  });
+
+  it('push refused by host policy: branch protection or a hook', () => {
+    expect(
+      classifyGitFailure(
+        gitFailed('push', 'origin main', 'remote: error: GH006: Protected branch update failed for refs/heads/main.\n ! [remote rejected] main -> main (protected branch hook declined)'),
+      ).kind,
+    ).toBe('push-refused-by-policy');
+    // GitLab says "not allowed to push" too — the policy reading must win.
+    expect(
+      classifyGitFailure(
+        gitFailed('push', 'origin main', 'remote: GitLab: You are not allowed to push code to protected branches on this project.\n ! [remote rejected] main -> main (pre-receive hook declined)'),
+      ).kind,
+    ).toBe('push-refused-by-policy');
+  });
+
+  it('startup step failed, naming the step', () => {
+    const failure = classifyGitFailure('KB startup step "groups-to-plugins" failed: Cannot read properties of undefined');
+    expect(failure.kind).toBe('step-failed');
+    expect(failure.cause).toContain('"groups-to-plugins"');
+    expect(classifyGitFailure('KB startup step "template-files" stopped the boot: roles.yaml is not valid YAML').kind).toBe(
+      'step-failed',
+    );
+  });
+
+  it('a step whose own message merely contains a git-ish word is still a step failure', () => {
+    expect(classifyGitFailure('KB startup step "template-files" failed: template file not found').kind).toBe('step-failed');
+  });
+
+  it('a step that failed in git is classified by what git said', () => {
+    expect(
+      classifyGitFailure(
+        `KB startup step "migrate" failed: ${gitFailed('push', 'origin main', "remote: Permission to acme/kb.git denied to bot.\nfatal: unable to access 'x': The requested URL returned error: 403")}`,
+      ).kind,
+    ).toBe('write-refused');
+  });
+
+  it('unknown, pointing at the server log — not at re-saving or restarting', () => {
+    const failure = classifyGitFailure('KB remote is empty and cannot be seeded: no initial Admin was supplied (ADMIN_EMAIL).');
+    expect(failure.kind).toBe('unknown');
+    expect(failure.cause).toMatch(/server log/i);
+    expect(failure.cause).not.toMatch(/sav|restart/i);
+  });
+
+  it('does not read status digits out of a URL', () => {
+    expect(
+      classifyGitFailure(gitFailed('ls-remote', 'https://example.com/acme/403-archive.git', 'fatal: something odd happened')).kind,
+    ).toBe('unknown');
+  });
+
+  it('does not read status digits out of a port number', () => {
+    for (const port of ['401', '403', '404']) {
+      for (const sub of ['ls-remote', 'push']) {
+        const text = gitFailed(
+          sub,
+          `https://git.example.com:${port}/kb.git`,
+          `fatal: unable to access 'x': Failed to connect to git.example.com port ${port}: Connection refused`,
+        );
+        expect(classifyGitFailure(text).kind).toBe('unreachable');
+      }
+    }
+  });
+
+  it('never quotes the raw text in the cause', () => {
+    const raw = gitFailed('ls-remote', URL, 'fatal: weird-marker-7f3a');
+    for (const text of [raw, `KB startup step "s" failed: ${raw}`]) {
+      expect(classifyGitFailure(text).cause).not.toContain('weird-marker-7f3a');
+    }
+  });
+
+  it("knows the connection check's wordings too — there is no second table", () => {
+    expect(
+      classifyGitFailure("fatal: could not read Password for 'https://x-access-token@github.com': terminal prompts disabled").kind,
+    ).toBe('credentials-rejected');
+    expect(
+      classifyGitFailure('remote: Invalid username or token. Password authentication is not supported for Git operations.').kind,
+    ).toBe('credentials-rejected');
+    expect(
+      classifyGitFailure('fatal: unable to access: gnutls_handshake() failed: The TLS connection was non-properly terminated.').kind,
+    ).toBe('unreachable');
+    expect(
+      classifyGitFailure("remote: TF401027: You need the Git 'GenericContribute' permission to perform this action.").kind,
+    ).toBe('write-refused');
+    expect(
+      classifyGitFailure('remote: Your credentials lack one or more required privilege scopes.').kind,
+    ).toBe('write-refused');
+  });
+
+  it('a write: a bare 403/404 or a generic refusal is the push refused; authentication still reads as credentials', () => {
+    const write = { operation: 'write' } as const;
+    const returned = (status: number) =>
+      `fatal: unable to access 'https://git.example.com/kb.git/': The requested URL returned error: ${status}`;
+    expect(classifyGitFailure(returned(403), write).kind).toBe('write-refused');
+    expect(classifyGitFailure(returned(404), write).kind).toBe('write-refused');
+    expect(classifyGitFailure(`remote: Forbidden\n${returned(403)}`, write).kind).toBe('write-refused');
+    expect(classifyGitFailure(returned(401), write).kind).toBe('credentials-rejected');
+    expect(classifyGitFailure('remote: HTTP Basic: Access denied', write).kind).toBe('credentials-rejected');
+    // The same statuses on a read: the login refused, or no such repository.
+    expect(classifyGitFailure(returned(403)).kind).toBe('credentials-rejected');
+    expect(classifyGitFailure(returned(404)).kind).toBe('not-found');
+  });
+
+  it('failureOf prefers the classification a failure carries over its scrubbed message', () => {
+    const carried = classifyGitFailure(gitFailed('push', 'origin main', 'remote: Permission to acme/kb.git denied to bot.'));
+    expect(carried.kind).toBe('write-refused');
+    expect(failureOf(new ClassifiedFailure('git push failed: *** ***', carried))).toEqual(carried);
+    // Anything else is read from its text.
+    expect(failureOf(new Error('KB startup step "s" failed: boom')).kind).toBe('step-failed');
+    expect(failureOf('Could not resolve host').kind).toBe('unreachable');
+  });
+
+  it('every cause is one sentence', () => {
+    const samples = [
+      'Authentication failed',
+      'Repository not found',
+      'Could not resolve host',
+      'git push failed: Permission to a/b denied',
+      'pre-receive hook declined',
+      'KB startup step "x" failed: boom',
+      'boom',
+    ];
+    for (const s of samples) {
+      const { cause } = classifyGitFailure(s);
+      // One terminal full stop, at the end.
+      expect(cause.trim().endsWith('.')).toBe(true);
+      expect(cause.replace(/\([^)]*\)/g, '').slice(0, -1)).not.toMatch(/\.\s/);
+    }
+  });
+});