@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -1,4 +1,3 @@
-import express from 'express';
 import { describe, expect, it } from 'vitest';
 import {
   CALL_TOOL_CHAIN_NAME,
@@ -9,21 +8,9 @@ import {
   splitCallLine,
 } from '@bevel-software/platform-mcp-core';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/tool-manuals.contract.js';
-import { ToolRegistry } from '../tool-registry.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/index.js';
 import type { UtcpTool } from '../tool.contract.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
-import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
-import { WorkerPatternMatcher } from '../../workspace/bounded-matcher.js';
-import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
-import { registerPluginsTools } from '../../plugins/plugins.tools.js';
-import { registerSkillsTools } from '../../skills/skills.tools.js';
-import { registerToolManualsTools } from '../../tool-manuals/tool-manuals.tools.js';
-import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { UuidSessionSink } from '../../workspace/session-sink.js';
-import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
+import type { registerSkillsTools } from '../../skills/index.js';
 import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength, firstSentenceEnd } from '../description-length.js';
 import { CAN_WRITE_CLAUSE } from '../../tool-helpers/index.js';
 import {
@@ -31,9 +18,8 @@ import {
   sharedFileRules,
 } from '../../agent-instructions/index.js';
 import { isPlatformFile, platformFilesByDepth } from '@bevel-software/platform-shared';
-import { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE, guideFirstDescription } from '../guide-first.js';
-import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
-import { agentGuideSections } from '../../agent-guide/agent-guide.js';
+import { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE } from '../guide-first.js';
+import { emptySkills, hexisTools, servedMetaTools, unused } from '../../../__tests__/hexis-catalog.js';
 
 /**
  * The cap exists because clients cut a long tool description, and they cut it
@@ -43,104 +29,11 @@ import { agentGuideSections } from '../../agent-guide/agent-guide.js';
  * NAMING the tool: the next paragraph someone appends to a description has to
  * answer to this test rather than to an agent's truncated catalog.
  *
- * Every registrar Hexis owns is mounted here, on stand-ins, because the
- * descriptions are the only thing under test: a stand-in that is never called
- * is honest about that. Tools PROXIED from connected MCP servers are not
+ * The catalog is every registrar Hexis owns, mounted on stand-ins (see
+ * `hexis-catalog.ts`). Tools PROXIED from connected MCP servers are not
  * measured — their text is the other server's.
  */
 
-/** Dependencies the registrars take but never touch while they are only building defs. */
-const unused = <T,>(): T => ({}) as T;
-
-/** A `.tool` catalog with nothing in it: the shortest honest answer for a listing. */
-const emptyManuals = {
-  listLocalOnly: async () => [],
-  listAll: async () => [],
-  list: async () => [],
-  listInvalid: async () => [],
-} as unknown as Parameters<typeof registerToolManualsTools>[4];
-
-/** A skill catalog with nothing in it — the per-user skill line is then one fixed sentence. */
-const emptySkills = { listSkills: async () => [] } as unknown as Parameters<typeof registerSkillsTools>[4];
-
-/**
- * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
- * examples written against the namespace it registers the knowledge-base tools
- * under and against the catalog it serves, and the chain without the rules it
- * states only in the shared places. So the chain description measured here
- * carries the worked call a client is really sent, which is its longest form.
- */
-function servedMetaTools(external: readonly UtcpTool[]) {
-  return codeModeMetaTools(
-    EXTERNAL_KB_MANUAL_NAME,
-    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
-    { sharedRulesPointer: '' },
-    // As the hosted endpoint serves them: opening with the guide-first
-    // sentence, through the one helper the endpoint itself uses.
-  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
-}
-
-/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
-async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = emptySkills): Promise<UtcpTool[]> {
-  const registry = new ToolRegistry();
-  const router = express.Router();
-  const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
-  const toolHandler = createToolHandlerFactory(unused());
-  const kb = testKbContext();
-  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
-
-  registerWorkspaceTools(
-    registry,
-    router,
-    toolAuth,
-    toolHandler,
-    unused(),
-    unused(),
-    unused(),
-    kb,
-    gate,
-    new RoutineWritePolicyService(),
-    new UuidSessionSink(),
-    undefined,
-    undefined,
-    // The two upload tools are mounted only when a store is supplied, and
-    // every real composition supplies one: without it they would be the two
-    // descriptions this suite never measured.
-    unused(),
-    // The guide reader, not needed to build defs; then the download store,
-    // mounted on the same terms as the upload one.
-    undefined,
-    unused(),
-    // Starter packs and the tree walk, not needed; then the grep matcher,
-    // mounted on the same terms (it spawns no worker until a search runs).
-    undefined,
-    undefined,
-    new WorkerPatternMatcher(),
-  );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
-  registerPluginsTools(registry, kb);
-  registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
-  registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
-    accessControl: unused(),
-    variableStatus: unused(),
-    kb,
-  });
-  // The guide's own tool, with the platform's sections: the one description
-  // that lists the sections is measured with the list it really carries.
-  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
-
-  const byName = new Map<string, UtcpTool>();
-  // The meta-tools as a client is served them (`mcp.service.ts` opens each
-  // with the guide-first sentence at the mount), so the catalog measured here
-  // is the catalog that goes out rather than the bare constant.
-  const external = (await registry.listExternal()) as UtcpTool[];
-  const metaTools = servedMetaTools(external);
-  for (const tool of [...(await registry.listInternal()), ...external, ...metaTools]) {
-    byName.set(tool.name, tool as UtcpTool);
-  }
-  return [...byName.values()];
-}
-
 describe('no Hexis tool description is long enough to be cut', () => {
   it(`keeps every description a client is handed within ${TOOL_DESCRIPTION_CAP} characters`, async () => {
     const over = (await hexisTools())

package/src/modules/tool-registry/manual.routes.ts

@@ -2,6 +2,7 @@ import express, { type Request, type RequestHandler } from 'express';
 import { UtcpManualSerializer } from '@utcp/sdk';
 import { declaresWrite, type IToolRegistry, type ToolManualContext, type UtcpTool } from './tool.contract.js';
 import { requireInternalSource } from '../tool-auth/index.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 import type { IToolReadOnlyHints } from './read-only-hints.contract.js';
 
 /** Resolve a connection-key/internal-token user id to its email (for per-caller provider defs). */
@@ -62,6 +63,12 @@ export function createManualRoutes(
    * Absent, the manual carries the tools' own tags only.
    */
   readOnlyHints?: Pick<IToolReadOnlyHints, 'apply'>,
+  /**
+   * Resolves the scope of a connection made as an agent configuration: the external
+   * manual then lists only the platform tools it loads, and the providers word
+   * their descriptions for it (`modules/agent-scope`).
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -71,17 +78,31 @@ export function createManualRoutes(
   async function context(req: Request): Promise<ToolManualContext> {
     const userId = req.toolAuth?.userId;
     if (!userId) return {};
-    if (!resolveUserEmail) return { userId };
+    let userEmail: string | undefined;
     try {
-      return { userId, userEmail: await resolveUserEmail(userId) };
+      userEmail = resolveUserEmail ? await resolveUserEmail(userId) : undefined;
     } catch {
-      return { userId };
+      userEmail = undefined;
     }
+    // Everything adds nothing to the context, so its providers are asked
+    // exactly what they were asked before connections could be narrowed.
+    const agentPath = req.toolAuth?.agentPath;
+    const connectionScope = agentPath ? await resolveConnectionScope(agentScope, userEmail, agentPath) : undefined;
+    return {
+      userId,
+      ...(userEmail !== undefined ? { userEmail } : {}),
+      ...(connectionScope ? { connectionScope } : {}),
+    };
   }
 
   router.get('/agent/utcp', manualAuth, async (req, res) => {
-    const tools = await registry.listExternal(await context(req));
-    res.json(toManual(readOnlyHints ? readOnlyHints.apply(tools) : tools));
+    const ctx = await context(req);
+    const tools = await registry.listExternal(ctx);
+    // A connection made as an agent configuration is offered only the platform
+    // tools that file loads; a call to another is refused at its route.
+    const scope = ctx.connectionScope;
+    const offered = scope ? tools.filter((t) => scope.allowsPlatformTool(t.name)) : tools;
+    res.json(toManual(readOnlyHints ? readOnlyHints.apply(offered) : offered));
   });
   router.get('/agent/internal/utcp', manualAuth, requireInternalSource, async (req, res) => {
     const internal = await registry.listInternal(await context(req));

package/src/modules/tool-registry/tool.contract.ts

@@ -1,4 +1,5 @@
 import type { JsonSchema, Tool as UtcpTool } from '@utcp/sdk';
+import type { ConnectionScope } from '../agent-scope/index.js';
 
 export type { JsonSchema, UtcpTool };
 
@@ -23,6 +24,12 @@ export interface ToolManualContext {
   userEmail?: string;
   /** The requesting user's id, when it could be resolved (for per-user gating). */
   userId?: string;
+  /**
+   * What the requesting connection may load, when it was made as an agent configuration
+   * file (`modules/agent-scope`): a provider that names skills or connectors
+   * in its description names only those. Absent is Everything.
+   */
+  connectionScope?: ConnectionScope;
 }
 
 /**

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

@@ -250,7 +250,7 @@ function makeReviewWorkflow(): IReviewWorkflowService {
 describe('WorkflowService — branch delegation', () => {
   it('listBranches delegates to git.listBranches', async () => {
     const git = makeGit();
-    const branches = [{ name: 'main', isCurrent: true, isProtected: true, ahead: 0, behind: 0, hasRemote: true }];
+    const branches = [{ name: 'main', isCurrent: true, isProtected: true, hasRemote: true }];
     (git.listBranches as ReturnType<typeof vi.fn>).mockResolvedValue(branches);
 
     const svc = new WorkflowService(makeDb(), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());

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

@@ -344,7 +344,7 @@ describe('WorkflowService.retireRemoteGoneClone — what can bring the branch ba
       }),
       createBranch: vi.fn(async (_ws: string, name: string) => {
         order.push('create');
-        return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
+        return { name, isProtected: false, hasRemote: true };
       }),
     } as unknown as GitService;
     const workspaceService = {

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

@@ -104,6 +104,9 @@ const workspaceService = {
 const workflowService = {
   listBranches: async (ws: string) => {
     calls.push(['listBranches', ws]);
+    // A real listing fetches first; mark when that fetch has landed.
+    await new Promise((r) => setTimeout(r, 0));
+    calls.push(['listBranches:fetched', ws]);
     return [{ name: 'main', isProtected: true }];
   },
   commitChange: async (ws: string, user: { id: string }, body: unknown) => {
@@ -117,7 +120,7 @@ const workflowService = {
   },
   createBranch: async (ws: string, name: string) => {
     calls.push(['createBranch', ws, name]);
-    return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
+    return { name, isProtected: false, hasRemote: true };
   },
   acquireLock: async (ws: string, branch: string, path: string) => {
     calls.push(['acquireLock', ws, branch, path]);
@@ -206,6 +209,10 @@ const workflowService = {
     calls.push(['branchStatus', ws]);
     return { branch: ws, hasUpstream: true, unmergedFromUpstream: true };
   },
+  branchCounts: async (ws: string) => {
+    calls.push(['branchCounts', ws]);
+    return { ahead: 3, behind: 1 };
+  },
   listPendingChangePaths: async (ws: string) => {
     calls.push(['listPendingChangePaths', ws]);
     return ['knowledge-base/KnowledgeBase/Pending.md'];
@@ -518,6 +525,24 @@ describe('registerWorkflowTools', () => {
     expect(calls).toContainEqual(['listBranches', 'existing-ws']);
   });
 
+  it('list_branches declares names, protection and remote presence, and no commit counts', async () => {
+    await start();
+    for (const tools of [await registryRef!.listInternal(), await registryRef!.listExternal()]) {
+      const listBranches = tools.find((t) => t.name === 'list_branches')!;
+      const branch = (listBranches.outputs as { properties: { branches: { items: { properties: object; required: string[] } } } })
+        .properties.branches.items;
+      expect(Object.keys(branch.properties).sort()).toEqual(['hasRemote', 'isProtected', 'name']);
+      expect([...branch.required].sort()).toEqual(['hasRemote', 'isProtected', 'name']);
+      expect(listBranches.description).toContain('{ name, isProtected, hasRemote }');
+      expect(listBranches.description).not.toMatch(/\bahead\b,|\bbehind\b,/);
+      // The counts are still `branch_status`'s answer, for its one branch.
+      const branchStatus = tools.find((t) => t.name === 'branch_status')!;
+      expect((branchStatus.outputs as { required: string[] }).required).toEqual(
+        expect.arrayContaining(['ahead', 'behind', 'behindRemote']),
+      );
+    }
+  });
+
   it('open_change_request acts on the SOURCE branch\'s workspace', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/open_change_request`, writeTok(), {
@@ -1008,6 +1033,26 @@ describe('save_file and the repository folder', () => {
     expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
   });
 
+  it('refuses a tmp ref in every path input, before any lock — save_file, the history tools and update_branch\'s resolutions alike', async () => {
+    const base = await start();
+    const calls_: Array<[string, Record<string, unknown>]> = [
+      ['save_file', { path: '__tmp__/chat-uploads/plan.xlsx' }],
+      ['read_file_at', { path: '__tmp__/chat-uploads/plan.xlsx', at: 'HEAD' }],
+      ['compare_file', { path: '__tmp__/chat-uploads/plan.xlsx' }],
+      ['list_file_changes', { path: '__tmp__/chat-uploads/plan.xlsx' }],
+      ['update_branch', { resolutions: [{ path: '__tmp__/chat-uploads/plan.xlsx', choose: 'ours' }] }],
+    ];
+    for (const [tool, args] of calls_) {
+      const res = await post(`${base}/api/agent/tools/${tool}`, writeTok(), { ...args, branch: WS });
+      expect(res.status, tool).toBe(400);
+      const body = (await res.json()) as { error: string; kind: string };
+      expect(body.kind, tool).toBe('tmp-ref-read-only');
+      expect(body.error).toContain(`${tool} does not take one there`);
+      expect(body.error).toContain('copy_file');
+    }
+    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 });
@@ -1165,8 +1210,9 @@ describe('history and syncing tools', () => {
       // The listing double names only `main`, so the draft's own entry is unknown.
       isProtected: false,
       hasRemote: true,
-      ahead: null,
-      behind: null,
+      // Counted for the draft alone, by its own workspace — not read off a listing.
+      ahead: 3,
+      behind: 1,
       behindRemote: true,
       uncommittedPaths: ['KnowledgeBase/Pending.md'],
       forkBase: 'main',
@@ -1175,6 +1221,11 @@ describe('history and syncing tools', () => {
       withheldPaths: 0,
     });
     expect(calls).toContainEqual(['changedPathsBetweenBranches', DRAFT_WS, 'main', DRAFT]);
+    expect(calls).toContainEqual(['branchCounts', DRAFT_WS]);
+    // Counted only once the listing's fetch has refreshed the remote-tracking refs.
+    const fetched = calls.findIndex((c) => c[0] === 'listBranches:fetched' && c[1] === DRAFT_WS);
+    expect(fetched).toBeGreaterThanOrEqual(0);
+    expect(calls.findIndex((c) => c[0] === 'branchCounts')).toBeGreaterThan(fetched);
 
     calls = [];
     const named = await post(tool(base, 'branch_status'), writeTok(), { branch: DRAFT, base: 'release' });

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

@@ -36,11 +36,9 @@ const branchSchema: JsonSchema = {
   properties: {
     name: { type: 'string' },
     isProtected: { type: 'boolean' },
-    ahead: { type: ['integer', 'null'], description: 'Commits ahead of upstream / nearest protected base; null if unresolved.' },
-    behind: { type: ['integer', 'null'], description: 'Commits behind; null if unresolved.' },
     hasRemote: { type: 'boolean', description: 'True iff `origin/<name>` exists after the last fetch.' },
   },
-  required: ['name', 'isProtected', 'ahead', 'behind', 'hasRemote'],
+  required: ['name', 'isProtected', 'hasRemote'],
 };
 
 const commitSchema: JsonSchema = {
@@ -239,7 +237,9 @@ export function registerWorkflowTools(
         // `getFilesystem` — so the branch-less call the tool handler refuses
         // before this runs would otherwise commit to, or fork from, a
         // workspace literally named "undefined".
-        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx),
+        // The normaliser also refuses a tmp ref (`__tmp__/…`) in every path
+        // input: none of these tools takes one (see `kb-fs/tmp-ref.ts`).
+        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName, { tool: spec.name }), ctx),
         { write: spec.write },
       ),
     );
@@ -258,7 +258,8 @@ export function registerWorkflowTools(
     name: 'list_branches',
     description:
       'List every draft known to the repository (protected versions + unprotected drafts, ' +
-      'local and on the shared remote). Returns `{ branches: [{ name, isProtected, ahead, behind, hasRemote }] }`. ' +
+      'local and on the shared remote). Returns `{ branches: [{ name, isProtected, hasRemote }] }`; ' +
+      'how far one branch is ahead or behind is `branch_status`\'s answer. ' +
       'Takes no arguments — branch listing is repo-global, not scoped to any one draft.',
     // Repo-global: the branch set is the same from any clone, so don't require
     // (and risk cloning) a model-named branch — resolve any existing workspace.
@@ -278,9 +279,10 @@ export function registerWorkflowTools(
   mount({
     name: 'commit_change',
     description:
-      'Save the currently-pending file edits as a new change on the current branch. Each change ' +
-      'must affect exactly one file — if multiple files are dirty, returns a structured error ' +
-      'listing them; commit them one at a time. Refused on protected branches without write permission.',
+      'Commit, as you, the one file left uncommitted on `branch`, without sharing it. Writes commit and share ' +
+      'on their own moments later (`branch_status` lists those still landing); `unzip` leaves its files uncommitted. ' +
+      'If several files are uncommitted, returns a structured error listing them; commit them one at a time. ' +
+      'Refused on protected branches without write permission.',
     inputs: {
       type: 'object',
       properties: {
@@ -308,7 +310,7 @@ export function registerWorkflowTools(
     name: 'save_file',
     description:
       'Schedule the file at <path> for commit + push using whatever bytes are on disk (no content ' +
-      'rewrite) — for binary uploads or files left uncommitted. On lock contention returns ' +
+      'rewrite) — for files left uncommitted, such as those `unzip` extracts. On lock contention returns ' +
       '`{ saved: false, reason }` rather than throwing. The commit lands asynchronously.',
     inputs: {
       type: 'object',
@@ -356,8 +358,9 @@ export function registerWorkflowTools(
   mount({
     name: 'share_current_branch',
     description:
-      'Publish the current branch to the shared remote so teammates and any change request pick up ' +
-      'your commits. No arguments. Refused on protected branches without write permission.',
+      'Publish `branch` to the shared remote so teammates and any change request pick up its commits. ' +
+      'Writes already share on their own: this is for sharing again after a refused push (`branch_status` shows ' +
+      'the branch ahead). Refused on protected branches without write permission.',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
       type: 'object',
@@ -376,10 +379,11 @@ export function registerWorkflowTools(
     description:
       'Create a new unprotected draft named `name`, forked from the existing branch `branch`. The ' +
       `backend rejects protected names (${protectedInline(kb)}) and filesystem-invalid names — surface ` +
-      'those errors verbatim. Convention: `<email-localpart>/<kebab-slug>`. Does NOT switch the ' +
-      'agent onto the new draft.',
+      'those errors verbatim. Name it `<you>/<kebab-slug>`: `<you>` is the person\'s email before the @, in lower case, ' +
+      'with each run of characters other than letters and digits as one `-` (`paul.brandt@` gives `paul-brandt/`). ' +
+      'Only that prefix makes the draft theirs, to delete later. Does NOT switch the agent onto the new draft.',
     // `branch` here is the fork BASE — its own meaning — so skip the generic
-    // workspace-`branch` injection ("the branch you are currently working on"),
+    // workspace-`branch` injection ("the branch to work on: ... or your draft"),
     // whose wording invites filling in the draft being created instead.
     skipBranch: true,
     // The handler refuses a missing `name` with a message that says what the
@@ -388,7 +392,7 @@ export function registerWorkflowTools(
     inputs: {
       type: 'object',
       properties: {
-        name: { type: 'string', minLength: 1, description: 'Name of the draft to create (`<email-localpart>/<kebab-slug>` for user drafts). Must not exist yet.' },
+        name: { type: 'string', minLength: 1, description: 'Name of the draft to create (`<you>/<kebab-slug>` for user drafts, as the description says). Must not exist yet.' },
         branch: { type: 'string', minLength: 1, description: 'Existing branch to fork the new draft from — usually the branch you are currently on.' },
       },
       required: ['name', 'branch'],
@@ -436,7 +440,7 @@ export function registerWorkflowTools(
     description:
       'Open a change request from a draft branch into a target branch. Auto-merges the latest target ' +
       'into the source first, pushes, then creates the CR. On conflicts returns a ' +
-      '`change-request-conflicts` error with affected paths. The author marker is injected server-side. ' +
+      '`change-request-conflicts` error with affected paths. ' +
       'Answers a SUMMARY, not the request\'s content: `url` first (hand it to the user), then `number`, ' +
       '`title`, `state`, `sourceBranch`, `targetBranch`, `approvals` (who must approve each file), ' +
       '`mergeBlockedReasons` (what blocks the merge), and `files` — the changed paths with their kind of ' +
@@ -548,12 +552,13 @@ export function registerWorkflowTools(
     name: 'merge_branch',
     description:
       'Merge branch `source` into branch `target` as you, and publish `target`. An agent proposes and syncs; ' +
-      'a person merges: this tool never lands a change request. It refuses while a change request from `source` ' +
+      'a person merges: this never lands a change request. It refuses while a change request from `source` ' +
       'into `target` is open (naming it): ask the user to review it in the app. It refuses ' +
-      'when `target` is a protected branch unless you could commit every changed file directly to it. ' +
+      'when `target` is a protected branch unless you could commit every changed file directly to it (never ' +
+      'for a change to `roles.yaml`). ' +
       'SYNC: merging the target into your draft (`source` = the change request\'s target, `target` = your draft) ' +
       'is always allowed, even with the draft\'s request open. ' +
-      'Writes are committed asynchronously; the merge first waits up to 20s for those on `source`. ' +
+      'Writes are committed asynchronously; it waits up to 20s for those on `source`. ' +
       'Returns `merged` with the merge commit; `nothing-to-merge` with `target`\'s tip when it already holds ' +
       'all of `source`; `pending-commits` (nothing merged) when writes are still committing — retry shortly — ' +
       'or one failed (`needsAttention`: tell the user); or `conflicts-need-resolution` with the conflicting ' +
@@ -617,7 +622,7 @@ export function registerWorkflowTools(
     name: 'delete_branch',
     description:
       'Delete branch `name` from the shared repository and the server. Allowed for the ' +
-      'branch\'s author (`<email-localpart>/…`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
+      'branch\'s author (`<you>/…` per `create_branch`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
       'protected branch, a name that is not a branch, a branch with saves still landing or a file held ' +
       '(retry once they land). An open change request from or into it that proposes nothing is closed and the ' +
       'delete goes ahead; one that still proposes something refuses it, naming and linking it: its author ' +
@@ -835,13 +840,13 @@ export function registerWorkflowTools(
       '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.',
+      'just before that commit. To put an earlier version back, write it with `write_file`. Takes your ' +
+      'read of the file on `branch` now and, for a branch, also at its tip.',
     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.' },
+        at: { type: 'string', minLength: 1, description: 'A full commit sha (40 or 64 hex characters), or a branch name.' },
         sessionId: SESSION_ID_INPUT,
       },
       required: ['path', 'at'],
@@ -978,9 +983,13 @@ export function registerWorkflowTools(
       // 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([
+      // The counts alone wait for the listing: its fetch refreshes the
+      // remote-tracking refs they are measured against.
+      const [status, [branches, counts], pending, forkBase] = await Promise.all([
         ctx.workflowService.branchStatus(workspaceId),
-        ctx.workflowService.listBranches(workspaceId),
+        ctx.workflowService
+          .listBranches(workspaceId)
+          .then(async (listed) => [listed, await ctx.workflowService.branchCounts(workspaceId)] as const),
         ctx.workflowService.listPendingChangePaths(workspaceId),
         ctx.workflowService.resolveForkBase(workspaceId, branch),
       ]);
@@ -1000,8 +1009,8 @@ export function registerWorkflowTools(
         branch,
         isProtected: info?.isProtected ?? kb.protectedBranches.has(branch),
         hasRemote: info?.hasRemote ?? status.hasUpstream,
-        ahead: info?.ahead ?? null,
-        behind: info?.behind ?? null,
+        ahead: counts.ahead,
+        behind: counts.behind,
         behindRemote: status.unmergedFromUpstream,
         uncommittedPaths,
         forkBase,