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

package/src/modules/kb-fs/ref-files.ts

@@ -0,0 +1,279 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { gitDirOf } from './git-dir.js';
+
+/**
+ * Where a ref points, read from the repository's own files instead of a
+ * `git rev-parse` process.
+ *
+ * A branch tip is a small file git maintains: `refs/remotes/origin/<branch>`
+ * as a loose file, or one line of `packed-refs`. Reading it costs a file read
+ * and no fork, and it is exactly as current as the last fetch — the same
+ * freshness a `rev-parse` has. A change-request listing resolves two tips per
+ * open request and the access gates resolve every ref they decide at; with a
+ * hundred open requests that was hundreds of forks per listing, each costing
+ * tens of milliseconds of the main thread on a server holding a large heap.
+ *
+ * What is read, in git's own order: a loose file under the common directory
+ * (a worktree shares `refs/` with the repository it belongs to), then
+ * `packed-refs`. `HEAD` and the per-worktree namespaces (`refs/worktree/`,
+ * `refs/bisect/`, `refs/rewritten/`) are a worktree's own: read loose from
+ * its git directory, never from the common directory, and never packed. A
+ * symbolic ref (`ref: refs/heads/main`) is followed. A tag is never decided
+ * here: its file may hold a tag object, and what that peels to is git's to
+ * say.
+ *
+ * The answer is one of three things, and the caller treats them differently:
+ * `{ sha }` is what git would answer too; `'missing'` means every file git
+ * would consult says there is no such ref, which is as authoritative as
+ * `rev-parse` answering nothing; `'unreadable'` means this reader could not
+ * decide — a repository it does not understand (one whose refs live in a
+ * reftable, say), a tag, a corrupt file, a name it refuses — and the caller
+ * asks git, which is authoritative. Never a guess: a read error is
+ * `'unreadable'`, not `'missing'`, so a flaky disk sends the caller to git
+ * rather than making a branch disappear.
+ *
+ * What the files guarantee about the object: git itself refuses to write a
+ * non-commit under `refs/heads/`, and `refs/remotes/origin/` mirrors the
+ * remote's `refs/heads/`, so a branch tip read here is a commit as surely
+ * as `rev-parse <branch>^{commit}` would make it one. A caller that holds
+ * an object id rather than a name, or a `<rev>^{...}` form, asks git.
+ */
+export type RefFileAnswer = { sha: string } | 'missing' | 'unreadable';
+
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MAX_SYMREF_DEPTH = 5;
+const PER_WORKTREE = /^refs\/(?:worktree|bisect|rewritten)\//;
+
+/** A ref name this reader is willing to turn into a path under `.git`. */
+function isSafeRefName(ref: string): boolean {
+  if (ref === 'HEAD') return true;
+  if (!ref.startsWith('refs/')) return false;
+  if (!/^[A-Za-z0-9._\-/@+]+$/.test(ref)) return false;
+  return !ref.split('/').some((segment) => segment === '' || segment === '.' || segment === '..');
+}
+
+/**
+ * One resolution's view of the repository: the two directories, and the
+ * `packed-refs` table read at most once however many candidates a name
+ * tries — the table can grow with the history, and a name that is missing
+ * as itself consults it for every prefix.
+ */
+interface GitDirs {
+  /** The worktree's own git directory: `HEAD` lives here. */
+  gitDir: string;
+  /** Where `refs/` and `packed-refs` live: the repository, shared by every worktree. */
+  commonDir: string;
+  /** The `packed-refs` table, read on first need; null when it could not be read. */
+  packed?: Promise<Map<string, string> | null>;
+}
+
+async function gitDirsOf(repoDir: string): Promise<GitDirs | null> {
+  let gitDir: string | null;
+  try {
+    gitDir = await gitDirOf(repoDir);
+  } catch {
+    return null;
+  }
+  if (gitDir === null) return null;
+  let commonDir = gitDir;
+  try {
+    const pointer = (await fs.readFile(path.join(gitDir, 'commondir'), 'utf-8')).trim();
+    if (pointer) commonDir = path.resolve(gitDir, pointer);
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  // A repository whose refs live in a reftable (`extensions.refStorage`)
+  // keeps nothing this reader understands under `refs/` or in `packed-refs`:
+  // every name would read as missing. Not a repository for this reader.
+  try {
+    await fs.stat(path.join(commonDir, 'reftable'));
+    return null;
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  try {
+    if (/^\s*refstorage\s*=\s*reftable\s*$/im.test(await fs.readFile(path.join(commonDir, 'config'), 'utf-8'))) {
+      return null;
+    }
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  return { gitDir, commonDir };
+}
+
+/**
+ * `packed-refs`: `<sha> <name>` lines, `^<sha>` peel lines, `#` comments.
+ * Absent file → an empty table. A line that is none of those is a file this
+ * reader does not understand, and the whole table is null (unreadable): a
+ * record it skipped could be the one that was asked for.
+ */
+async function readPackedRefs(commonDir: string): Promise<Map<string, string> | null> {
+  let text: string;
+  try {
+    text = await fs.readFile(path.join(commonDir, 'packed-refs'), 'utf-8');
+  } catch (err) {
+    return isAbsence(err) ? new Map() : null;
+  }
+  const table = new Map<string, string>();
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('^')) {
+      if (!SHA.test(line.slice(1))) return null;
+      continue;
+    }
+    const space = line.indexOf(' ');
+    const sha = space < 0 ? '' : line.slice(0, space);
+    const name = space < 0 ? '' : line.slice(space + 1).trim();
+    if (!SHA.test(sha) || !name) return null;
+    table.set(name, sha);
+  }
+  return table;
+}
+
+/**
+ * The file at `<dir>/<relative>`, read as git reads a loose ref: a symbolic
+ * ref is followed, an object id is the answer, anything else is not decided.
+ */
+async function readLooseRef(dirs: GitDirs, dir: string, relative: string, depth: number): Promise<RefFileAnswer> {
+  let text: string;
+  try {
+    text = (await fs.readFile(path.join(dir, ...relative.split('/')), 'utf-8')).trim();
+  } catch (err) {
+    return isAbsence(err) ? 'missing' : 'unreadable';
+  }
+  if (text.startsWith('ref:')) {
+    const answer = await resolveIn(dirs, text.slice('ref:'.length).trim(), depth + 1);
+    // A symbolic ref whose target is gone is dangling, and git reports it
+    // as such; a packed entry under the symbolic ref's own name does not
+    // stand in for it. Git's to report, then.
+    return answer === 'missing' ? 'unreadable' : answer;
+  }
+  return SHA.test(text) ? { sha: text } : 'unreadable';
+}
+
+async function resolveIn(dirs: GitDirs, ref: string, depth: number): Promise<RefFileAnswer> {
+  if (depth > MAX_SYMREF_DEPTH) return 'unreadable';
+  if (!isSafeRefName(ref)) return 'unreadable';
+  // `HEAD` and the per-worktree namespaces (`refs/worktree/`, `refs/bisect/`,
+  // `refs/rewritten/`) are a worktree's own, kept loose in its git directory
+  // and never packed; everything else is the repository's.
+  const own = ref === 'HEAD' || PER_WORKTREE.test(ref);
+  const loose = await readLooseRef(dirs, own ? dirs.gitDir : dirs.commonDir, ref, depth);
+  if (loose !== 'missing') return decidedHere(ref, loose);
+  if (own) return 'missing';
+  const packed = await (dirs.packed ??= readPackedRefs(dirs.commonDir));
+  if (!packed) return 'unreadable';
+  const sha = packed.get(ref);
+  return sha ? decidedHere(ref, { sha }) : 'missing';
+}
+
+/**
+ * The files decide only where git itself guarantees the object is a commit:
+ * `HEAD` and `refs/heads/*`, which git refuses to point at anything else,
+ * and `refs/remotes/*`, fetched from a remote's `refs/heads/*` under the
+ * same refusal. Anything else that exists — a tag, a ref directly under
+ * `refs/` — may name a tree or a blob, which only git's `^{commit}` refuses,
+ * so it is git's to resolve. Anything that does not exist is as missing as
+ * any other ref, so a short name can move on to the branch git would find
+ * next.
+ */
+function decidedHere(ref: string, answer: RefFileAnswer): RefFileAnswer {
+  if (answer !== 'missing' && answer !== 'unreadable' && !commitGuaranteed(ref)) return 'unreadable';
+  return answer;
+}
+
+function commitGuaranteed(ref: string): boolean {
+  return ref === 'HEAD' || ref.startsWith('refs/heads/') || ref.startsWith('refs/remotes/');
+}
+
+/**
+ * The commit a full ref name (`refs/...`) or `HEAD` points at in the
+ * repository behind `repoDir` (a clone, or a worktree of one). See the module
+ * doc for the three answers and what each means to the caller.
+ *
+ * "Missing" is what `rev-parse` answers nothing for, and `rev-parse` tries
+ * the same prefixes for a full name as for a short one (`refs/heads/x` is
+ * also looked for as `refs/heads/refs/heads/x`), so a name that is missing
+ * as itself but present under a prefix is git's to resolve.
+ */
+export async function readRefSha(repoDir: string, ref: string): Promise<RefFileAnswer> {
+  const dirs = await gitDirsOf(repoDir);
+  if (!dirs) return 'unreadable';
+  const exact = await resolveIn(dirs, ref, 0);
+  if (exact !== 'missing') return exact;
+  for (const name of prefixedCandidates(ref)) {
+    if ((await resolveIn(dirs, name, 0)) !== 'missing') return 'unreadable';
+  }
+  return 'missing';
+}
+
+/**
+ * The names `git rev-parse` tries for `<name>` after `$GIT_DIR/<name>`
+ * itself, in git's order (gitrevisions(7)): `refs/<name>`,
+ * `refs/tags/<name>`, `refs/heads/<name>`, `refs/remotes/<name>`,
+ * `refs/remotes/<name>/HEAD`. The same for every spelling, a full `refs/...`
+ * name included.
+ */
+function prefixedCandidates(name: string): string[] {
+  return [`refs/${name}`, `refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`, `refs/remotes/${name}/HEAD`];
+}
+
+/**
+ * Every name `git rev-parse` tries for a spelling, in git's order: the
+ * spelling itself at `$GIT_DIR/<name>` (which for `HEAD` and a full
+ * `refs/...` name is the ref file), then the prefixed forms. Null for a
+ * spelling this reader does not resolve — an object id or its abbreviation,
+ * a `<rev>^{...}` or `@{...}` form, an empty or option-looking name — which
+ * the caller sends to git.
+ */
+function refNameCandidates(ref: string): string[] | null {
+  if (!ref || ref.startsWith('-')) return null;
+  if (/[\^~:@{}\\\s]/.test(ref)) return null;
+  if (/^[0-9a-f]{4,64}$/i.test(ref)) return null;
+  // `main-worktree/<ref>` and `worktrees/<name>/<ref>` reach another
+  // worktree's own refs (gitrevisions(7)): git's to resolve.
+  if (/^(?:main-worktree|worktrees)\//.test(ref)) return null;
+  return [ref, ...prefixedCandidates(ref)];
+}
+
+/**
+ * {@link readRefSha} for a name as a caller holds it (`main`, `origin/main`,
+ * `HEAD`, `refs/heads/main`): the first of git's candidates that resolves,
+ * starting where git starts, at `$GIT_DIR/<name>` itself. Whatever is found
+ * there (`MERGE_HEAD`, `FETCH_HEAD`, `AUTO_MERGE`, which may name a tree) is
+ * git's to resolve; only its absence lets the `refs/` candidates be read.
+ * `'missing'` only when every candidate is missing; `'unreadable'` as soon
+ * as one cannot be decided, because the undecided one might be the one git
+ * would pick.
+ */
+export async function readRevSha(repoDir: string, rev: string): Promise<RefFileAnswer> {
+  const candidates = refNameCandidates(rev);
+  if (!candidates) return 'unreadable';
+  const dirs = await gitDirsOf(repoDir);
+  if (!dirs) return 'unreadable';
+  for (const name of candidates) {
+    const answer = name === rev ? await resolveAsItself(dirs, rev) : await resolveIn(dirs, name, 0);
+    if (answer !== 'missing') return answer;
+  }
+  return 'missing';
+}
+
+/**
+ * Git's first step for any spelling: `$GIT_DIR/<name>`. For `HEAD` and a
+ * full `refs/...` name that is the ref itself, read as such. For anything
+ * else it is a pseudoref (`MERGE_HEAD`, `AUTO_MERGE`, which may name a
+ * tree), and whatever exists there is git's to resolve.
+ */
+async function resolveAsItself(dirs: GitDirs, rev: string): Promise<RefFileAnswer> {
+  if (rev === 'HEAD' || rev.startsWith('refs/')) return resolveIn(dirs, rev, 0);
+  if (!isSafeRefName(`refs/${rev}`)) return 'unreadable';
+  try {
+    await fs.stat(path.join(dirs.gitDir, ...rev.split('/')));
+    return 'unreadable';
+  } catch (err) {
+    return isAbsence(err) ? 'missing' : 'unreadable';
+  }
+}

package/src/modules/plugins/__tests__/teams.routes.test.ts

@@ -4,6 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { AccessControlService } from '../../access/access-control.service.js';
 import type { ISkillService, SkillSummary } from '../../skills/skills.contract.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { IPluginIndexService, PluginCatalogEntry } from '../plugins.contract.js';
@@ -62,6 +63,10 @@ interface HarnessOpts {
   /** What the org-wide `everyone` principal reads. */
   everyone?: string[];
   email?: string | null;
+  /** Whether the caller is an admin, who is shown every group. Defaults to true. */
+  admin?: boolean;
+  /** The groups the caller is a member of, which is all a non-admin is shown. */
+  memberOf?: string[];
 }
 
 /** The org-wide entry every answer opens with — empty unless `everyone` says otherwise. */
@@ -82,6 +87,12 @@ async function harness(opts: HarnessOpts = {}) {
       opts.team && group in opts.team ? tableVerdict(opts.team[group], paths) : null,
     ),
     canReadAsEveryoneBatch: vi.fn(async (_w: string, paths: string[]) => tableVerdict(opts.everyone, paths)),
+    holdsAdminRootWrite: vi.fn(async () => opts.admin ?? true),
+    groupsOfUser: vi.fn(async () => opts.memberOf ?? []),
+    // The real policy over the two stubs above: who sees which group is the
+    // resolver's one answer, not something a route (or this double) decides.
+    visibleGroups: (wsId: string, email: string, groups: readonly string[]) =>
+      AccessControlService.prototype.visibleGroups.call(accessControl, wsId, email, groups),
   } as unknown as IAccessControl;
   const index = { catalog: async () => CATALOG, invalidate: () => undefined } as IPluginIndexService;
   const skills = { listSkills: async () => SKILLS } as unknown as ISkillService;
@@ -242,6 +253,50 @@ describe('GET /api/teams', () => {
     );
   });
 
