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

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

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

package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts

@@ -42,6 +42,13 @@ const workflowService = {
     calls.push(['createBranch', ws, name]);
     return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
   },
+  acquireLock: async (ws: string, branch: string, path: string) => {
+    calls.push(['acquireLock', ws, branch, path]);
+    return { acquired: true, lock: { branch, path, holderUserId: 'user-A', holderName: 'N' } };
+  },
+  releaseLock: async (ws: string, branch: string, path: string) => {
+    calls.push(['releaseLock', ws, branch, path]);
+  },
 } as never;
 const events = {
   emit: (p: unknown) => {
@@ -52,15 +59,18 @@ const events = {
 
 const internalToken = new InternalTokenService({ secret: 's' });
 let httpServer: HttpServer | undefined;
+/** The registry the tools were mounted into, so a test can inspect their definitions. */
+let registryRef: ToolRegistry | undefined;
 
 async function start(): Promise<string> {
   const registry = new ToolRegistry();
+  registryRef = registry;
   const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
   const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
   const toolHandler = createToolHandlerFactory(resolve);
 
   const router = express.Router();
-  registerWorkflowTools(registry, router, toolAuth, toolHandler);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, 'knowledge-base');
   router.use(createManualRoutes(registry, toolAuth));
 
   const app = express();
@@ -190,3 +200,52 @@ describe('registerWorkflowTools', () => {
     expect(external).not.toContain('switch_branch'); // internal-only
   });
 });
+
+describe('save_file and the repository folder', () => {
+  // `save_file` commits whatever is on disk at `path` through the lock
+  // protocol, bypassing the locking filesystem's own guard. A path without the
+  // clone-folder prefix names a file git can never see, so it is refused here,
+  // before a lock is taken, with the same corrected-path message the write
+  // tools give.
+  it('refuses a repo-relative path before taking any lock', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: 'KnowledgeBase/Reviews/PR-12.html',
+      branch: WS,
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('"knowledge-base/KnowledgeBase/Reviews/PR-12.html"');
+    expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
+  });
+
+  it('answers a missing path with a 400, not a crash', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), { branch: WS });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toMatch(/path/i);
+    expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
+  });
+
+  it('schedules a prefixed path as before', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: 'knowledge-base/KnowledgeBase/Reviews/PR-12.html',
+      branch: WS,
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ saved: true, queued: true });
+    expect(calls).toContainEqual(['acquireLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
+    expect(calls).toContainEqual(['releaseLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
+  });
+
+  it('describes the prefix on its path input', async () => {
+    await start();
+    const tools = await registryRef!.listInternal();
+    const def = tools.find((t) => t.name === 'save_file');
+    // `toolDef` wraps a tool's inputs under a single `body` property.
+    const body = (def!.inputs as { properties: { body: { properties: Record<string, { description?: string }> } } }).properties.body;
+    expect(body.properties.path.description).toContain('`knowledge-base/`');
+  });
+});

package/src/modules/workflow/agent-tools/workflow.tools.ts

@@ -6,6 +6,7 @@ import { toolDef, withBranchInput } from '../../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 
 // A function, not a constant: the branch model is applied during boot, and a
 // module-scope capture would freeze this at the empty set that exists before it.
