@bevel-software/platform-core-backend 0.22.0 → 0.24.0

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

@@ -0,0 +1,378 @@
+import express from 'express';
+import { describe, expect, it } from 'vitest';
+import {
+  CALL_TOOL_CHAIN_NAME,
+  CHAIN_FAILURES_RULE,
+  CHAIN_LARGE_RESULTS_RULE,
+  codeModeMetaTools,
+} 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 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 { 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 { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength, firstSentenceEnd } from '../description-length.js';
+import {
+  POINTER_GUIDE_NAME_BUDGET,
+  SHARED_RULES_POINTER_MAX,
+  TOOL_PREFIX_CAP,
+  sharedFileRules,
+  sharedRulesPointer,
+} from '../../agent-instructions/index.js';
+import { isPlatformFile, platformFilesByDepth } from '@bevel-software/platform-shared';
+
+/**
+ * The cap exists because clients cut a long tool description, and they cut it
+ * from the END — where the text specific to the tool sits. Agents reported
+ * `file_stat`, `read_file`, `write_file` and `write_files` arriving as
+ * "[truncated]". So this measures what a client is actually handed, and fails
+ * 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
+ * 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 ending in the pointer.
+ * 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[], pointer = sharedRulesPointer(testKbContext().layout)) {
+  return codeModeMetaTools(
+    EXTERNAL_KB_MANUAL_NAME,
+    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
+    { sharedRulesPointer: pointer },
+  );
+}
+
+/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
+async function hexisTools(): 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(),
+  );
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb);
+  registerPluginsTools(registry);
+  registerSkillsTools(registry, router, toolAuth, toolHandler, emptySkills);
+  registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
+    accessControl: unused(),
+    variableStatus: unused(),
+    kb,
+  });
+
+  const byName = new Map<string, UtcpTool>();
+  // The meta-tools as a client is served them: the chain carries its pointer
+  // (`mcp.service.ts` appends it at the mount), so the catalog measured here is
+  // the catalog that goes out rather than the unpointed 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())
+      .map((t) => ({ tool: t.name, chars: clientVisibleLength(t) }))
+      .filter((m) => m.chars > TOOL_DESCRIPTION_CAP)
+      .sort((a, b) => b.chars - a.chars);
+    // The message names the tool and its length, because "a description is too
+    // long" sends the next reader back to measuring them by hand.
+    expect(
+      over,
+      over.map((m) => `${m.tool}: ${m.chars} characters (cap ${TOOL_DESCRIPTION_CAP})`).join('\n'),
+    ).toEqual([]);
+  });
+
+  it(`leaves the tool's own first sentence inside the shorter ${CLIENT_SHORT_CUT}-character cut`, async () => {
+    // The cap does not answer the ~500-character cut; the ORDER of the text
+    // does, and this is where that claim is checked rather than asserted in a
+    // comment. A client that stops at 500 must still have the sentence saying
+    // what the tool does — what it loses is the pointer tail, and the file the
+    // pointer names is stated in the handshake instructions and in the guide
+    // anyway. Lowering the cap to 500 would not buy this; only order does.
+    const late = (await hexisTools())
+      .map((t) => ({ tool: t.name, endsAt: firstSentenceEnd(t) }))
+      .filter((m) => m.endsAt > CLIENT_SHORT_CUT)
+      .sort((a, b) => b.endsAt - a.endsAt);
+    expect(
+      late,
+      late
+        .map((m) => `${m.tool}: first sentence ends at ${m.endsAt} (cut ${CLIENT_SHORT_CUT}) — lead with what it does`)
+        .join('\n'),
+    ).toEqual([]);
+  });
+
+  it('holds the cap on a deployment that renamed its guide, not only under the default', async () => {
+    // The pointer ends every file tool's description and its length moves with
+    // a deployment setting, so a cap checked only against the nine characters
+    // of `AGENTS.md` guarantees nothing about the catalog a renamed deployment
+    // serves. Two things make it hold: the pointer is bounded by construction
+    // (past `POINTER_GUIDE_NAME_BUDGET` the guide is named by its role), and
+    // `clientVisibleLength` charges the worst case rather than this layout's.
+    const tools = await hexisTools();
+    const atWorst = tools
+      .map((t) => ({ tool: t.name, chars: clientVisibleLength(t) }))
+      .filter((m) => m.chars > TOOL_DESCRIPTION_CAP);
+    expect(atWorst, atWorst.map((m) => `${m.tool}: ${m.chars}`).join('\n')).toEqual([]);
+
+    // And measured literally, under the longest guide name a deployment can
+    // actually configure: every description still fits.
+    const longest = `${'x'.repeat(252)}.md`;
+    const pointerHere = sharedRulesPointer(testKbContext().layout);
+    const pointerThere = sharedRulesPointer({ ...testKbContext().layout, agentsFile: longest });
+    expect(pointerThere.length).toBeLessThanOrEqual(SHARED_RULES_POINTER_MAX);
+    for (const tool of tools) {
+      if (!tool.description?.endsWith(pointerHere)) continue;
+      const asRenamed = tool.description.slice(0, -pointerHere.length) + pointerThere;
+      const chars = clientVisibleLength({ name: tool.name, description: asRenamed });
+      expect(chars, `${tool.name} on a renamed deployment`).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    }
+  });
+
+  it('measures a prefixed tool with the prefix a client sees, not without it', async () => {
+    // The four knowledge-base tools carry the deployment's tool prefix ahead of
+    // their description on the MCP surface — up to `TOOL_PREFIX_CAP` characters
+    // the admin writes. A cap applied to the bare description would pass while
+    // the catalog the agent reads was over it by 300.
+    const read = (await hexisTools()).find((t) => t.name === 'read_file');
+    expect(read).toBeDefined();
+    // Its own text, with the pointer charged at its worst case rather than at
+    // this layout's, plus the prefix at ITS cap and the blank line between.
+    const pointer = sharedRulesPointer();
+    const ownAtWorstPointer = read!.description!.length - pointer.length + SHARED_RULES_POINTER_MAX;
+    expect(clientVisibleLength(read!)).toBe(ownAtWorstPointer + TOOL_PREFIX_CAP + 2);
+    expect(ownAtWorstPointer + TOOL_PREFIX_CAP + 2).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+  });
+
+  it('fails, naming the tool, when a paragraph takes a description over the cap', () => {
+    const padded = { name: 'write_file', description: 'x'.repeat(TOOL_DESCRIPTION_CAP + 1) } as UtcpTool;
+    expect(clientVisibleLength(padded)).toBeGreaterThan(TOOL_DESCRIPTION_CAP);
+    // A tool with no description at all is not over the cap.
+    expect(clientVisibleLength({ name: 'nothing' } as UtcpTool)).toBe(0);
+    // Unless it is a PREFIXED one: the prefix is sent on its own then (no
+    // description, so no blank line either), and that text is what the client
+    // was handed. Measuring it as nothing would hide the only thing it got.
+    expect(clientVisibleLength({ name: 'read_file' } as UtcpTool)).toBe(TOOL_PREFIX_CAP);
+  });
+
+  it('measures the catalog, which is what a client lists — and says what is outside it', async () => {
+    // The cap is about `tools/list`: a client cuts what it was sent. The ONE
+    // long description this repository still writes is the in-process Mastra
+    // `call_tool_chain`, which no client lists — the in-process agent is handed
+    // it directly — and which OPENS with `@utcp/code-mode`'s own 2,500-character
+    // usage guide, text this repository does not own. It is left as it is, on
+    // purpose, and this assertion is what keeps that a stated fact rather than
+    // an oversight: if it ever reaches the catalog, the cap test above measures
+    // it like everything else.
+    const { createCallToolChainTool } = await import('../../code-mode/code-mode.tool.js');
+    const mastraTool = createCallToolChainTool(unused(), unused(), EXTERNAL_KB_MANUAL_NAME) as unknown as {
+      description: string;
+    };
+    expect(mastraTool.description).toContain('UTCP CodeMode Tool Usage Guide');
+    expect(mastraTool.description.length).toBeGreaterThan(TOOL_DESCRIPTION_CAP);
+    expect((await hexisTools()).some((t) => t.description === mastraTool.description)).toBe(false);
+  });
+});
+
+describe('every file tool ends with the pointer and carries no shared paragraph', () => {
+  /** The tools that used to carry the shared paragraphs — every `mount`ed one. */
+  const FILE_TOOLS = [
+    'read_file',
+    'list_files',
+    'file_stat',
+    'grep',
+    'write_file',
+    'write_files',
+    'edit_file',
+    'delete_file',
+    'delete_folder',
+    'mkdir',
+    'move_file',
+    'copy_file',
+    'unzip',
+    'execute_command',
+    'apply_file_upload',
+  ];
+
+  it('ends each description with the one sentence naming the shared rules', async () => {
+    const tools = await hexisTools();
+    const pointer = sharedRulesPointer(testKbContext().layout);
+    for (const name of FILE_TOOLS) {
+      const def = tools.find((t) => t.name === name);
+      expect(def, name).toBeDefined();
+      expect(def!.description!.endsWith(pointer), `${name} must end with: ${pointer}`).toBe(true);
+      // Ends with a full sentence, so nothing reads as cut off mid-thought.
+      expect(def!.description!.trimEnd().endsWith('.'), name).toBe(true);
+    }
+  });
+
+  it('no longer repeats a shared paragraph inside a description', async () => {
+    const tools = await hexisTools();
+    // One recognisable fragment per rule that moved out. Searched across EVERY
+    // Hexis description, not only the file tools: a rule that came back by
+    // being pasted into a neighbouring tool is the same regression.
+    const moved = [
+      'Content rule (the same on every file tool)',
+      'they refuse documents, images, archives and other binary files',
+      '`mode` decides what may happen at a path and DEFAULTS TO',
+      'Images: keep them in an `assets/` folder',
+      'Escape sequences: some clients decode them in arguments',
+      'If this is refused for permissions',
+      'Before your first read or change in a workspace',
+      'Do NOT set `confirm: true` on your first call',
+    ];
+    for (const fragment of moved) {
+      const carriers = tools.filter((t) => (t.description ?? '').includes(fragment)).map((t) => t.name);
+      expect(carriers, `"${fragment}" is a shared rule and belongs in the shared places only`).toEqual([]);
+    }
+  });
+});
+
+describe('the shared rules describe the tools they name', () => {
+  it('ends the chain description with the pointer too, under the cap', async () => {
+    // What a chain does with a failure, a large result or an image is true of
+    // every call, so it is stated in the shared rules — and the clients that
+    // drop the handshake `instructions` see only descriptions, so the chain
+    // gets the same pointer every file tool ends with. Composed at the mount,
+    // because `mcp-core` may not spell a guide name that is a deployment
+    // setting.
+    const pointer = sharedRulesPointer(testKbContext().layout);
+    const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
+    expect(served.description!.endsWith(pointer)).toBe(true);
+    expect(clientVisibleLength(served)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    // The other two describe the registry, not what a call does: no pointer.
+    for (const tool of servedMetaTools([]).filter((t) => t.name !== CALL_TOOL_CHAIN_NAME)) {
+      expect(tool.description).not.toContain(pointer);
+    }
+  });
+
+  it('states what a chain does in the shared rules, and not a second time on the chain', async () => {
+    // The pointer is only honest if the rules it points at are THERE. These
+    // two were paragraphs of the chain's description; they moved, whole, and a
+    // description that kept them as well would be the long one a client cuts.
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'tool-chain')!;
+    expect(rule.body).toContain(CHAIN_FAILURES_RULE);
+    expect(rule.body).toContain(CHAIN_LARGE_RESULTS_RULE);
+    const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
+    expect(served.description).not.toContain(CHAIN_FAILURES_RULE);
+    expect(served.description).not.toContain(CHAIN_LARGE_RESULTS_RULE);
+    // What a chained read does to an image was already one of the shared rules.
+    const content = sharedFileRules(testKbContext().layout).find((r) => r.id === 'content-kinds')!;
+    expect(content.body).toContain('image_omitted');
+  });
+
+  it('keeps the rules on the chain itself where no shared rules are served', () => {
+    // The standalone bridge proxies a deployment whose guide it cannot name, so
+    // it passes no pointer — and an agent there must still be told what a chain
+    // that timed out, or answered too much, or read an image, does.
+    const [chain] = codeModeMetaTools('hexis', []).filter((t) => t.name === CALL_TOOL_CHAIN_NAME);
+    expect(chain.description).toContain(CHAIN_FAILURES_RULE);
+    expect(chain.description).toContain(CHAIN_LARGE_RESULTS_RULE);
+    expect(chain.description).toContain('image_omitted');
+  });
+
+  it('names a dry run only on the tools that take one', async () => {
+    // A rule is worse than no rule when it promises an argument the tool
+    // rejects: `delete_file` has no `dryRun`, so an agent told to preflight a
+    // single-file delete gets a validation error on the safe call and learns to
+    // skip it. Read off the schemas rather than asserted by hand.
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'dry-run-confirm')!;
+    const tools = await hexisTools();
+    // `toolDef` wraps a tool's own inputs under `body`, which is the schema a
+    // client validates against — so that is where the argument either is or is not.
+    const takesDryRun = (name: string): boolean => {
+      const inputs = tools.find((t) => t.name === name)?.inputs as
+        | { properties?: { body?: { properties?: Record<string, unknown> } } }
+        | undefined;
+      return inputs?.properties?.body?.properties?.dryRun !== undefined;
+    };
+    expect(takesDryRun('move_file')).toBe(true);
+    expect(takesDryRun('delete_folder')).toBe(true);
+    expect(takesDryRun('delete_file')).toBe(false);
+    // Every tool that takes one, read off the catalog rather than listed here —
+    // a hand-written list is what let `copy_file` gain a `dryRun` on dev while
+    // the rule still named two tools, so an agent reading the guide was told
+    // the copy had no preflight it could run.
+    const withDryRun = tools.filter((t) => takesDryRun(t.name)).map((t) => t.name);
+    expect(withDryRun.length, 'no tool takes a dryRun — the rule would be vacuous').toBeGreaterThan(1);
+    for (const name of withDryRun) {
+      expect(rule.body, name).toContain(name);
+    }
+    // Named, but as the tool that has none — never as one that takes one.
+    expect(rule.body).toContain('delete_file takes neither');
+    expect(rule.body).not.toContain('move_file, delete_file and delete_folder take');
+  });
+
+  it('gives each platform file the depth it actually counts at', () => {
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'managed-items')!;
+    const { anyDepth, rootOnly } = platformFilesByDepth(testKbContext().layout);
+    // The split is the half of the rule a list of names leaves out, and
+    // `isPlatformFile` is the predicate the prose has to match.
+    expect(rule.body).toContain(`${anyDepth.map((n) => `\`${n}\``).join(' or ')} in any folder`);
+    expect(rule.body).toContain(`${rootOnly.map((n) => `\`${n}\``).join(' or ')} at the repository root`);
+    for (const name of anyDepth) expect(isPlatformFile(`Deep/Folder/${name}`, testKbContext().layout), name).toBe(true);
+    for (const name of rootOnly) expect(isPlatformFile(`Deep/Folder/${name}`, testKbContext().layout), name).toBe(false);
+  });
+
+  it('says what unzip extracts, rather than that it takes any bytes', () => {
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'content-kinds')!;
+    // `unzip` refuses anything but a `.zip` (`workspace.service.ts`: "Only .zip
+    // files can be extracted"), so the byte-tool clause must not sweep it in.
+    expect(rule.body).toContain('unzip extracts the entries of a `.zip`');
+    expect(rule.body).not.toContain('and unzip act on bytes of any kind');
+  });
+});

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

@@ -0,0 +1,111 @@
+/**
+ * How long a tool description may be, and how to measure one.
+ *
+ * Clients cut a long description, and they cut it from the END — which is
+ * where the text specific to the tool sits, after whatever shared preamble it
+ * carried. Agents reported `file_stat`, `read_file`, `write_file` and
+ * `write_files` arriving ending in "[truncated]". The rules those descriptions
+ * shared now live in one place (see `agent-instructions/shared-file-rules.ts`)
+ * and each description ends with one sentence pointing there, which is what
+ * makes the cap below reachable rather than aspirational.
+ */
+
+import { TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
+import { PREFIXED_TOOLS } from '../agent-instructions/compose.js';
+import { SHARED_RULES_POINTER_MAX, sharedRulesPointer } from '../agent-instructions/shared-file-rules.js';
+import type { UtcpTool } from './tool.contract.js';
+
+/**
+ * The ceiling on what a client is handed for one tool, enforced by
+ * `__tests__/tool-description-length.test.ts`.
+ *
+ * DERIVED, not published: the clients that cut descriptions do not say where.
+ * Two cuts were observed, and they are different problems. claude.ai cuts
+ * around 500 characters — NOT what this cap answers, and not something a cap
+ * could answer: no useful description of `move_file` fits in 500. What answers
+ * that one is the ORDER of the text, which is why the deployment's purpose line
+ * is prepended rather than appended (see `prefixToolDescription`) and why every
+ * description now leads with what the tool does and ends with the pointer: a
+ * cut at 500 then takes the pointer and leaves the tool. The other cut is the
+ * four-figure one agents reported on `file_stat`, `read_file`, `write_file` and
+ * `write_files`, and 1,200 sits below it with room to spare.
+ *
+ * So the cap is a ceiling on growth rather than a guarantee of survival, and it
+ * is a number the reviewer may move: the point of pinning it is that moving it
+ * is a decision someone takes, rather than a paragraph someone appends.
+ */
+export const TOOL_DESCRIPTION_CAP = 1_200;
+
+/**
+ * The OTHER cut — the ~500 characters claude.ai allows — as a number the tests
+ * can hold something to.
+ *
+ * It is deliberately not the value of {@link TOOL_DESCRIPTION_CAP}, and the
+ * difference is the whole point: lowering the cap to 500 would not make these
+ * descriptions survive that client, it would only move the loss from the client
+ * to the source, because no useful description of `move_file` or `file_stat`
+ * fits in 500 characters and shortening them to fit means dropping facts an
+ * agent needs.
+ *
+ * What survives a cut here is decided by ORDER instead, and order is testable:
+ * the purpose prefix goes first, the tool's own opening sentence next, the
+ * pointer to the shared rules last. So a cut at 500 takes the pointer — which
+ * costs the agent the name of a file the handshake instructions and the guide
+ * both state anyway — and leaves the sentence saying what the tool does.
+ * {@link firstSentenceEnd} measures where that sentence ends, and the suite
+ * pins it under this number for every tool, so the claim above is a check
+ * rather than a comment.
+ */
+export const CLIENT_SHORT_CUT = 500;
+
+/**
+ * Where the tool's OWN opening sentence ends in the text a client is handed:
+ * the purpose prefix counted at its cap, as in {@link clientVisibleLength}, and
+ * the pointer not counted at all, since it is the part a short cut is meant to
+ * take.
+ *
+ * A description with no sentence-ending punctuation counts whole — the honest
+ * answer for text that never finishes a sentence.
+ */
+export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>): number {
+  const prefix = PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0;
+  const description = tool.description ?? '';
+  if (description === '') return prefix;
+  const pointer = sharedRulesPointer();
+  const own = description.endsWith(pointer) ? description.slice(0, -pointer.length) : description;
+  const firstSentence = own.match(/^[\s\S]*?[.!?](?=\s|$)/)?.[0] ?? own;
+  return prefix + firstSentence.length;
+}
+
+/**
+ * The length of the description as a CLIENT receives it — which for the four
+ * knowledge-base tools includes the deployment's purpose prefix, since the MCP
+ * surface prepends it (`prefixToolDescription`) and the client cuts the result.
+ * Measured at the prefix's CAP rather than at whatever the current admin wrote:
+ * the cap is what an admin may grow their text to without being told, so a
+ * description that only fits beside a short prefix does not really fit.
+ *
+ * The pointer sentence is measured the same way, for the same reason. It ends
+ * every file tool's description and its length moves with a DEPLOYMENT SETTING
+ * — the guide's file name — so a description measured beside the nine
+ * characters of `AGENTS.md` would pass here and arrive cut on a deployment
+ * that renamed its guide. Whatever pointer a description actually carries is
+ * discounted and charged at {@link SHARED_RULES_POINTER_MAX} instead.
+ */
+export function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>): number {
+  const own = tool.description?.length ?? 0;
+  // A prefixed tool with no description of its own is still handed the prefix,
+  // and nothing else — `prefixToolDescription` sends the prefix alone, with no
+  // blank line after it. Measuring that as zero would under-report the only
+  // text the client got.
+  if (own === 0) return PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP : 0;
+  // The pointer at its worst case rather than at this layout's: swap the one
+  // it carries for the longest it could be. A description that does not end
+  // with it (`start_session`, the proxied tools) is charged nothing.
+  const pointer = sharedRulesPointer();
+  const atWorstPointer = tool.description!.endsWith(pointer)
+    ? own - pointer.length + SHARED_RULES_POINTER_MAX
+    : own;
+  // `+ 2` for the blank line `prefixToolDescription` puts between the two.
+  return PREFIXED_TOOLS.has(tool.name) ? atWorstPointer + TOOL_PREFIX_CAP + 2 : atWorstPointer;
+}

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

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { PendingCommitsService } from '../pending-commits.service.js';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * Commits still queued for a branch when the knowledge-base repository is
+ * REPLACED.
+ *
+ * A release enqueues the bytes and only then drops its lock, so the moment the
+ * locks on a branch are dropped there may be rows already waiting — written
+ * against a working copy of the repository that is gone. Left `pending`, the
+ * worker picks them up after the re-clone and commits them onto a same-named
+ * branch of a DIFFERENT repository: somebody else's file, overwritten by a
+ * change nobody made to it.
+ *
+ * So they are escalated, never dropped: the bytes stay in the row, the reason
+ * is on it, and a person decides.
+ */
+function makeFakeDb(moved: Array<{ id: string }>) {
+  const sets: Record<string, unknown>[] = [];
+  const db = {
+    update: vi.fn(() => ({
+      set: (values: Record<string, unknown>) => {
+        sets.push(values);
+        return { where: () => ({ returning: async () => moved }) };
+      },
+    })),
+    // Queued bytes are never thrown away over this.
+    delete: () => {
+      throw new Error('a queued commit must never be deleted');
+    },
+  } as unknown as Database;
+  return { db, sets };
+}
+
+describe('PendingCommitsService.markNeedsAttentionOnBranch', () => {
+  it('escalates every queued commit on the branch, with the reason, and answers how many', async () => {
+    const { db, sets } = makeFakeDb([{ id: 'a' }, { id: 'b' }]);
+    const svc = new PendingCommitsService(db);
+
+    await expect(
+      svc.markNeedsAttentionOnBranch('alice/draft', 'The repository was replaced.'),
+    ).resolves.toBe(2);
+
+    expect(sets).toHaveLength(1);
+    // `needs_attention` is the status the admin surface reads — the row is out
+    // of the worker's reach and in front of a person.
+    expect(sets[0]?.status).toBe('needs_attention');
+    expect(sets[0]?.lastError).toBe('The repository was replaced.');
+    expect(sets[0]?.lastAttemptedAt).toBeInstanceOf(Date);
+  });
+
+  it('answers zero when nothing was queued for that branch', async () => {
+    const { db } = makeFakeDb([]);
+    const svc = new PendingCommitsService(db);
+    await expect(svc.markNeedsAttentionOnBranch('quiet/branch', 'whatever')).resolves.toBe(0);
+  });
+});
+
+/**
+ * The same, keyed on the WORKING COPY that was set aside. Closing change
+ * requests covers their branches and nothing else; a commit queued on the
+ * default branch was written against the repository that was left all the
+ * same, and the path it names is about to hold a clone of another one.
+ */
+describe('PendingCommitsService.markNeedsAttentionInWorkspace', () => {
+  it('escalates every queued commit for the working copy, with the reason, and answers how many', async () => {
+    const { db, sets } = makeFakeDb([{ id: 'a' }, { id: 'b' }, { id: 'c' }]);
+    const svc = new PendingCommitsService(db);
+
+    await expect(svc.markNeedsAttentionInWorkspace('main', 'The repository was replaced.')).resolves.toBe(3);
+
+    expect(sets).toHaveLength(1);
+    expect(sets[0]?.status).toBe('needs_attention');
+    expect(sets[0]?.lastError).toBe('The repository was replaced.');
+    expect(sets[0]?.lastAttemptedAt).toBeInstanceOf(Date);
+  });
+
+  /**
+   * Rows are stored under the encoded id, whichever spelling the caller
+   * enqueued with. The predicate is rendered and read, since the stub does
+   * not evaluate it: the id it compares must be the stored spelling, and it
+   * must match only the two statuses a worker could still write, `pending`
+   * and `running`.
+   */
+  it('looks for the working copy under the id the queue stores, and only for commits still queued', async () => {
+    const wheres: SQL[] = [];
+    const db = {
+      update: () => ({
+        set: () => ({
+          where: (predicate: SQL) => {
+            wheres.push(predicate);
+            return { returning: async () => [] };
+          },
+        }),
+      }),
+    } as unknown as Database;
+    await new PendingCommitsService(db).markNeedsAttentionInWorkspace('alice/feature', 'whatever');
+
+    const { sql: text, params } = new PgDialect().sqlToQuery(wheres[0]!);
+    expect(text).toContain('"workspace_id" =');
+    expect(params).toEqual(['alice%2Ffeature', 'pending', 'running']);
+  });
+
+  it('answers zero when nothing was queued for it', async () => {
+    const { db } = makeFakeDb([]);
+    await expect(new PendingCommitsService(db).markNeedsAttentionInWorkspace('main', 'whatever')).resolves.toBe(0);
+  });
+});

package/src/modules/workflow/__tests__/workflow.routes.history-read-gate.test.ts

@@ -8,6 +8,10 @@ import type { AuthService } from '../../auth/auth.service.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { WorkflowEventBus } from '../event-bus.js';
 import { createWorkflowRoutes } from '../workflow.routes.js';
+import {
+  VersionNotOnBranchError,
+  VERSION_NOT_ON_BRANCH_MESSAGE,
+} from '../../../shared/domain-errors.js';
 
 // A file's history is its content with a time axis: the same default-deny
 // read model that hides a file must hide its commit list, its diffs, and its
@@ -129,6 +133,27 @@ describe('history routes enforce the read model', () => {
     expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
   });
 
+  it.each([
+    ['/show-file?sha=abc1234&path=%s', 'showFileAtChange'],
+    ['/file-at-change?sha=abc1234&path=%s', 'fileAtChange'],
+  ] as const)(
+    '%s: a save off this branch is refused with the history message',
+    async (route, method) => {
+      // The service raises it (the git layer knows the branch); the route has
+      // to pass the typed refusal through with its own status and sentence,
+      // because a reader who is told "not found" about a file that is plainly
+      // there learns the wrong thing. The bytes route carries the same rule,
+      // so neither can be read around through the other.
+      h = await makeHarness();
+      h.workflow[method].mockRejectedValueOnce(new VersionNotOnBranchError());
+      const res = await get(route.replace('%s', OPEN));
+      expect(res.status).toBe(404);
+      expect(((await res.json()) as { error: string }).error).toBe(
+        VERSION_NOT_ON_BRANCH_MESSAGE,
+      );
+    },
+  );
+
   it('an access-model error fails closed, not open', async () => {
     h = await makeHarness();
     h.canRead.mockRejectedValueOnce(new Error('access tree unreadable'));