@bevel-software/platform-core-backend 0.30.0 → 0.31.0

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

@@ -1,9 +1,13 @@
 import type { Router, RequestHandler } from 'express';
 import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
-import { ToolError, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import { isCommitSha } from '../../../shared/git.contract.js';
 import { toolDef } 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 type { IAccessControl } from '../../access/access-control.interface.js';
+import { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_INPUT, type AgentAccessGate } from '../../workspace/index.js';
+import { readablePathsAt, readableAtCommits, assertReadableAtCommits } from '../read-on-branch.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
@@ -176,6 +180,21 @@ export function registerWorkflowTools(
    * nor links a request it answers no for.
    */
   maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
+  /**
+   * The per-file read gate the history tools apply: a file's past is the
+   * file, so a history read takes the read the file itself takes — on the
+   * workspace for its own branch's history (`canRead`), at the commit
+   * another branch's content was served from (`canReadAtRef`, through
+   * `readableAtCommits`, the compare route's own rule), and in batches for
+   * the path lists `branch_status` shows.
+   */
+  accessControl: Pick<IAccessControl, 'canRead' | 'canReadAtRef' | 'canReadBatch' | 'canReadBatchAtRef'>,
+  /**
+   * The deployment's blocking read hook, told of every file content a history
+   * tool serves, as `read_file` tells it — a hook that refuses the read
+   * refuses the history too.
+   */
+  agentAccessGate: AgentAccessGate,
 ): void {
   const { kbDirName } = kb;
   const mount = (spec: {
@@ -748,4 +767,446 @@ export function registerWorkflowTools(
       };
     },
   });
+
+  // ── History and syncing ────────────────────────────────────────────────────
+  //
+  // What the app's History tab, compare view and "update from target" do,
+  // as tools: the agent never runs git itself. Each reads through the
+  // workflow service's gated methods and takes the per-file read the file
+  // itself takes.
+
+  /** The branch's workspace, made when it is not on disk yet, and its id. */
+  const workspaceOf = async (ctx: ToolContext, branch: string): Promise<string> => {
+    await ctx.workspaceService.getOrCreateForBranch(branch);
+    return workspaceIdForBranch(branch);
+  };
+
+  /**
+   * The per-file read gate on the workspace's own branch, and the
+   * deployment's read hook told of the read (as `read_file` tells it);
+   * answers the repository-relative path.
+   */
+  const requireRead = async (ctx: ToolContext, branch: string, workspaceId: string, path: string): Promise<string> => {
+    const rel = stripKbDir(path, kbDirName);
+    await notifyAgentRead(agentAccessGate, ctx, branch, path);
+    if (!(await accessControl.canRead(workspaceId, ctx.user.email, rel))) {
+      throw new ToolError(`You don't have permission to read "${rel}".`, 403, { kind: 'read-denied', path: rel });
+    }
+    return rel;
+  };
+
+  /**
+   * The per-file read gate for content served from ANOTHER branch — the
+   * compare route's rule: at every commit the branch resolves to (the one
+   * the service serves it from, and its other tip when the local head and
+   * the published tip differ), all of which must grant, asked by the
+   * service inside its reservation before anything is said about the path
+   * there.
+   */
+  const requireReadAtCommits = (ctx: ToolContext, workspaceId: string, rel: string, commits: readonly string[], branch: string): Promise<void> =>
+    assertReadableAtCommits(accessControl, workspaceId, ctx.user.email, rel, commits, branch);
+
+  /** Which of `paths` the caller may read at `origin/<base>` — the change-request reads' rule, `readablePathsAt`. */
+  const readableAt = (ctx: ToolContext, workspaceId: string, base: string, paths: string[]): Promise<Set<string>> =>
+    readablePathsAt(accessControl, workspaceId, ctx.user.email, base, paths);
+
+
+  mount({
+    name: 'list_file_changes',
+    description:
+      'The history of one file on `branch`: its commits, newest first — who made each, when, and its ' +
+      'subject — as the app\'s History tab shows them. `limit` caps the list (default 20, at most 100). ' +
+      'Read a version with `read_file_at` and its diff with `compare_file`. Takes the read the file itself ' +
+      'takes; a folder has no history of its own (ask per file).',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative (as `read_file` takes it).' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many commits at most (default 20).' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        changes: { type: 'array', items: commitSchema, description: 'Newest first.' },
+      },
+      required: ['path', 'changes'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      const limit = typeof args.limit === 'number' ? args.limit : undefined;
+      const changes = await ctx.workflowService.listChangesForFile(workspaceId, path, limit);
+      return { path: rel, changes };
+    },
+  });
+
+  mount({
+    name: 'read_file_at',
+    description:
+      'One file as it was at a point in history: `at` is a commit (from `list_file_changes`, on `branch`\'s ' +
+      'own history) or the name of another branch (its published tip). Answers `content` (null when the ' +
+      'file was not there) and `sha`, the commit it was read at; for a commit, also `before`, the file ' +
+      'just before that commit. To put an earlier version back, write it with `write_file`. Takes the read ' +
+      'the file takes at that point.',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
+        at: { type: 'string', minLength: 1, description: 'A commit sha, or a branch name.' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path', 'at'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        at: { type: 'string', description: 'What was asked for.' },
+        kind: { type: 'string', enum: ['commit', 'branch'] },
+        sha: { type: 'string', description: 'The commit the content was read at.' },
+        content: { type: ['string', 'null'], description: 'The file at that commit; null when it was not there.' },
+        before: { type: ['string', 'null'], description: 'For a commit: the file just before it; null when it was not there (or the commit is the first).' },
+      },
+      required: ['path', 'at', 'kind', 'sha', 'content'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      const at = args.at;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      if (typeof at !== 'string' || at.length === 0) throw new ToolError('`at` is required: a commit sha or a branch name.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      // The hook and the workspace gate first, whichever point in history is
+      // read: the file is this workspace's file.
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      if (isCommitSha(at)) {
+        const { baseline, current } = await ctx.workflowService.fileAtChange(workspaceId, path, at);
+        return { path: rel, at, kind: 'commit', sha: at, content: current, before: baseline };
+      }
+      // Read at the branch's published tip, authorized at that very commit
+      // inside the read — before anything is said about the path there,
+      // the folder refusal included: the ref is a name a fetch may move
+      // between a verdict and a read; the commit is not.
+      const read = await ctx.workflowService.fileAtBranch(workspaceId, path, at, (commits) => requireReadAtCommits(ctx, workspaceId, rel, commits, at));
+      return { path: rel, at, kind: 'branch', sha: read.sha, content: read.content };
+    },
+  });
+
+  mount({
+    name: 'compare_file',
+    description:
+      'The unified diff of one file: between two branches (`from`, `to`; either may be `branch` itself), ' +
+      'or of one commit on `branch` (`at`: what that commit changed in the file). Empty when identical. ' +
+      'Takes the read the file takes on each side.',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
+        from: { type: 'string', minLength: 1, description: 'A branch: the diff\'s left side.' },
+        to: { type: 'string', minLength: 1, description: 'A branch: the diff\'s right side.' },
+        at: { type: 'string', minLength: 1, description: 'A commit sha on `branch`: the diff that commit made in the file.' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        diff: { type: 'string', description: 'A unified diff; empty when the two sides are identical.' },
+      },
+      required: ['path', 'diff'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      // As the compare route: the workspace's own gate on the path (the
+      // checked-out side can be served from the working tree), then each
+      // compared side at the commit it was served from.
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      if (typeof args.at === 'string' && args.at.length > 0) {
+        if (!isCommitSha(args.at)) throw new ToolError('`at` must be a full commit sha.', 400);
+        return { path: rel, diff: await ctx.workflowService.showFileAtChange(workspaceId, path, args.at) };
+      }
+      const from = args.from;
+      const to = args.to;
+      if (typeof from !== 'string' || from.length === 0 || typeof to !== 'string' || to.length === 0) {
+        throw new ToolError('Give `from` and `to` (two branches), or `at` (one commit).', 400);
+      }
+      const compared = await ctx.workflowService.compareFile(workspaceId, path, from, to, async (sides) => {
+        await requireReadAtCommits(ctx, workspaceId, rel, sides.from, from);
+        await requireReadAtCommits(ctx, workspaceId, rel, sides.to, to);
+      });
+      return { path: rel, diff: compared.diff };
+    },
+  });
+
+  mount({
+    name: 'branch_status',
+    description:
+      'Where `branch` stands, before proposing or syncing a draft. Answers whether it is on the shared ' +
+      'repository, how far ahead of and behind its upstream it is, whether the shared branch has commits this ' +
+      'workspace lacks (`behindRemote`: `update_branch` brings them in), the files written but not committed ' +
+      'yet, the protected branch it was forked from (`forkBase`), and `changedPaths`: what it changes against ' +
+      '`base` (default: the fork base) — the files a change request into it would carry.',
+    inputs: {
+      type: 'object',
+      properties: {
+        base: { type: 'string', minLength: 1, description: 'The branch to compare against (default: the fork base).' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        branch: { type: 'string' },
+        isProtected: { type: 'boolean' },
+        hasRemote: { type: 'boolean', description: 'True when the shared repository has the branch.' },
+        ahead: { type: ['integer', 'null'], description: 'Commits ahead of the upstream (or the fork base); null when unresolved.' },
+        behind: { type: ['integer', 'null'], description: 'Commits behind; null when unresolved.' },
+        behindRemote: { type: 'boolean', description: 'The shared branch has commits this workspace has not merged yet.' },
+        uncommittedPaths: { type: 'array', items: { type: 'string' }, description: 'Written but not committed yet (saves still landing).' },
+        forkBase: { type: ['string', 'null'], description: 'The protected branch this one was forked from; null when none can be reached.' },
+        base: { type: ['string', 'null'], description: 'What `changedPaths` is against.' },
+        changedPaths: { type: 'array', items: { type: 'string' }, description: 'Repository-relative; rename-aware; only the paths you may read. Empty when `base` is null.' },
+        withheldPaths: { type: 'integer', description: 'How many changed or uncommitted paths were left out because you may not read them.' },
+      },
+      required: ['branch', 'isProtected', 'hasRemote', 'ahead', 'behind', 'behindRemote', 'uncommittedPaths', 'forkBase', 'base', 'changedPaths', 'withheldPaths'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const workspaceId = await workspaceOf(ctx, branch);
+      // Each read below takes the workspace's reservation on its own: this
+      // is a REPORT of independent facts, not a range measured across steps,
+      // and a save or sync landing between two of them is tolerated — the
+      // next call reports it. (The one answer that must be exact, what a
+      // merge is of, is taken under one reservation by `update_branch`.)
+      const [status, branches, pending, forkBase] = await Promise.all([
+        ctx.workflowService.branchStatus(workspaceId),
+        ctx.workflowService.listBranches(workspaceId),
+        ctx.workflowService.listPendingChangePaths(workspaceId),
+        ctx.workflowService.resolveForkBase(workspaceId, branch),
+      ]);
+      const info = branches.find((b) => b.name === branch);
+      const base = typeof args.base === 'string' && args.base.length > 0 ? args.base : forkBase;
+      // A path's name is information too: the changed paths are shown as the
+      // change-request reads show them (readable at `origin/<base>`), the
+      // uncommitted ones as the workspace's own listing would.
+      const changedAll =
+        base && base !== branch ? await ctx.workflowService.changedPathsBetweenBranches(workspaceId, base, branch) : [];
+      const readableChanged = base ? await readableAt(ctx, workspaceId, base, changedAll) : new Set<string>();
+      const changedPaths = changedAll.filter((p) => readableChanged.has(p));
+      const pendingRel = pending.map((p) => stripKbDir(p, kbDirName));
+      const pendingVerdicts = pendingRel.length > 0 ? await accessControl.canReadBatch(workspaceId, ctx.user.email, pendingRel) : new Map<string, boolean>();
+      const uncommittedPaths = pendingRel.filter((p) => pendingVerdicts.get(p) === true);
+      return {
+        branch,
+        isProtected: info?.isProtected ?? kb.protectedBranches.has(branch),
+        hasRemote: info?.hasRemote ?? status.hasUpstream,
+        ahead: info?.ahead ?? null,
+        behind: info?.behind ?? null,
+        behindRemote: status.unmergedFromUpstream,
+        uncommittedPaths,
+        forkBase,
+        base: base && base !== branch ? base : null,
+        changedPaths,
+        withheldPaths: changedAll.length - changedPaths.length + (pendingRel.length - uncommittedPaths.length),
+      };
+    },
+  });
+
+  mount({
+    name: 'update_branch',
+    description:
+      'Bring another branch into `branch` as a merge commit by you, and publish it: `from` (a draft\'s ' +
+      'target, to refresh the draft), or left out, the branch\'s own shared state when it moved while this ' +
+      'workspace held commits (`branch_status` says `behindRemote`). Never a protected branch. CONFLICTS: ' +
+      'the first call answers `conflicts` naming every conflicted path with the file at the merge base, on ' +
+      'each side (`ours` = `branch`, `theirs` = `from`) and the working copy with git\'s markers, and leaves ' +
+      'the branch as it was. Decide each file (keep both sides\' information unless one is clearly stale; ' +
+      '`list_file_changes` shows intent), then call again with `resolutions`, one per conflicted path: ' +
+      '`content` (the resolved text) or `choose` (`ours`, `theirs`, `delete`). Only conflicted paths are ' +
+      'written here; other edits go through the file tools. Answers `merged`, `nothing-to-merge`, ' +
+      '`conflicts` again (something changed meanwhile), or `pending-commits` (writes still landing: retry).',
+    inputs: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', minLength: 1, description: 'The branch to bring in (default: this branch\'s own shared state).' },
+        sessionId: SESSION_ID_INPUT,
+        resolutions: {
+          type: 'array',
+          description: 'One per conflicted path, from a previous `conflicts` answer.',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string', minLength: 1, description: 'The conflicted path, as the answer named it.' },
+              content: { type: 'string', description: 'The resolved text of the file.' },
+              choose: { type: 'string', enum: ['ours', 'theirs', 'delete'], description: 'Keep one side whole, or drop the file.' },
+            },
+            required: ['path'],
+            additionalProperties: false,
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['merged', 'nothing-to-merge', 'conflicts', 'pending-commits'] },
+        from: { type: 'string', description: 'The branch brought in.' },
+        sha: { type: 'string', description: '`merged`: the merge commit, now the tip of `branch`, published; `nothing-to-merge`: the unchanged tip.' },
+        resolvedPaths: { type: 'array', items: { type: 'string' }, description: '`merged`: the conflicts the resolutions settled.' },
+        mergeBase: { type: ['string', 'null'], description: '`conflicts`: the common ancestor; null when the histories are unrelated.' },
+        ours: { type: 'string', description: '`conflicts`: the tip of `branch`.' },
+        theirs: { type: 'string', description: '`conflicts`: the tip of `from`.' },
+        files: {
+          type: 'array',
+          description:
+            '`conflicts`: every conflicted path you may read, with the file at the base, on each side, and the marked-up ' +
+            'working copy. A side is null when that side has no file — or when `truncated` names it (too large or not ' +
+            'text): then read `ours` with `read_file`, `theirs` with `read_file_at` at `from`, `base` with `read_file_at` ' +
+            'at `mergeBase`.',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string' },
+              base: { type: ['string', 'null'] },
+              ours: { type: ['string', 'null'] },
+              theirs: { type: ['string', 'null'] },
+              merged: { type: ['string', 'null'] },
+              truncated: { type: 'array', items: { type: 'string', enum: ['base', 'ours', 'theirs', 'merged'] } },
+            },
+            required: ['path', 'base', 'ours', 'theirs', 'merged'],
+          },
+        },
+        unresolved: { type: 'array', items: { type: 'string' }, description: '`conflicts`: the paths you may read that no resolution covered.' },
+        withheldConflicts: {
+          type: 'integer',
+          description:
+            '`conflicts`: how many conflicted files were left out because you may not read them on one of the two branches. ' +
+            'They are not yours to settle: ask a person who can read them to update the draft in the app.',
+        },
+        branch: { type: 'string', description: '`pending-commits`: the branch whose writes are not committed yet.' },
+        pending: { type: 'integer', description: '`pending-commits`: how many.' },
+        needsAttention: { type: 'string', description: '`pending-commits`: a queued commit failed; the worker\'s message. Tell the user.' },
+        message: { type: 'string', description: '`pending-commits`: what to do next.' },
+      },
+      required: ['kind'],
+    },
+    write: true,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const from = args.from;
+      if (from !== undefined && (typeof from !== 'string' || from.length === 0)) {
+        throw new ToolError('`from` must be a branch name.', 400);
+      }
+      let resolutions: { path: string; content?: string; choose?: 'ours' | 'theirs' | 'delete' }[] | undefined;
+      if (args.resolutions !== undefined) {
+        if (!Array.isArray(args.resolutions)) throw new ToolError('`resolutions` must be a list.', 400);
+        resolutions = args.resolutions.map((r: unknown, i: number) => {
+          const entry = r as Record<string, unknown>;
+          if (!entry || typeof entry.path !== 'string' || entry.path.length === 0) {
+            throw new ToolError(`resolutions[${i}]: \`path\` is required.`, 400);
+          }
+          const out: { path: string; content?: string; choose?: 'ours' | 'theirs' | 'delete' } = { path: entry.path };
+          if (entry.content !== undefined) {
+            if (typeof entry.content !== 'string') throw new ToolError(`resolutions[${i}]: \`content\` must be text.`, 400);
+            out.content = entry.content;
+          }
+          if (entry.choose !== undefined) {
+            if (entry.choose !== 'ours' && entry.choose !== 'theirs' && entry.choose !== 'delete') {
+              throw new ToolError(`resolutions[${i}]: \`choose\` is \`ours\`, \`theirs\` or \`delete\`.`, 400);
+            }
+            out.choose = entry.choose;
+          }
+          return out;
+        });
+      }
+      const workspaceId = await workspaceOf(ctx, branch);
+      /**
+       * Whether the caller may read `rel` on both sides of this merge — at
+       * the two COMMITS the answer says the merge was of, which is what its
+       * bytes are from, never at a branch ref that may have moved since the
+       * reservation was released — with the deployment's read hook told of
+       * the read, as every history read tells it: a hook that refuses makes
+       * the file one the caller may not read; a hook that fails is not an
+       * answer and propagates.
+       */
+      const mayReadBothSides = async (rel: string, at: { ours: string; theirs: string }): Promise<boolean> => {
+        try {
+          await notifyAgentRead(agentAccessGate, ctx, branch, `${kbDirName}/${rel}`);
+        } catch (err) {
+          // A hook's own refusal carries a status; anything else is a failure of the hook, not an answer.
+          if (hasHttpStatus(err)) return false;
+          throw err;
+        }
+        return readableAtCommits(accessControl, workspaceId, ctx.user.email, rel, [at.ours, at.theirs]);
+      };
+      // A resolution reads a file on both branches and writes it on the
+      // draft, so the deployment's hooks are asked as they are for any read
+      // and any write. The access model's own verdicts — may the caller read
+      // the file on both branches, may they change it on the draft — are the
+      // service's, asked inside the merge against the source commit as
+      // fetched (`updateBranch`), so a rule that changed with the source
+      // cannot be outrun by a check made before it was fetched.
+      for (const r of resolutions ?? []) {
+        const wsPath = `${kbDirName}/${stripKbDir(r.path, kbDirName)}`;
+        try {
+          await notifyAgentRead(agentAccessGate, ctx, branch, wsPath);
+        } catch (err) {
+          if (hasHttpStatus(err)) {
+            throw new ToolError(`You may not read "${stripKbDir(r.path, kbDirName)}" here, so it is not yours to settle.`, 403, {
+              kind: 'read-denied',
+              path: stripKbDir(r.path, kbDirName),
+            });
+          }
+          throw err;
+        }
+        await assertAgentWriteAllowed(agentAccessGate, ctx, branch, wsPath);
+      }
+      // A resolution's content lands on the draft by the merge, not by the
+      // file tools' filesystem: it takes the same pre-disk gate that
+      // filesystem runs (`roles.yaml` must parse, no new role, no unknown
+      // group), handed to the service to ask before the merge.
+      const outcome =
+        resolutions !== undefined
+          ? await ctx.workflowService.updateBranch(workspaceId, ctx.user, {
+              ...(from !== undefined ? { from } : {}),
+              resolutions,
+              validateWrite: await ctx.getWriteValidator(branch),
+            })
+          : await ctx.workflowService.updateBranch(workspaceId, ctx.user, from !== undefined ? { from } : {});
+      if (outcome.kind !== 'conflicts') return outcome;
+      // A conflict answer carries the file on both branches, and a path's
+      // name is information too: a file the caller may not read on both is
+      // left out of `files` and `unresolved` alike and only counted.
+      const files = [];
+      for (const f of outcome.files) if (await mayReadBothSides(f.path, outcome)) files.push(f);
+      const shown = new Set(files.map((f) => f.path));
+      return {
+        ...outcome,
+        files,
+        unresolved: outcome.unresolved.filter((p) => shown.has(p)),
+        withheldConflicts: outcome.files.length - files.length,
+      };
+    },
+  });
 }

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

