@bevel-software/platform-core-backend 0.1.0

package/src/modules/workflow/__tests__/pending-commits.worker.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { ISystemNoticeSink } from '../pending-commits.worker.js';
+import {
+  N_RECOVERY,
+  N_TRANSIENT,
+  PendingCommitsWorker,
+  type RecoveryAgentRunner,
+  type WorkflowCommitDriver,
+  type WorkspaceProvider,
+} from '../pending-commits.worker.js';
+import type {
+  PendingCommit,
+  PendingCommitsService,
+} from '../pending-commits.service.js';
+
+/**
+ * Unit tests for the queue-draining worker. The service + workflow layers
+ * have their own tests; here we focus on the *decision tree* the worker
+ * applies per claimed row:
+ *
+ *   - Success → markSucceeded, nothing else.
+ *   - Failure inside transient budget → markTransientFailure, no recovery agent.
+ *   - Failure outside transient budget but inside recovery budget → spawn agent.
+ *   - Failure outside recovery budget → mark needs_attention + send feedback notice.
+ *
+ * We never actually start the polling loop (`start()`) — `drainOnce()` is
+ * the seam the tests step through. That avoids fake-timer choreography
+ * and keeps the test fast.
+ */
+
+const RECOVERY_BOT = { id: 'recovery-bot-id', email: 'recovery-bot@bevel.local', name: 'Recovery Bot' };
+
+function makeRow(overrides: Partial<PendingCommit> = {}): PendingCommit {
+  return {
+    id: overrides.id ?? 'row-1',
+    workspaceId: overrides.workspaceId ?? 'ws-1',
+    branch: overrides.branch ?? 'feat/x',
+    path: overrides.path ?? 'Foo.md',
+    authorEmail: overrides.authorEmail ?? 'alice@example.com',
+    authorName: overrides.authorName ?? 'Alice',
+    queuedAt: overrides.queuedAt ?? new Date('2026-01-01T00:00:00Z'),
+    status: overrides.status ?? 'running',
+    attempts: overrides.attempts ?? 0,
+    recoveryAgentRuns: overrides.recoveryAgentRuns ?? 0,
+    lastAttemptedAt: overrides.lastAttemptedAt ?? null,
+    lastError: overrides.lastError ?? null,
+  };
+}
+
+function makeService(): PendingCommitsService {
+  return {
+    enqueue: vi.fn().mockResolvedValue(undefined),
+    claimNext: vi.fn().mockResolvedValue(null),
+    markSucceeded: vi.fn().mockResolvedValue(undefined),
+    markTransientFailure: vi.fn().mockResolvedValue(undefined),
+    markRecoveryStarted: vi.fn().mockResolvedValue(undefined),
+    markNeedsAttention: vi.fn().mockResolvedValue(undefined),
+    listNeedsAttention: vi.fn().mockResolvedValue([]),
+    countPending: vi.fn().mockResolvedValue(0),
+    startupReconcile: vi.fn().mockResolvedValue(undefined),
+  } as unknown as PendingCommitsService;
+}
+
+function makeWorkspaces(): WorkspaceProvider {
+  return {
+    knownWorkspaces: () => [{ id: 'ws-1', branch: 'feat/x' }],
+  };
+}
+
+function makeFeedback(): ISystemNoticeSink {
+  return { send: vi.fn().mockResolvedValue(undefined) } as unknown as ISystemNoticeSink;
+}
+
+describe('PendingCommitsWorker.drainOnce', () => {
+  let service: PendingCommitsService;
+  let workflow: WorkflowCommitDriver & {
+    runPendingCommit: ReturnType<typeof vi.fn>;
+  };
+  let recoveryAgent: RecoveryAgentRunner & { run: ReturnType<typeof vi.fn> };
+  let feedback: ISystemNoticeSink & { send: ReturnType<typeof vi.fn> };
+  let worker: PendingCommitsWorker;
+
+  beforeEach(() => {
+    service = makeService();
+    workflow = { runPendingCommit: vi.fn() } as never;
+    recoveryAgent = { run: vi.fn() } as never;
+    feedback = makeFeedback() as never;
+    worker = new PendingCommitsWorker({
+      service,
+      workflow,
+      recoveryAgent,
+      feedback,
+      workspaces: makeWorkspaces(),
+      recoveryBot: RECOVERY_BOT,
+      now: () => new Date('2026-01-01T00:01:00Z'),
+    });
+    // drainOnce checks `this.running` against the per-workspace iterator;
+    // start() sets it true. We don't want the polling loop, just the
+    // single-pass drain, so flip the flag manually.
+    (worker as unknown as { running: boolean }).running = true;
+  });
+
+  it('happy path: claims row, runs commit, marks succeeded — no other branches taken', async () => {
+    const row = makeRow();
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    workflow.runPendingCommit.mockResolvedValueOnce(undefined);
+
+    await worker.drainOnce();
+
+    expect(service.claimNext).toHaveBeenCalledWith('ws-1', expect.any(Date));
+    expect(workflow.runPendingCommit).toHaveBeenCalledWith(
+      'ws-1',
+      'feat/x',
+      'Foo.md',
+      expect.objectContaining<Partial<AuthUser>>({ email: 'alice@example.com', name: 'Alice' }),
+    );
+    expect(service.markSucceeded).toHaveBeenCalledWith('row-1');
+    expect(service.markTransientFailure).not.toHaveBeenCalled();
+    expect(service.markRecoveryStarted).not.toHaveBeenCalled();
+    expect(service.markNeedsAttention).not.toHaveBeenCalled();
+    expect(recoveryAgent.run).not.toHaveBeenCalled();
+    expect(feedback.send).not.toHaveBeenCalled();
+  });
+
+  it('skips work entirely when claimNext returns null (idle queue)', async () => {
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(null);
+
+    await worker.drainOnce();
+
+    expect(workflow.runPendingCommit).not.toHaveBeenCalled();
+    expect(service.markSucceeded).not.toHaveBeenCalled();
+  });
+
+  it('transient failure (within budget) records the error and does NOT spawn recovery', async () => {
+    // attempts=0 → next attempt would be 1, which is < N_TRANSIENT (3).
+    const row = makeRow({ attempts: 0 });
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    workflow.runPendingCommit.mockRejectedValueOnce(new Error('transient git error'));
+
+    await worker.drainOnce();
+
+    expect(service.markTransientFailure).toHaveBeenCalledWith('row-1', 'transient git error');
+    expect(service.markRecoveryStarted).not.toHaveBeenCalled();
+    expect(recoveryAgent.run).not.toHaveBeenCalled();
+    expect(service.markNeedsAttention).not.toHaveBeenCalled();
+    expect(feedback.send).not.toHaveBeenCalled();
+  });
+
+  it('exhausting transient budget spawns the recovery agent (within recovery budget)', async () => {
+    // attempts = N_TRANSIENT - 1 → next attempt would equal N_TRANSIENT,
+    // crossing the budget. recoveryAgentRuns=0 → still within recovery budget.
+    const row = makeRow({ attempts: N_TRANSIENT - 1, recoveryAgentRuns: 0 });
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    workflow.runPendingCommit.mockRejectedValueOnce(new Error('cannot push: needs human'));
+    recoveryAgent.run.mockResolvedValueOnce(undefined);
+
+    await worker.drainOnce();
+
+    expect(service.markTransientFailure).not.toHaveBeenCalled();
+    expect(service.markRecoveryStarted).toHaveBeenCalledWith('row-1');
+    expect(recoveryAgent.run).toHaveBeenCalledWith({
+      workspaceId: 'ws-1',
+      branch: 'feat/x',
+      path: 'Foo.md',
+      lastError: 'cannot push: needs human',
+      originalAuthorEmail: 'alice@example.com',
+    });
+    expect(service.markNeedsAttention).not.toHaveBeenCalled();
+    expect(feedback.send).not.toHaveBeenCalled();
+  });
+
+  it('a recovery-agent crash does not abort the worker — the row stays pending for the next pass', async () => {
+    const row = makeRow({ attempts: N_TRANSIENT - 1, recoveryAgentRuns: 0 });
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    workflow.runPendingCommit.mockRejectedValueOnce(new Error('cannot push'));
+    recoveryAgent.run.mockRejectedValueOnce(new Error('codemode wiring broken'));
+
+    // No throw — the worker swallows the agent crash and moves on.
+    await expect(worker.drainOnce()).resolves.toBeUndefined();
+    // markRecoveryStarted still fired (we incremented the agent counter
+    // for this attempt), so the row will hit needs_attention naturally
+    // after N_RECOVERY tries.
+    expect(service.markRecoveryStarted).toHaveBeenCalled();
+    expect(service.markNeedsAttention).not.toHaveBeenCalled();
+  });
+
+  it('exhausting both budgets marks needs_attention and emits a system feedback notice', async () => {
+    // attempts at the transient ceiling AND recovery already ran N_RECOVERY
+    // times: nothing left to try. Escalate.
+    const row = makeRow({
+      attempts: N_TRANSIENT - 1,
+      recoveryAgentRuns: N_RECOVERY,
+    });
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    workflow.runPendingCommit.mockRejectedValueOnce(new Error('unrecoverable'));
+
+    await worker.drainOnce();
+
+    expect(service.markNeedsAttention).toHaveBeenCalledWith('row-1', 'unrecoverable');
+    expect(recoveryAgent.run).not.toHaveBeenCalled();
+    expect(feedback.send).toHaveBeenCalledTimes(1);
+    const call = (feedback.send as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(call.source).toBe('system');
+    expect(call.user).toEqual(RECOVERY_BOT);
+    // Body should carry enough context for an admin to investigate without
+    // needing to consult the DB.
+    expect(call.message).toContain('Terminal commit failure');
+    expect(call.message).toContain('ws-1');
+    expect(call.message).toContain('Foo.md');
+    expect(call.message).toContain('unrecoverable');
+    expect(call.message).toContain('alice@example.com');
+  });
+
+  it('a feedback-sink failure does not throw — the row stays needs_attention regardless', async () => {
+    const row = makeRow({ attempts: N_TRANSIENT - 1, recoveryAgentRuns: N_RECOVERY });
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    workflow.runPendingCommit.mockRejectedValueOnce(new Error('unrecoverable'));
+    (feedback.send as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('feedback DB down'));
+
+    await expect(worker.drainOnce()).resolves.toBeUndefined();
+    expect(service.markNeedsAttention).toHaveBeenCalled();
+  });
+});
+
+describe('PendingCommitsWorker lifecycle', () => {
+  it('start() is idempotent; stop() awaits the in-flight pass without throwing', async () => {
+    const worker = new PendingCommitsWorker({
+      service: makeService(),
+      workflow: { runPendingCommit: vi.fn() },
+      recoveryAgent: { run: vi.fn() },
+      feedback: makeFeedback(),
+      workspaces: makeWorkspaces(),
+      recoveryBot: RECOVERY_BOT,
+      // Skip the real sleep so stop() returns immediately.
+      sleep: () => Promise.resolve(),
+    });
+    worker.start();
+    worker.start(); // second start is a no-op
+    await expect(worker.stop()).resolves.toBeUndefined();
+    await expect(worker.stop()).resolves.toBeUndefined(); // idempotent
+  });
+});

package/src/modules/workflow/__tests__/preserve-roles-yaml.test.ts

@@ -0,0 +1,308 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+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 type { IAccessControl } from '../../access/access-control.interface.js';
+import { FileLockService } from '../file-lock.service.js';
+import { PendingCommitsService } from '../pending-commits.service.js';
+import { WorkflowService } from '../workflow.service.js';
+import type { Database } from '../../database/connection.js';
+import { RolesYamlPreservationError } from '../workflow.errors.js';
+
+/**
+ * Focused tests for the roles.yaml-preservation guard inside
+ * `mergeChangeRequest`. The security property: a change request can NEVER carry
+ * a roles.yaml change across its merge — if the CR's roles.yaml differs from the
+ * base branch's, the base version is restored on the SOURCE branch (commit +
+ * push) before the merge fires, so the merged diff has no roles.yaml change.
+ * roles.yaml is mutable only via the admin Roles & Members surface.
+ */
+
+const KB_DIR = 'knowledge-base';
+const BASE = 'current-company-state';
+const HEAD = 'mallory/escalate';
+const USER = { id: 'u-mallory', email: 'mallory@x.com', name: 'Mallory' };
+const BASE_ROLES = 'roles:\n  Admin:\n    - admin@x.com\n';
+const ATTACKER_ROLES = 'roles:\n  Admin:\n    - admin@x.com\n    - mallory@x.com\n';
+
+function noopAccessControl(): IAccessControl {
+  return {
+    canWrite: vi.fn(), canWriteBatch: vi.fn(), canRead: vi.fn(), canReadBatch: vi.fn(),
+    eligibleReaders: vi.fn(), canReadAtRef: vi.fn(),
+    canDownload: vi.fn(), canOwner: vi.fn(), eligibleOwners: vi.fn(), eligibleDownloaders: vi.fn(),
+    eligibleWriters: vi.fn(), eligibleWriterEmails: vi.fn(), eligibleOwnerEmails: vi.fn(),
+    grantSources: vi.fn(), invalidate: vi.fn(), findEmailByHash: vi.fn(), kbPrincipals: vi.fn(),
+    validateRolesYaml: vi.fn(), referencesToRole: vi.fn(), canWriteAtRef: vi.fn(),
+    canWriteBatchAtRef: vi.fn(), eligibleWritersAtRef: vi.fn(), eligibleWritersForPathsAtRef: vi.fn(),
+  } as unknown as IAccessControl;
+}
+
+describe('mergeChangeRequest — roles.yaml preservation guard', () => {
+  let root: string;
+  let headRepoDir: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'preserve-roles-'));
+    // The source branch's per-branch workspace, laid out like the real one:
+    // <root>/<encoded-branch>/<kbDir>/roles.yaml
+    headRepoDir = path.join(root, encodeURIComponent(HEAD), KB_DIR);
+    await fs.mkdir(headRepoDir, { recursive: true });
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  function makeSvc(opts: {
+    headRoles: string | null;
+    baseRoles: string | null;
+    commitFileResult?: unknown;
+    pushImpl?: () => Promise<void>;
+    getPrResult?: { branch: string; base: string } | null;
+    getPrDetailResult?: unknown;
+    // Simulate a concurrent editor already holding the roles.yaml lock. When set,
+    // acquire returns { acquired: false } and the restore must fail-closed.
+    lockHeldBy?: string;
+  }) {
+    const ac = noopAccessControl();
+    const reviewWorkflow = {
+      mergePr: vi.fn().mockResolvedValue({ prNumber: 1, sha: 'merged', mergedAt: 't' }),
+    } as unknown as IReviewWorkflowService;
+
+    const workspaceService = {
+      getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch) })),
+      getWorkspacePath: vi.fn(async (id: string) => path.join(root, id)),
+    } as unknown as WorkspaceService;
+
+    const git = {
+      fetch: vi.fn().mockResolvedValue(undefined),
+      pull: vi.fn().mockResolvedValue(undefined),
+      // Resolve roles.yaml at origin/<ref> from the per-test content.
+      readFileAtRef: vi.fn(async (_ws: string, ref: string) =>
+        ref === `origin/${BASE}` ? opts.baseRoles : ref === `origin/${HEAD}` ? opts.headRoles : null,
+      ),
+      commitFile: vi.fn().mockResolvedValue(
+        'commitFileResult' in opts ? opts.commitFileResult : { sha: 'preserve-sha' },
+      ),
+      push: vi.fn(opts.pushImpl ?? (async () => undefined)),
+    } as unknown as GitService;
+
+    const prs = {
+      getPr: vi.fn().mockResolvedValue(
+        opts.getPrResult === undefined ? { branch: HEAD, base: BASE } : opts.getPrResult,
+      ),
+      // After a preservation commit, mergeChangeRequest refreshes the CR detail
+      // (fresh headSha + approvals) before merging. Deterministic stub.
+      getPrDetail: vi.fn().mockResolvedValue(
+        'getPrDetailResult' in opts
+          ? opts.getPrDetailResult
+          : { headSha: 'sha-after-preserve', approvals: [], state: 'open', title: 'Title', base: BASE },
+      ),
+      invalidateDetailCache: vi.fn(),
+    } as unknown as PullRequestService;
+
+    // The restore holds the SAME per-file lock a concurrent editor would (keyed
+    // on `<kbDir>/roles.yaml`), so a live edit can't race the neutralisation.
+    const acquire = vi.fn(async () =>
+      opts.lockHeldBy
+        ? { acquired: false as const, lock: { holderName: opts.lockHeldBy } }
+        : { acquired: true as const, lock: { holderName: USER.name } },
+    );
+    const release = vi.fn(async () => undefined);
+    const fileLocks = { acquire, release } as unknown as FileLockService;
+
+    const svc = new WorkflowService(
+      {} as unknown as Database,
+      git, prs, reviewWorkflow, workspaceService, ac,
+      fileLocks, {} as unknown as PendingCommitsService,
+      KB_DIR,
+    );
+    // Conflicts are now surfaced by the local merge inside `reviewWorkflow.mergePr`
+    // (mocked to resolve here), so there's no provider "mergeable" pre-check to stub.
+    return { svc, git, prs, reviewWorkflow, fileLocks };
+  }
+
+  async function merge(svc: WorkflowService) {
+    return svc.mergeChangeRequest(1, USER, 'sha', [], 'open', 'Title', BASE, 'w1', { bypass: false });
+  }
+
+  it('no-ops when the CR does not change roles.yaml (identical content)', async () => {
+    const { svc, git, reviewWorkflow } = makeSvc({ headRoles: BASE_ROLES, baseRoles: BASE_ROLES });
+    await merge(svc);
+    // No restore write/commit/push, but the merge still proceeds.
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+    expect(reviewWorkflow.mergePr).toHaveBeenCalledTimes(1);
+  });
+
+  it('no-ops when neither base nor head has a roles.yaml (both absent)', async () => {
+    const { svc, git, reviewWorkflow } = makeSvc({ headRoles: null, baseRoles: null });
+    await merge(svc);
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(reviewWorkflow.mergePr).toHaveBeenCalledTimes(1);
+  });
+
+  it('restores base roles.yaml on the source branch when the CR changed it (escalation guard)', async () => {
+    // Seed the source workspace with the ATTACKER version, as it would be after
+    // reset-to-origin of the CR head.
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), ATTACKER_ROLES);
+    const { svc, git, reviewWorkflow, fileLocks } = makeSvc({ headRoles: ATTACKER_ROLES, baseRoles: BASE_ROLES });
+
+    await merge(svc);
+
+    // The restore ran under the SAME per-file lock a human/agent editor uses,
+    // keyed on the workspace-relative `<kbDir>/roles.yaml` path on the SOURCE
+    // branch — so a concurrent edit can't slip past the neutralisation.
+    expect(fileLocks.acquire).toHaveBeenCalledWith(
+      encodeURIComponent(HEAD),
+      HEAD,
+      `${KB_DIR}/roles.yaml`,
+      USER,
+    );
+    // The working-tree roles.yaml was rewritten back to the BASE version...
+    const onDisk = await fs.readFile(path.join(headRepoDir, 'roles.yaml'), 'utf-8');
+    expect(onDisk).toBe(BASE_ROLES);
+    // ...committed (single-path, not `add -A`) + pushed on the SOURCE branch...
+    expect(git.commitFile).toHaveBeenCalledWith(
+      encodeURIComponent(HEAD),
+      USER,
+      'roles.yaml',
+      expect.stringMatching(/preserve official roles\.yaml/i),
+      true,
+    );
+    expect(git.push).toHaveBeenCalledWith(encodeURIComponent(HEAD), USER);
+    // ...the lock was released after the inline commit...
+    expect(fileLocks.release).toHaveBeenCalledWith(
+      encodeURIComponent(HEAD),
+      HEAD,
+      `${KB_DIR}/roles.yaml`,
+      USER,
+    );
+    // ...and only THEN does the merge proceed.
+    expect(reviewWorkflow.mergePr).toHaveBeenCalledTimes(1);
+  });
+
+  it('ABORTS the merge when roles.yaml is locked by a concurrent editor (fail-closed)', async () => {
+    // A same-branch editor holds the roles.yaml lock. The restore must NOT race
+    // it — acquire returns { acquired: false }, so the merge aborts rather than
+    // writing over (or being overwritten by) the live edit.
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), ATTACKER_ROLES);
+    const { svc, git, reviewWorkflow } = makeSvc({
+      headRoles: ATTACKER_ROLES,
+      baseRoles: BASE_ROLES,
+      lockHeldBy: 'Someone Else',
+    });
+
+    await expect(merge(svc)).rejects.toBeInstanceOf(RolesYamlPreservationError);
+    // Nothing was written/committed/pushed, and the merge never ran.
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+    expect(reviewWorkflow.mergePr).not.toHaveBeenCalled();
+    // The on-disk attacker version is untouched — the lock holder's edit stands.
+    const onDisk = await fs.readFile(path.join(headRepoDir, 'roles.yaml'), 'utf-8');
+    expect(onDisk).toBe(ATTACKER_ROLES);
+  });
+
+  it('restores by deleting roles.yaml when the base branch has none', async () => {
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), ATTACKER_ROLES);
+    const { svc, git } = makeSvc({ headRoles: ATTACKER_ROLES, baseRoles: null });
+
+    await merge(svc);
+
+    await expect(fs.access(path.join(headRepoDir, 'roles.yaml'))).rejects.toThrow();
+    expect(git.commitFile).toHaveBeenCalled();
+    expect(git.push).toHaveBeenCalled();
+  });
+
+  it('ABORTS the merge (RolesYamlPreservationError) if the restore push fails', async () => {
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), ATTACKER_ROLES);
+    const { svc, reviewWorkflow } = makeSvc({
+      headRoles: ATTACKER_ROLES,
+      baseRoles: BASE_ROLES,
+      pushImpl: async () => { throw new Error('push rejected: non-fast-forward'); },
+    });
+
+    await expect(merge(svc)).rejects.toBeInstanceOf(RolesYamlPreservationError);
+    // Fail-closed: the merge must NOT have run.
+    expect(reviewWorkflow.mergePr).not.toHaveBeenCalled();
+  });
+
+  it('ABORTS the merge if the CR (PR) cannot be resolved', async () => {
+    const { svc, reviewWorkflow } = makeSvc({ headRoles: BASE_ROLES, baseRoles: BASE_ROLES, getPrResult: null });
+    await expect(merge(svc)).rejects.toBeInstanceOf(RolesYamlPreservationError);
+    expect(reviewWorkflow.mergePr).not.toHaveBeenCalled();
+  });
+
+  it('refreshes the merge inputs from the updated PR head after a preservation commit', async () => {
+    // The restore commit advances the source head, so the caller's headSha/approvals
+    // (resolved pre-preservation) go stale. mergeChangeRequest must re-resolve them
+    // from the live PR before merging, not forward the originals.
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), ATTACKER_ROLES);
+    const { svc, prs, reviewWorkflow } = makeSvc({ headRoles: ATTACKER_ROLES, baseRoles: BASE_ROLES });
+
+    await merge(svc);
+
+    expect(prs.getPrDetail).toHaveBeenCalledWith(1, expect.objectContaining({ fresh: true }));
+    // mergePr is called with the REFRESHED head sha, not the original 'sha'.
+    expect(reviewWorkflow.mergePr).toHaveBeenCalledWith(
+      1, USER, 'sha-after-preserve', [], 'open', 'Title', BASE, 'w1', { bypass: false },
+    );
+  });
+
+  it('does NOT refresh (keeps the caller inputs) when the CR does not touch roles.yaml', async () => {
+    // No preservation commit → no head advance → nothing to refresh; the original
+    // headSha/approvals flow straight through.
+    const { svc, prs, reviewWorkflow } = makeSvc({ headRoles: BASE_ROLES, baseRoles: BASE_ROLES });
+    await merge(svc);
+    expect(prs.getPrDetail).not.toHaveBeenCalled();
+    expect(reviewWorkflow.mergePr).toHaveBeenCalledWith(
+      1, USER, 'sha', [], 'open', 'Title', BASE, 'w1', { bypass: false },
+    );
+  });
+
+  it('ABORTS the merge when the restore produces no commit while origin still diverges (fail-closed)', async () => {
+    // origin/base vs origin/head differ (restore required), but commitFile is a
+    // no-op — e.g. the local checkout is out of sync and already matched base.
+    // origin/head would still carry the divergent roles.yaml, so this must fail
+    // closed rather than return "nothing to do".
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), BASE_ROLES);
+    const { svc, git, reviewWorkflow } = makeSvc({
+      headRoles: ATTACKER_ROLES,
+      baseRoles: BASE_ROLES,
+      commitFileResult: null,
+    });
+    await expect(merge(svc)).rejects.toBeInstanceOf(RolesYamlPreservationError);
+    expect(git.push).not.toHaveBeenCalled();
+    expect(reviewWorkflow.mergePr).not.toHaveBeenCalled();
+  });
+
+  it('ABORTS the merge when the post-preservation CR detail cannot be reloaded (fail-closed)', async () => {
+    // After a preservation commit advances the head, the gate inputs must be
+    // re-resolved. If the fresh detail is unavailable, abort — never fall back to
+    // the stale headSha/approvals.
+    await fs.writeFile(path.join(headRepoDir, 'roles.yaml'), ATTACKER_ROLES);
+    const { svc, reviewWorkflow } = makeSvc({
+      headRoles: ATTACKER_ROLES,
+      baseRoles: BASE_ROLES,
+      getPrDetailResult: null,
+    });
+    await expect(merge(svc)).rejects.toBeInstanceOf(RolesYamlPreservationError);
+    expect(reviewWorkflow.mergePr).not.toHaveBeenCalled();
+  });
+
+  it('ABORTS the merge when reading roles.yaml fails for a non-absence reason (fail-closed)', async () => {
+    // readFileAtRef now rethrows real git errors (only true absence maps to null),
+    // so a fatal read must surface as RolesYamlPreservationError — never be mistaken
+    // for "roles.yaml absent" and waved through.
+    const { svc, git, reviewWorkflow } = makeSvc({ headRoles: ATTACKER_ROLES, baseRoles: BASE_ROLES });
+    (git.readFileAtRef as unknown as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('git show failed: fatal: unable to read tree object'),
+    );
+    await expect(merge(svc)).rejects.toBeInstanceOf(RolesYamlPreservationError);
+    expect(reviewWorkflow.mergePr).not.toHaveBeenCalled();
+  });
+});

