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

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$/);
+  });
+});

package/src/modules/workflow/git/__tests__/pull-request.service.getPrDetail.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { PullRequestService } from '../pull-request.service.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../git.service.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+
+const ROW = {
+  id: 'cr-7',
+  number: 7,
+  sourceBranch: 'alice/feature',
+  targetBranch: 'current-company-state',
+  title: 'Feature',
+  body: '',
+  authorEmail: 'alice@bevel.software',
+  authorName: 'Alice',
+  state: 'open',
+  mergedSha: null,
+  createdAt: new Date('2026-08-01T00:00:00Z'),
+  updatedAt: null,
+  closedAt: null,
+};
+
+function makeDb(): Database {
+  return {
+    select: () => ({
+      from: () => ({
+        where: () => ({ limit: async () => [ROW] }),
+      }),
+    }),
+  } as unknown as Database;
+}
+
+const BASE = 'b'.repeat(40);
+const HEAD = 'a'.repeat(40);
+
+/**
+ * A detail read is the hot path behind every change-request poll, every
+ * approval click, and every merge. It resolves the SHAs first (that fetches
+ * both refs), so the file list must be pinned to those same commits rather
+ * than fetch and resolve again. The SHAs and the file list are read on every
+ * call (a new head must show); what the detail cache saves is the DB
+ * enrichment (comments, approvals), so that is where "cached" is observed.
+ */
+describe('PullRequestService.getPrDetail — git work per read', () => {
+  function harness() {
+    const resolvePrShas = vi.fn(async () => ({ baseSha: BASE, headSha: HEAD }));
+    const changedFilesForPr = vi.fn(async () => []);
+    const git = { resolvePrShas, changedFilesForPr } as unknown as GitService;
+    const workspace = {
+      findAnyWorkspaceId: async () => 'ws-main',
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    const access = { canWriteAtRef: async () => false } as unknown as IAccessControl;
+    const svc = new PullRequestService(makeDb(), workspace, access, git);
+    const listComments = vi.fn(async () => []);
+    const getApprovalStates = vi.fn(async () => []);
+    svc.setDetailEnricher({
+      listComments,
+      getApprovalStates,
+      evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
+    });
+    return { svc, resolvePrShas, changedFilesForPr, getApprovalStates };
+  }
+
+  it('pins the file list to the SHAs it just resolved, and keeps patches for a client read', async () => {
+    const { svc, resolvePrShas, changedFilesForPr } = harness();
+    const detail = await svc.getPrDetail(7, { fresh: true });
+
+    expect(detail?.headSha).toBe(HEAD);
+    expect(detail?.baseSha).toBe(BASE);
+    expect(resolvePrShas).toHaveBeenCalledTimes(1);
+    expect(changedFilesForPr).toHaveBeenCalledTimes(1);
+    expect(changedFilesForPr).toHaveBeenCalledWith(
+      'ws-main',
+      'current-company-state',
+      'alice/feature',
+      { at: { baseSha: BASE, headSha: HEAD } },
+    );
+    // The SHAs (and their fetch) come first; the file list rides on it.
+    expect(resolvePrShas.mock.invocationCallOrder[0]).toBeLessThan(
+      changedFilesForPr.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it('a client read is cached: the next plain read skips the enrichment', async () => {
+    const { svc, getApprovalStates } = harness();
+    await svc.getPrDetail(7, { fresh: true });
+    await svc.getPrDetail(7);
+    expect(getApprovalStates).toHaveBeenCalledTimes(1);
+  });
+
+  it('an internal read (patches: false) skips patches and is not cached', async () => {
+    const { svc, changedFilesForPr, getApprovalStates } = harness();
+    await svc.getPrDetail(7, { fresh: true, patches: false });
+    expect(changedFilesForPr).toHaveBeenLastCalledWith(
+      'ws-main',
+      'current-company-state',
+      'alice/feature',
+      { at: { baseSha: BASE, headSha: HEAD }, patchCap: 0 },
+    );
+    // Not cached: the next plain read enriches again and asks for its own
+    // (full) file list.
+    await svc.getPrDetail(7);
+    expect(getApprovalStates).toHaveBeenCalledTimes(2);
+    expect(changedFilesForPr).toHaveBeenLastCalledWith(
+      'ws-main',
+      'current-company-state',
+      'alice/feature',
+      { at: { baseSha: BASE, headSha: HEAD } },
+    );
+  });
+});

package/src/modules/workflow/git/git.service.ts

@@ -17,6 +17,7 @@ import type { WorkflowHooks, CommitValidationContext } from '../workflow-hooks.j
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import { WorkspaceMutex } from '../../kb-fs/mutex.js';
+import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../../kb-fs/clone-config.js';
 import {
   assertValidBranchName,
@@ -244,6 +245,23 @@ async function synthesizeUntrackedSideDiff(
   }
 }
 
+/**
+ * `stat` for the stray check: false only when nothing can be there (ENOENT,
+ * or ENOTDIR when a parent segment is a file). Permission and I/O failures
+ * propagate: treating them as "absent" would let an unreadable stray pass as
+ * committed.
+ */
+async function existsForCommitCheck(absolutePath: string): Promise<boolean> {
+  try {
+    await fs.stat(absolutePath);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') return false;
+    throw err;
+  }
+}
+
 export class GitService implements IGitService {
   // Per-workspace fetch state, kept OUTSIDE the workspace mutex on purpose.
   // `git fetch` only writes `refs/remotes/origin/*` and packs new objects —
@@ -928,7 +946,10 @@ export class GitService implements IGitService {
       const { stdout: scoped } = await this.git(cwd, [
         'status', '--porcelain=v1', '--', repoRelativePath,
       ]);
-      if (!scoped.trim()) return null;
+      if (!scoped.trim()) {
+        await this.assertNoBytesBesideRepo(workspaceId, cwd, relativePath, repoRelativePath);
+        return null;
+      }
 
       // **No access check at commit time.** Per the "disk is the source of
       // truth" rule, by the time content is on disk it must not be rejected.
@@ -1969,24 +1990,39 @@ export class GitService implements IGitService {
    * list, statuses, and +/- counts; per-file patches are generated for up to
    * `patchCap` files (default 400) — beyond that `patch` is left undefined,
    * exactly like the old API's binary/oversized files (the UI renders those with
-   * no inline diff). Patch generation is skipped for binary files.
+   * no inline diff). Patch generation is skipped for binary files; `patchCap: 0`
+   * skips it entirely, which is one git subprocess per changed file saved.
+   *
+   * `at` pins the diff to two commits the caller has ALREADY resolved (the
+   * change-request detail resolves its SHAs first, which fetches both refs):
+   * no fetch, no ref resolution, and the file list is computed from exactly
+   * the commits the caller pins its head SHA to, so a fetch that lands in
+   * between cannot make the two disagree. Never pass SHAs from a path that
+   * has not just resolved them: the diff would describe a stale head.
    */
   async changedFilesForPr(
     workspaceId: string,
     baseBranch: string,
     headBranch: string,
-    opts: { patchCap?: number } = {},
+    opts: { patchCap?: number; at?: { baseSha: string; headSha: string } } = {},
   ): Promise<PullRequestFile[]> {
     assertValidBranchName(baseBranch);
     assertValidBranchName(headBranch);
+    if (opts.at) {
+      for (const sha of [opts.at.baseSha, opts.at.headSha]) {
+        if (!/^[0-9a-f]{40,64}$/.test(sha)) {
+          throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+        }
+      }
+    }
     const patchCap = opts.patchCap ?? 400;
     // Fetch outside the mutex (network round-trip) so origin latency can't hold
     // the workspace lock; the lock guards only the local diff work below.
     const cwd = await this.repoDir(workspaceId);
-    await this.fetchPrRefs(cwd, baseBranch, headBranch);
+    if (!opts.at) await this.fetchPrRefs(cwd, baseBranch, headBranch);
     return this.mutex.run(workspaceId, async () => {
-      const baseRef = await this.resolveBranchRef(cwd, baseBranch);
-      const headRef = await this.resolveBranchRef(cwd, headBranch);
+      const baseRef = opts.at ? opts.at.baseSha : await this.resolveBranchRef(cwd, baseBranch);
+      const headRef = opts.at ? opts.at.headSha : await this.resolveBranchRef(cwd, headBranch);
       const range = `${baseRef}...${headRef}`; // three-dot = changes on head since merge-base
 
       const [{ stdout: nameStatusOut }, { stdout: numstatOut }] = await Promise.all([
@@ -2383,6 +2419,37 @@ export class GitService implements IGitService {
     }
   }
 
+  /**
+   * A clean `git status` for a path has two honest readings (already
+   * committed; a queued re-apply of something that landed) and one dishonest
+   * one: the bytes exist, but BESIDE the repository, because a caller wrote a
+   * workspace-relative path without the `<kbDirName>/` prefix. Git never sees
+   * that file, so returning null would report "nothing to commit" for a write
+   * that silently never landed. Throw instead; the pending-commits ladder
+   * escalates the row to a needs-attention notice rather than dropping it.
+   *
+   * The stray has to be PROVABLE, because some callers pass repo-relative
+   * paths on purpose (the decline-revert flow, the merge-time `roles.yaml`
+   * preservation): bytes at the workspace-relative location AND nothing at
+   * the same repo-relative location inside the clone. A clean, committed
+   * `roles.yaml` keeps its null even if something of that name sits beside the
+   * clone, so an unrelated stray cannot abort a merge. Only ENOENT (or a
+   * parent that is not a directory) means "absent"; any other stat failure
+   * surfaces, so an unreadable stray is never reported as committed.
+   */
+  private async assertNoBytesBesideRepo(
+    workspaceId: string,
+    repoDir: string,
+    relativePath: string,
+    repoRelativePath: string,
+  ): Promise<void> {
+    if (relativePath !== repoRelativePath) return;
+    const workspaceDir = await this.workspaceService.getWorkspacePath(workspaceId);
+    if (!(await existsForCommitCheck(path.join(workspaceDir, relativePath)))) return;
+    if (await existsForCommitCheck(path.join(repoDir, repoRelativePath))) return;
+    assertInsideRepo(relativePath, this.kbDirName);
+  }
+
   private async repoDir(workspaceId: string): Promise<string> {
     return path.join(await this.workspaceService.getWorkspacePath(workspaceId), this.kbDirName);
   }

package/src/modules/workflow/git/pull-request.service.ts

@@ -7,12 +7,13 @@ import type {
   PullRequestFile,
   PullRequestState,
   PullRequestSummary,
+  IGitService,
 } from '@bevel-software/platform-shared';
 import type { Database } from '../../database/connection.js';
 import { changeRequests } from '../../database/schema.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { GitService } from './git.service.js';
+import { AccessUnreadableError } from '../../access-model/access-errors.js';
 import { WorkflowValidationError } from '../../../shared/domain-errors.js';
 import { hashEmail } from '../../../shared/hash-email.js';
 
@@ -100,7 +101,7 @@ export class PullRequestService implements IPullRequestService {
     private readonly db: Database,
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
-    private readonly gitService: GitService,
+    private readonly gitService: IGitService,
   ) {}
 
   setDetailEnricher(enricher: PrDetailEnricher): void {
@@ -276,7 +277,7 @@ export class PullRequestService implements IPullRequestService {
 
   async getPrDetail(
     prNumber: number,
-    opts: { fresh?: boolean; workspaceId?: string; viewerEmail?: string } = {},
+    opts: { fresh?: boolean; workspaceId?: string; viewerEmail?: string; patches?: boolean } = {},
   ): Promise<PullRequestDetail | null> {
     if (!Number.isInteger(prNumber) || prNumber <= 0) {
       throw new WorkflowValidationError('PR number must be a positive integer');
@@ -303,10 +304,19 @@ export class PullRequestService implements IPullRequestService {
       );
       baseSha = shas.baseSha;
       headSha = shas.headSha;
+      // The file list is pinned to the SHAs just resolved (`at`), so it and
+      // the `headSha` approvals pin against describe the same commits even if
+      // another fetch lands on this workspace in between, and the second
+      // fetch of the same two refs is gone. `patches: false` is for the
+      // internal detail an approve / withdraw / revert fetches to pin its
+      // work: those never read `files[].patch`, and generating it cost one git
+      // subprocess per changed file per click. The detail served to clients
+      // keeps its patches, so the published payload is unchanged.
       files = await this.gitService.changedFilesForPr(
         workspaceId,
         row.targetBranch,
         row.sourceBranch,
+        { at: { baseSha, headSha }, ...(opts.patches === false ? { patchCap: 0 } : {}) },
       );
     }
 
@@ -343,6 +353,10 @@ export class PullRequestService implements IPullRequestService {
               opts.viewerEmail,
             )
             .catch((err) => {
+              // An unreadable access tree fails the whole read (503): a detail
+              // with empty approvals would tell the merge gate "nothing to
+              // approve", and a reviewer nothing at all.
+              if (err instanceof AccessUnreadableError) throw err;
               console.warn(`[cr] getApprovalStates failed for #${prNumber}:`, err);
               return [] as FileApprovalState[];
             }),
@@ -403,7 +417,11 @@ export class PullRequestService implements IPullRequestService {
       viewerCanCancel,
     };
 
-    this.detailCache.set(cacheKey, { at: now, headSha: detail.headSha, value: detail });
+    // A patch-less detail is an internal read; it must not be served to the
+    // next client poll as if it were the full one.
+    if (opts.patches !== false) {
+      this.detailCache.set(cacheKey, { at: now, headSha: detail.headSha, value: detail });
+    }
     return detail;
   }
 

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

@@ -26,6 +26,7 @@ import type {
 } from './pending-commits.service.js';
 import { BACKOFF_MS, N_RECOVERY, N_TRANSIENT } from './pending-commits.service.js';
 import { sanitizeError } from './sanitize-error.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
 
 /**
  * Where the worker escalates terminal failures — the narrow, workflow-owned
@@ -276,6 +277,8 @@ export class PendingCommitsWorker {
   /**
    * Process a single claimed row. Outcome paths (see plan §lifecycle):
    *   - commit + push succeeds → delete the row.
+   *   - throws because the path is outside the repository → markNeedsAttention
+   *     + feedback notice at once (no retry can change it, see below).
    *   - throws, transient budget remains → markTransientFailure.
    *   - throws, transient exhausted, recovery budget remains → spawn agent.
    *   - throws, recovery exhausted → markNeedsAttention + feedback notice.
@@ -303,6 +306,19 @@ export class PendingCommitsWorker {
       // contain credentialed URLs ("https://x-access-token:ghp_…@…"); we
       // can't undo a persisted leak, so mask before any of them sees it.
       const message = sanitizeError(err);
+
+      const corrected = pathOutsideRepoCorrection(err);
+      if (corrected !== null) {
+        // The bytes sit BESIDE the clone (a workspace-relative path without
+        // the clone-folder prefix), so git will never see them: no retry can
+        // succeed, and a recovery agent has no commit to repair. Every attempt
+        // would throw this same refusal, so escalate now, with the corrected
+        // path in the notice, instead of spending the transient budget and
+        // N_RECOVERY agent runs to reach the same row state.
+        await this.escalate(row, message, strayPathNotice(row, message, corrected), 'path outside the repository');
+        return;
+      }
+
       const nextAttempts = row.attempts + 1;
 
       if (nextAttempts < N_TRANSIENT) {
@@ -346,30 +362,76 @@ export class PendingCommitsWorker {
       }
 
       // Recovery budget exhausted — escalate.
-      await this.deps.service.markNeedsAttention(row.id, message);
+      await this.escalate(row, message, terminalFailureNotice(row, message), `after ${N_RECOVERY} recovery runs`);
+    }
+  }
+
+  /**
+   * The last step of every terminal path: flag the row `needs_attention`
+   * and tell the dashboard. `why` is the log line's reason; `notice` is the
+   * body the admin reads.
+   */
+  private async escalate(row: PendingCommit, message: string, notice: string, why: string): Promise<void> {
+    await this.deps.service.markNeedsAttention(row.id, message);
+    console.error(
+      `[pending-commits] TERMINAL ws=${row.workspaceId} branch=${row.branch} path=${row.path} ${why}: ${message}`,
+    );
+    try {
+      await this.deps.feedback.send({
+        source: 'system',
+        user: this.deps.recoveryBot,
+        message: notice,
+      });
+    } catch (feedbackErr) {
+      // Don't let a feedback-sink hiccup mask the underlying terminal
+      // failure — the row is already `needs_attention` and the next
+      // process restart will keep logging it. Just note that the
+      // notice didn't reach the dashboard.
       console.error(
-        `[pending-commits] TERMINAL ws=${row.workspaceId} branch=${row.branch} path=${row.path} after ${N_RECOVERY} recovery runs: ${message}`,
+        `[pending-commits] failed to emit terminal-failure feedback notice for ws=${row.workspaceId} path=${row.path}:`,
+        sanitizeError(feedbackErr),
       );
-      try {
-        await this.deps.feedback.send({
-          source: 'system',
-          user: this.deps.recoveryBot,
-          message: terminalFailureNotice(row, message),
-        });
-      } catch (feedbackErr) {
-        // Don't let a feedback-sink hiccup mask the underlying terminal
-        // failure — the row is already `needs_attention` and the next
-        // process restart will keep logging it. Just note that the
-        // notice didn't reach the dashboard.
-        console.error(
-          `[pending-commits] failed to emit terminal-failure feedback notice for ws=${row.workspaceId} path=${row.path}:`,
-          sanitizeError(feedbackErr),
-        );
-      }
     }
   }
 }
 
+/**
+ * The commit layer's refusal of a path whose bytes sit beside the clone
+ * rather than in it (`kb-fs/repo-path.ts`): the corrected path it carries,
+ * or null for any other error. Read from the payload, not the message: the
+ * message the worker keeps is sanitized and truncated to fit `last_error`,
+ * and the correction is what gets cut. Deterministic: the same row throws
+ * it on every attempt.
+ */
+function pathOutsideRepoCorrection(err: unknown): string | null {
+  if (!(err instanceof WorkflowDomainError) || err.payload?.kind !== 'path-outside-repo') return null;
+  const corrected = err.payload.corrected;
+  return typeof corrected === 'string' && corrected.length > 0 ? corrected : '(see error)';
+}
+
+function strayPathNotice(row: PendingCommit, error: string, corrected: string): string {
+  return [
+    '[pending_commits] Commit refused: the file is outside the repository.',
+    '',
+    `Workspace: ${row.workspaceId}`,
+    `Branch:    ${row.branch}`,
+    `Path:      ${row.path}`,
+    `Use instead: ${corrected}`,
+    `Original author: ${row.authorEmail}`,
+    `Queued at: ${row.queuedAt.toISOString()}`,
+    `Error: ${error}`,
+    '',
+    'The bytes were written beside the git clone (a workspace-relative path',
+    'without the clone-folder prefix), so git never sees them. Nothing was',
+    'committed, retrying cannot change that, and no recovery agent was run.',
+    '',
+    'Resolve manually:',
+    `  - move the file to "${corrected}" and save it again, or delete it if it`,
+    '    should be discarded',
+    '  - then delete the row from pending_commits.',
+  ].join('\n');
+}
+
 function terminalFailureNotice(row: PendingCommit, error: string): string {
   const elapsedMs = Date.now() - row.queuedAt.getTime();
   const elapsed = formatElapsed(elapsedMs);