+  it("shows someone who is not an admin only the groups they are in, never another group's name", async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: {
+        'Sales Team': ['Plugins/GTM', 'Skills/Sales/outreach/SKILL.md', 'Plugins/GTM/mcp.json'],
+        'Finance Team': ['Plugins/Finance', 'Skills/Finance/ledger/SKILL.md', 'Plugins/Finance/books.tool'],
+      },
+      admin: false,
+      memberOf: ['Sales Team'],
+    });
+    const res = await h.get();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      teams: [
+        NOTHING_ORG_WIDE,
+        { name: 'Sales Team', plugins: ['gtm'], skills: ['outreach'], tools: ['hubspot'] },
+      ],
+    });
+    // A group that is not listed is not asked about either.
+    expect(h.accessControl.canReadAsGroupBatch).not.toHaveBeenCalledWith(
+      expect.anything(),
+      'Finance Team',
+      expect.anything(),
+    );
+  });
+
+  it('shows someone in no group, who is not an admin, Everyone alone', async () => {
+    const h = await harness({ groups: ['Sales Team'], caller: EVERYTHING, team: { 'Sales Team': [] }, admin: false });
+    expect(await (await h.get()).json()).toEqual({ teams: [NOTHING_ORG_WIDE] });
+  });
+
+  it('shows an admin every group, including ones they are not in', async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: { 'Sales Team': [], 'Finance Team': [] },
+      admin: true,
+      memberOf: [],
+    });
+    const body = (await (await h.get()).json()) as { teams: { name: string }[] };
+    expect(body.teams.map((t) => t.name)).toEqual(['Everyone', 'Sales Team', 'Finance Team']);
+  });
+
   it('is 401 without a caller', async () => {
     const h = await harness({ email: null });
     expect((await h.get()).status).toBe(401);

package/src/modules/plugins/teams.routes.ts

@@ -37,6 +37,10 @@ import type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract
  * what `read: everyone` (or a public plugin) reaches. Same slice, same
  * caller gate, asked of the resolver as `canReadAsEveryoneBatch`. The name
  * cannot collide with a group's: `everyone` is reserved by the grammar.
+ *
+ * The groups listed after it are every group for an admin, and only the
+ * caller's own groups for anyone else (`groupsOfUser`), so the lens never
+ * names a group the caller has no part in.
  */
 export interface TeamAccess {
   name: string;
@@ -110,10 +114,19 @@ export function createTeamsRoutes(
         };
       };
 
+      // Which groups to list: the resolver's one answer to who sees which
+      // group (every group for an admin, only their own for anyone else), the
+      // same the share dialog offers and a grant may name. A group's NAME is
+      // information too: a deployment that gives each client, author or
+      // customer a group of their own would otherwise show every member the
+      // whole roster, even though the slices of groups they are not in come
+      // back empty.
+      const listed = await accessControl.visibleGroups(wsId, email, groups);
+
       const teams: TeamAccess[] = [
         slice(EVERYONE_TEAM, await accessControl.canReadAsEveryoneBatch(wsId, probes)),
       ];
-      for (const name of groups) {
+      for (const name of listed) {
         const team = await accessControl.canReadAsGroupBatch(wsId, name, probes);
         if (team === null) continue; // gone between the two reads — nothing to say
         teams.push(slice(name, team));

package/src/modules/settings/__tests__/setup.routes.layout-phase.test.ts

@@ -10,13 +10,13 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
-import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
 import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import { newKbStartupRunner } from '../../../__tests__/workspace-service.js';
 
 /**
  * The completing save and the REAL initialization phase, wired the way the
@@ -105,7 +105,7 @@ function boot() {
   // it: the completing save applies the admin's names to it, and the step
   // reads them from it when the phase runs.
   const kb = testKbContext();
-  const runner = new KbStartupRunner({
+  const runner = newKbStartupRunner({
     gitRunner: new NodeGitRunner(),
     kbRepoUrl: () => upstream,
     workspacesRoot: path.join(root, 'workspaces'),

package/src/modules/settings/__tests__/setup.routes.managed-phase.test.ts

@@ -12,7 +12,6 @@ import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import { ManagedRepository } from '../managed-repository.js';
 import { RepositorySource } from '../repository-source.js';
-import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
 import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
@@ -20,6 +19,7 @@ import { defaultKbTemplateDir } from '../../../assets.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { KbContext } from '../../../shared/kb-context.js';
+import { newKbStartupRunner } from '../../../__tests__/workspace-service.js';
 
 /**
  * A repository the deployment keeps, and the REAL startup phase, wired the
@@ -89,7 +89,7 @@ function boot(kb: KbContext) {
   const gitRunner = new NodeGitRunner(60_000, source.credentials);
   const workspacesRoot = path.join(root, 'workspaces');
   const setAsideRoot = path.join(root, 'backups', 'replaced-working-copies');
-  const runner = new KbStartupRunner({
+  const runner = newKbStartupRunner({
     gitRunner,
     kbRepoUrl: () => source.url(),
     workspacesRoot,

package/src/modules/tool-auth/internal-token.service.ts

@@ -33,7 +33,7 @@ export interface InternalTokenClaim {
    * connection key to pass through). The verifier resolves such tokens to
    * `source: 'external'`: the caller IS an external agent, and must be treated
    * like one everywhere — admitted to external-only surfaces (`start_session`,
-   * `ask`), refused from internal-only ones (`execute_command`, …), and
+   * `ask`), refused from internal-only ones (`switch_branch`, …), and
    * expected to carry `sessionId` on the tool body, not in the token.
    */
   externalProxy?: boolean;

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -66,8 +66,7 @@ const WWW_AUTH = 'Bearer realm="bevel-tools"';
  * Gate that admits ONLY in-process callers (those bearing an internal HMAC
  * token). Mount it AFTER `toolAuth` on every internal-only surface — the
  * internal tool catalog and the routes of tools registered with
- * `registerInternalTool` but NOT `registerExternalTool` (e.g. `execute_command`,
- * `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
+ * `registerInternalTool` but NOT `registerExternalTool` (e.g. `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
  * an external connection key authenticates successfully, so without this gate it
  * could invoke an internal-only route directly by guessing its name. The route
  * MUST stay mounted (our own agent reaches it over the same loopback HTTP), so

package/src/modules/tool-helpers/__tests__/branch-declaration.test.ts

@@ -8,7 +8,6 @@ import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
@@ -24,6 +23,7 @@ import {
   type BranchDeclaration,
   type ToolDefSpec,
 } from '../index.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 const execFileAsync = promisify(execFile);
 const KB_DIR = 'knowledge-base';
@@ -116,7 +116,7 @@ describe('a tool declares how it treats its branch', () => {
     await runGit(seed, ['push', 'origin', 'HEAD:refs/heads/refs/heads/ghost']);
 
     kb = testKbContext({ kbDirName: KB_DIR });
-    const workspaces = new WorkspaceService(workspacesRoot, upstream, kb, new NodeFs());
+    const workspaces = newWorkspaceService(workspacesRoot, upstream, kb, new NodeFs());
     const resolve = createToolContextResolver({
       authService: {
         getUserById: async () => ({ id: 'u', email: 'alice@example.com', name: 'Alice' }),

package/src/modules/tool-helpers/tool-handler.ts

@@ -36,8 +36,8 @@ export interface ToolHandlerOptions {
   writeScope?: boolean;
   /**
    * How this route treats `branch`, when it must differ from what its
-   * `toolDef` recorded. Only `execute_command` sets it (`own`): it falls back
-   * to an internal caller's focused branch rather than being refused.
+   * `toolDef` recorded (`own`: the handler resolves it itself rather than
+   * being refused).
    */
   branch?: BranchHandling;
 }

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

@@ -41,8 +41,8 @@ export interface ToolContext {
   sessionId?: string;
   /**
    * The branch the in-process agent's workspace is focused on, from its internal
-   * token. An internal-only workspace tool (e.g. `execute_command`) falls back to
-   * it when the model omits `branch`, so the in-app chat agent acts on its own
+   * token. A tool may fall back to it when the model omits `branch` (`list_tool_setup`
+   * reads the focused branch's setup), so the in-app chat agent acts on its own
    * workspace even on a branch-less call. Only set for `source: 'internal'`;
    * external callers must name the branch explicitly (a present-but-invalid value
    * still fails closed regardless of this).

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

@@ -15,6 +15,7 @@ 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';
@@ -110,6 +111,11 @@ async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = em
     // 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);
   registerPluginsTools(registry, kb);
@@ -257,7 +263,6 @@ describe('every file tool opens with the guide-first sentence and carries no sha
     'move_file',
     'copy_file',
     'unzip',
-    'execute_command',
     'apply_file_upload',
   ];