package/src/modules/workflow/__tests__/sanitize-error.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeError } from '../sanitize-error.js';
+
+describe('sanitizeError', () => {
+  it('returns String(err) for non-Error throws', () => {
+    expect(sanitizeError('plain string')).toBe('plain string');
+    expect(sanitizeError(42)).toBe('42');
+    expect(sanitizeError(null)).toBe('null');
+  });
+
+  it('extracts err.message for Error instances and drops the stack', () => {
+    const err = new Error('boom');
+    err.stack = 'Error: boom\n  at /secret/path/file.ts:1:1\n  authorization: bearer abc';
+    expect(sanitizeError(err)).toBe('boom');
+  });
+
+  it('collapses whitespace to a single line', () => {
+    expect(sanitizeError(new Error('line1\nline2\n\tline3'))).toBe('line1 line2 line3');
+  });
+
+  it('redacts the user:pass component of a credentialed URL but keeps the host', () => {
+    const msg = "fatal: unable to access 'https://x-access-token:ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA@github.com/acme/repo.git/'";
+    const out = sanitizeError(new Error(msg));
+    expect(out).not.toContain('ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA');
+    expect(out).not.toContain('x-access-token');
+    expect(out).toContain('[REDACTED]@');
+    expect(out).toContain('github.com');
+  });
+
+  it('redacts Authorization: Bearer headers', () => {
+    const out = sanitizeError(
+      new Error('http 401 (Authorization: Bearer sk-AAAAAAAAAAAAAAAAAAAA)'),
+    );
+    expect(out).not.toContain('sk-AAAAAAAAAAAAAAAAAAAA');
+    expect(out).toContain('[REDACTED]');
+  });
+
+  it('redacts token= / secret= / api_key= style key-value pairs', () => {
+    const out = sanitizeError(new Error('curl https://host?token=AAAAAAAAAAAAAAAA secret=BBBBBBBBBBBBBBBB'));
+    expect(out).not.toContain('AAAAAAAAAAAAAAAA');
+    expect(out).not.toContain('BBBBBBBBBBBBBBBB');
+    expect(out.match(/\[REDACTED\]/g)?.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('redacts long bare hex blobs that look like tokens', () => {
+    const out = sanitizeError(new Error('sha=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'));
+    expect(out).not.toContain('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6');
+  });
+
+  it('redacts GitHub PAT prefixes (ghp_, github_pat_)', () => {
+    expect(sanitizeError(new Error('use ghp_abcdef1234567890'))).not.toContain('ghp_abcdef1234567890');
+    expect(sanitizeError(new Error('use github_pat_11ABCDEFGH_xxx'))).not.toContain('github_pat_11ABCDEFGH_xxx');
+  });
+
+  it('truncates messages longer than 200 chars with an ellipsis', () => {
+    const long = 'x'.repeat(500);
+    const out = sanitizeError(new Error(long));
+    expect(out.length).toBeLessThanOrEqual(200);
+    expect(out.endsWith('…')).toBe(true);
+  });
+
+  it('is idempotent on already-sanitised text', () => {
+    const once = sanitizeError(new Error('Authorization: Bearer abc; token=def123'));
+    const twice = sanitizeError(once);
+    expect(twice).toBe(once);
+  });
+});

package/src/modules/workflow/__tests__/session-ontology.policy.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { recordTouch, decideWrite } from '../session-ontology.policy.js';
+
+const PRODUCT = 'KnowledgeBase/Product';
+const PLATFORM = 'KnowledgeBase/Platform';
+const GTM = 'KnowledgeBase/GTM';
+
+describe('recordTouch', () => {
+  it('adds a named ontology to the set', () => {
+    expect([...recordTouch(new Set(), PRODUCT)]).toEqual([PRODUCT]);
+  });
+
+  it('adds nothing for a neutral touch', () => {
+    expect([...recordTouch(new Set([PRODUCT]), null)]).toEqual([PRODUCT]);
+  });
+
+  it('accumulates across ontologies', () => {
+    const a = recordTouch(new Set(), PRODUCT);
+    const b = recordTouch(a, PLATFORM);
+    expect(new Set(b)).toEqual(new Set([PRODUCT, PLATFORM]));
+  });
+
+  it('does not mutate the input set', () => {
+    const input = new Set([PRODUCT]);
+    recordTouch(input, PLATFORM);
+    expect([...input]).toEqual([PRODUCT]);
+  });
+});
+
+describe('decideWrite', () => {
+  it('allows a write to a neutral path regardless of touched set', () => {
+    expect(decideWrite(new Set([PRODUCT, PLATFORM]), null)).toEqual({ allow: true });
+  });
+
+  it('allows a write when the session has touched nothing yet', () => {
+    expect(decideWrite(new Set(), PRODUCT)).toEqual({ allow: true });
+  });
+
+  it('allows a write to the single ontology the session is confined to', () => {
+    expect(decideWrite(new Set([PRODUCT]), PRODUCT)).toEqual({ allow: true });
+  });
+
+  it('blocks a write to a different ontology when confined to one (different-ontology)', () => {
+    expect(decideWrite(new Set([PRODUCT]), PLATFORM)).toEqual({
+      allow: false,
+      reason: 'different-ontology',
+      touched: [PRODUCT],
+      attempted: PLATFORM,
+    });
+  });
+
+  it('blocks ALL writes once the session has touched two ontologies (multi-ontology)', () => {
+    // Reading across ontologies poisons writes — even a write back into Product.
+    expect(decideWrite(new Set([PRODUCT, PLATFORM]), PRODUCT)).toEqual({
+      allow: false,
+      reason: 'multi-ontology',
+      touched: [PLATFORM, PRODUCT],
+      attempted: PRODUCT,
+    });
+    expect(decideWrite(new Set([PRODUCT, PLATFORM]), GTM).allow).toBe(false);
+  });
+});