@@ -9,6 +9,8 @@ import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import { WorkflowHooks } from '../../workflow-hooks.js';
 import { GitService } from '../git.service.js';
 import { WorkflowValidationError, BranchNameError } from '../../../../shared/domain-errors.js';
+import { GitRunError, type IGitRunner } from '../../../../shared/git.contract.js';
+import { NodeGitRunner } from '../node-git-runner.js';
 
 const execFileAsync = promisify(execFile);
 const PROCESS_MAP_DIR = 'knowledge-base';
@@ -107,7 +109,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     await runGit(repo, ['checkout', '-b', 'alice/edit-foo']);
     await commitFile(repo, 'Knowledge/Foo.md', 'line one\nline two\n', 'add line two');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Foo.md',
       'current-company-state',
@@ -117,6 +119,69 @@ describe('GitService.diffFileBetweenBranches', () => {
     expect(diff).toContain('+line two');
   });
 
+  it('asks the caller\'s verdict at the two commits served, before the path is described at either', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), testKbContext());
+    await commitFile(repo, 'Knowledge/Foo.md', 'line one\n', 'base');
+    await commitFile(repo, 'Docs/a.md', 'a\n', 'a folder');
+    const base = (await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repo })).stdout.trim();
+    await runGit(repo, ['checkout', '-b', 'alice/edit-foo']);
+    await commitFile(repo, 'Knowledge/Foo.md', 'line one\nline two\n', 'add line two');
+    const tip = (await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repo })).stdout.trim();
+
+    const asked: unknown[] = [];
+    // Local branches only: each side resolves to the one commit it was served from.
+    const sides = { from: [base], to: [tip] };
+    const { diff } = await svc.diffFileBetweenBranches(workspaceId, 'Knowledge/Foo.md', 'current-company-state', 'alice/edit-foo', async (s) => {
+      asked.push(s);
+    });
+    expect(diff).toContain('+line two');
+    expect(asked).toEqual([sides]);
+
+    // A folder the caller may not read is refused as unreadable, never as a folder.
+    const refuse = async (s: unknown): Promise<void> => {
+      asked.push(s);
+      throw new WorkflowValidationError('not yours to read');
+    };
+    await expect(svc.diffFileBetweenBranches(workspaceId, 'Docs', 'current-company-state', 'alice/edit-foo', refuse)).rejects.toThrow(/not yours to read/);
+    expect(asked).toEqual([sides, sides]);
+  });
+
+  it('fails closed when a lookup of a side\'s other tip fails for any reason but absence: no diff, the verdict never asked', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    await commitFile(repo, 'Knowledge/Foo.md', 'line one\n', 'base');
+    await runGit(repo, ['checkout', '-b', 'alice/edit-foo']);
+    await commitFile(repo, 'Knowledge/Foo.md', 'line one\nline two\n', 'add line two');
+    const inner = new NodeGitRunner();
+    // The secondary lookup (`refs/remotes/origin/alice/edit-foo`, absent in
+    // this local-only repository) fails the way a corrupt repository or a
+    // deadline fails — not the way an absent ref answers.
+    let failure: GitRunError | null = null;
+    const gitRunner = {
+      defaultTimeoutMs: inner.defaultTimeoutMs,
+      credentials: inner.credentials,
+      run: async (cwd: string, args: string[], opts?: object) => {
+        if (failure && args[0] === 'rev-parse' && args.includes('refs/remotes/origin/alice/edit-foo')) throw failure;
+        return inner.run(cwd, args, opts as never);
+      },
+    } as unknown as IGitRunner;
+    const svc = new GitService(stubWorkspaceService(workspaceId, workspaceDir), new WorkflowHooks(), testKbContext(), undefined, null, gitRunner);
+    const asked: unknown[] = [];
+    const authorize = async (s: unknown): Promise<void> => { asked.push(s); };
+    for (const f of [
+      new GitRunError('git rev-parse failed', { exitCode: 128, stderr: 'fatal: bad object' }),
+      new GitRunError('git rev-parse timed out', { timedOut: true }),
+    ]) {
+      failure = f;
+      await expect(svc.diffFileBetweenBranches(workspaceId, 'Knowledge/Foo.md', 'current-company-state', 'alice/edit-foo', authorize)).rejects.toBe(f);
+    }
+    expect(asked).toEqual([]);
+    // An absent ref is the one answer that is "no such commit": the diff goes on.
+    failure = null;
+    expect((await svc.diffFileBetweenBranches(workspaceId, 'Knowledge/Foo.md', 'current-company-state', 'alice/edit-foo', authorize)).diff).toContain('+line two');
+    expect(asked).toHaveLength(1);
+  });
+
   it('returns the empty string when the file is identical on both branches', async () => {
     const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
     const svc = new GitService(
@@ -130,7 +195,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     // no edits to Same.md on the new branch
     await commitFile(repo, 'Knowledge/Other.md', 'sidecar\n', 'unrelated edit');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Same.md',
       'current-company-state',
@@ -151,7 +216,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     await runGit(repo, ['checkout', '-b', 'alice/cleanup']);
     await deleteFileCommit(repo, 'Knowledge/Old.md', 'remove Old.md');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Old.md',
       'current-company-state',
@@ -173,7 +238,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     await runGit(repo, ['checkout', '-b', 'alice/add-new']);
     await commitFile(repo, 'Knowledge/New.md', 'brand new\n', 'add New.md');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/New.md',
       'current-company-state',
@@ -211,7 +276,7 @@ describe('GitService.diffFileBetweenBranches', () => {
       testKbContext(),
     );
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Foo.md',
       'current-company-state',
@@ -240,7 +305,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     await runGit(repo, ['checkout', '-b', 'alice/edit-foo']);
     await commitFile(repo, 'Knowledge/Foo.md', 'baseline\nedit\n', 'edit');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'knowledge-base/Knowledge/Foo.md',
       'current-company-state',
@@ -267,7 +332,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     // and pressing save before sharing.
     await writeFile(repo, 'Knowledge/Foo.md', 'baseline\nfresh edit\n');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Foo.md',
       'current-company-state',
@@ -291,7 +356,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     // Brand-new file, never committed — only on disk.
     await writeFile(repo, 'Knowledge/Brandnew.md', 'fresh content\n');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Brandnew.md',
       'current-company-state',
@@ -313,7 +378,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     await runGit(repo, ['checkout', '-b', 'alice/draft']);
     await writeFile(repo, 'Knowledge/Brandnew.md', 'fresh content\n');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Brandnew.md',
       'alice/draft',
@@ -339,7 +404,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     // side. Lines added on current-company-state — i.e. the *removal* of
     // "draft edit" — should appear as `+` on the to side, and "draft edit"
     // should appear as `-`.
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       'Knowledge/Foo.md',
       'alice/edit-foo',
@@ -443,7 +508,7 @@ describe('GitService.diffFileBetweenBranches', () => {
     await writeFile(repo, relPath, 'base content\nfeature edit\n');
     await svc.commitFile(workspaceId, user, relPath, 'feature edit');
 
-    const diff = await svc.diffFileBetweenBranches(
+    const { diff } = await svc.diffFileBetweenBranches(
       workspaceId,
       relPath,
       'current-company-state',