@@ -118,6 +119,8 @@ export function registerWorkflowTools(
   router: Router,
   toolAuth: RequestHandler,
   toolHandler: ToolHandlerFactory,
+  /** The clone folder at the workspace root; `save_file` refuses a path outside it. */
+  kbDirName: string,
 ): void {
   const mount = (spec: {
     name: string;
@@ -221,7 +224,13 @@ export function registerWorkflowTools(
       '`{ saved: false, reason }` rather than throwing. The commit lands asynchronously.',
     inputs: {
       type: 'object',
-      properties: { path: { type: 'string', minLength: 1, description: 'Workspace-relative path (as write_file expects).' } },
+      properties: {
+        path: {
+          type: 'string',
+          minLength: 1,
+          description: `Workspace-relative path, as write_file expects: starts with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`).`,
+        },
+      },
       required: ['path'],
       additionalProperties: false,
     },
@@ -238,6 +247,14 @@ export function registerWorkflowTools(
     handler: async (args, ctx: ToolContext) => {
       const path = args.path as string;
       const branch = args.branch as string;
+      // This tool commits whatever is on disk at `path` through the lock
+      // protocol, bypassing the locking filesystem's own guard. A path without
+      // the clone-folder prefix names a file git can never see: refuse it
+      // before a lock is taken, with the same corrected-path message.
+      if (typeof path !== 'string' || path.length === 0) {
+        throw new ToolError('`path` is required and must be a non-empty string.', 400);
+      }
+      assertInsideRepo(path, kbDirName);
       const workspaceId = workspaceIdForBranch(branch);
       const acquired = await ctx.workflowService.acquireLock(workspaceId, branch, path, ctx.user);
       if (!acquired.acquired) {

package/src/modules/workflow/git/__tests__/git.service.changedFilesForPr.test.ts

@@ -130,6 +130,62 @@ describe('GitService.changedFilesForPr / resolvePrShas', () => {
     expect(baseSha).not.toBe(headSha);
   });
 
+  /**
+   * A change-request detail resolves the SHAs (which fetches both refs) and
+   * then lists the files. `at` pins that listing to the commits just
+   * resolved: no second fetch, and the file list describes exactly the head
+   * the approvals pin against even when a newer push has landed on origin in
+   * between. The default keeps refreshing first.
+   */
+  it('`at` pins the diff to the resolved commits; the default refreshes origin/* first', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+    // The branch is authored in ANOTHER clone, so this workspace only ever
+    // knows it as origin/alice/feature — the production shape, where the
+    // base-branch workspace answers for every request without a local copy.
+    const other = path.join(root, 'other');
+    await runGit(root, ['clone', upstream, other]);
+    await runGit(other, ['checkout', '-b', 'alice/feature']);
+    await fs.writeFile(path.join(other, 'added.md'), 'hello\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'feature work']);
+    await runGit(other, ['push', '-u', 'origin', 'alice/feature']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+    // What the detail does first: resolve (and fetch) the two SHAs.
+    const pinned = await git.resolvePrShas(workspaceId, 'current-company-state', 'alice/feature');
+
+    // A second push lands on origin after the resolution.
+    await fs.writeFile(path.join(other, 'second.md'), 'more\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'more work']);
+    await runGit(other, ['push', 'origin', 'alice/feature']);
+
+    const atPinned = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'alice/feature',
+      { at: pinned },
+    );
+    expect(atPinned.map((f) => f.path)).toEqual(['added.md']);
+
+    const refreshed = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'alice/feature',
+    );
+    expect(refreshed.map((f) => f.path).sort()).toEqual(['added.md', 'second.md']);
+
+    await expect(
+      git.changedFilesForPr(workspaceId, 'current-company-state', 'alice/feature', {
+        at: { baseSha: pinned.baseSha, headSha: 'origin/alice/feature' },
+      }),
+    ).rejects.toThrow(/invalid commit sha/);
+  });
+
   /**
    * roles.yaml can never change through a merge — `preserveBaseRolesYaml`
    * restores the base copy onto the source before every merge — so the review

package/src/modules/workflow/git/__tests__/git.service.commitFile.strayPath.test.ts

@@ -0,0 +1,162 @@
+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 path from 'node:path';
+import os from 'node:os';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+import { WorkflowValidationError } from '../../../../shared/domain-errors.js';
+
+/**
+ * `commitFile` on a path whose bytes sit BESIDE the repository.
+ *
+ * The workspace dir holds the clone as `knowledge-base/`. A caller that
+ * writes a workspace-relative path without that prefix puts the file next to
+ * the clone, where `git status` inside the clone reports it clean. Before,
+ * `commitFile` read that as "nothing to commit" and returned null, so the
+ * write was reported as landed while git never saw it. Now it throws, and the
+ * pending-commits ladder escalates the row instead of dropping it.
+ *
+ * The three honest null cases must survive unchanged: a clean committed path,
+ * a path that exists nowhere (a queued re-apply of a committed deletion), and
+ * a repo-relative path some internal callers pass directly.
+ */
+
+const execFileAsync = promisify(execFile);
+const KB = 'knowledge-base';
+
+const USER: AuthUser = { id: 'u1', email: 'alice@example.com', name: 'Alice' };
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-stray-'));
+}
+
+const GIT_ENV = {
+  ...process.env,
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 't@x.com',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 't@x.com',
+};
+
+async function runGit(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, { cwd, env: GIT_ENV });
+  return stdout.toString().trim();
+}
+
+async function seedWorkspace(root: string, workspaceId: string): Promise<{ workspaceDir: string; repo: string }> {
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, KB);
+  await fs.mkdir(repo, { recursive: true });
+  await runGit(repo, ['init', '-b', 'main']);
+  await runGit(repo, ['config', 'user.email', 't@x.com']);
+  await runGit(repo, ['config', 'user.name', 'Test']);
+  await runGit(repo, ['config', 'gc.auto', '0']);
+  // One committed file so HEAD exists and the "clean path" cases have something to be clean about.
+  await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
+  await fs.writeFile(path.join(repo, 'Knowledge/A.md'), 'a\n');
+  await runGit(repo, ['add', 'Knowledge/A.md']);
+  await runGit(repo, ['commit', '-m', 'seed']);
+  return { workspaceDir, repo };
+}
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+describe('GitService.commitFile with bytes beside the repository', () => {
+  let root: string;
+  const workspaceId = 'ws-stray';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  });
+
+  it('throws instead of returning null when the file exists at the workspace root and not in the clone', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    // The prefix-less write the agent made: beside the clone, not inside it.
+    await fs.mkdir(path.join(workspaceDir, 'KnowledgeBase/Reviews'), { recursive: true });
+    await fs.writeFile(path.join(workspaceDir, 'KnowledgeBase/Reviews/PR-12.html'), '<p>review</p>');
+    const headBefore = await runGit(repo, ['rev-parse', 'HEAD']);
+
+    const attempt = svc.commitFile(workspaceId, USER, 'KnowledgeBase/Reviews/PR-12.html');
+    await expect(attempt).rejects.toBeInstanceOf(WorkflowValidationError);
+    await expect(attempt).rejects.toThrow('"knowledge-base/KnowledgeBase/Reviews/PR-12.html"');
+
+    // Nothing landed, and the stray is left where it is for someone to recover.
+    expect(await runGit(repo, ['rev-parse', 'HEAD'])).toBe(headBefore);
+    expect(await fs.readFile(path.join(workspaceDir, 'KnowledgeBase/Reviews/PR-12.html'), 'utf-8')).toBe('<p>review</p>');
+  });
+
+  it('still returns null for a clean, committed path (the honest no-op)', async () => {
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    expect(await svc.commitFile(workspaceId, USER, `${KB}/Knowledge/A.md`)).toBeNull();
+  });
+
+  it('still returns null for a path that exists nowhere (a queued re-apply of a committed deletion)', async () => {
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    expect(await svc.commitFile(workspaceId, USER, `${KB}/Knowledge/Gone.md`)).toBeNull();
+  });
+
+  it('still returns null for a repo-relative path that is clean inside the clone (the form internal callers pass)', async () => {
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    expect(await svc.commitFile(workspaceId, USER, 'Knowledge/A.md')).toBeNull();
+  });
+
+  it('still returns null for a repo-relative path when the clone has that file too, even with a same-named file at the workspace root', async () => {
+    // Not provably stray: the clone holds `Knowledge/A.md` and it is clean, so
+    // a repo-relative caller's no-op stays honest whatever else sits beside
+    // the clone under the same name.
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    await fs.mkdir(path.join(workspaceDir, 'Knowledge'), { recursive: true });
+    await fs.writeFile(path.join(workspaceDir, 'Knowledge/A.md'), 'a copy beside the clone\n');
+    expect(await svc.commitFile(workspaceId, USER, 'Knowledge/A.md')).toBeNull();
+  });
+
+  it('does not mistake an unreadable stray for an absent one', async () => {
+    // Only ENOENT means "nothing there". Any other stat failure must surface,
+    // or a stray the process cannot read is silently reported as committed.
+    // root ignores mode bits, and Windows has none to set (`chmod` there only
+    // toggles read-only, so the stat below still succeeds): nothing to prove.
+    if (process.getuid?.() === 0 || process.platform === 'win32') return;
+    const { workspaceDir } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    const strayDir = path.join(workspaceDir, 'KnowledgeBase');
+    await fs.mkdir(strayDir, { recursive: true });
+    await fs.writeFile(path.join(strayDir, 'PR-12.html'), 'x');
+    await fs.chmod(strayDir, 0o000);
+    try {
+      const attempt = svc.commitFile(workspaceId, USER, 'KnowledgeBase/PR-12.html');
+      await expect(attempt).rejects.toMatchObject({ code: 'EACCES' });
+    } finally {
+      await fs.chmod(strayDir, 0o755);
+    }
+  });
+
+  it('still commits a prefixed path inside the clone', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), KB);
+    await fs.writeFile(path.join(repo, 'Knowledge/B.md'), 'b\n');
+    const committed = await svc.commitFile(workspaceId, USER, `${KB}/Knowledge/B.md`);
+    expect(committed).not.toBeNull();
+    expect(committed!.authorEmail).toBe('alice@example.com');
+    expect(await runGit(repo, ['log', '--oneline'])).toMatch(/^\S+ .*\n\S+ seed$/);
+  });
+});