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

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -1,10 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
-import type { KbContext } from '../../../../shared/kb-context.js';
 import { renderRolesYaml } from '../../../access-model/index.js';
 import { reservedRootDirs } from './template-files.step.js';
-import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource, renderTemplateText } from './template-source.js';
+import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource, renderTemplateText, type TemplateKb } from './template-source.js';
 import { assertNotGitInternals, hasGitInternalsSegment } from '../../../../shared/git-internals.js';
 import { GitInternalsError } from '../../../../shared/domain-errors.js';
 import { isManagedGuide } from '../../../agent-guide/index.js';
@@ -35,7 +34,7 @@ export function buildSeedTree(
   extraRootDirs: readonly string[],
   seedAdminEmails: readonly string[],
   /** Read per seed, never captured: the setup-completing save may apply the layout after this builder was composed. */
-  kb: Pick<KbContext, 'layout'>,
+  kb: TemplateKb,
 ): (dir: string) => Promise<string[]> {
   // Validated eagerly; resolved per seed.
   reservedRootDirs(extraRootDirs, kb.layout);
@@ -57,7 +56,7 @@ class KbSeedTree {
     private readonly templates: TemplateSource,
     private readonly extraRootDirs: readonly string[],
     private readonly seedAdminEmails: readonly string[],
-    private readonly kb: Pick<KbContext, 'layout'>,
+    private readonly kb: TemplateKb,
   ) {}
 
   /** Fill `dir` with a complete knowledge base; resolve to what was GENERATED. */
@@ -184,7 +183,7 @@ class KbSeedTree {
     if (text === null) {
       await fs.copyFile(from, to);
     } else {
-      await fs.writeFile(to, renderTemplateText(text, this.kb.layout), 'utf8');
+      await fs.writeFile(to, renderTemplateText(text, this.kb.layout, this.kb.defaultBranch), 'utf8');
     }
     await fs.chmod(to, (await fs.stat(from)).mode & 0o777);
   }

package/src/modules/workspace/startup/steps/template-files.step.ts

@@ -6,10 +6,9 @@ import {
   type KbLayout,
 } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
-import type { KbContext } from '../../../../shared/kb-context.js';
 import { PREAMBLE_FILE } from '../../../agent-instructions/index.js';
 import { isManagedGuide } from '../../../agent-guide/index.js';
-import { TemplateSource } from './template-source.js';
+import { TemplateSource, type TemplateKb } from './template-source.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 import { hasGitInternalsSegment } from '../../../../shared/git-internals.js';
 
@@ -71,7 +70,7 @@ export const GENERATED_FILES: readonly string[] = ['roles.yaml'];
  * The three roots CORE gives a knowledge base: the ontologies, the shared
  * skills, and the plugins that hold tools and link the skills.
  *
- * `Data/`, `Agents/` and `Pipelines/` are deliberately absent. They scaffold
+ * `Data/`, `Agents/` and `Workflows/` are deliberately absent. They scaffold
  * the agentic execution layer, which is not part of this platform — a core
  * deployment that created them would be handing every operator three empty
  * folders it has no feature to fill. A distribution that DOES own that layer
@@ -93,7 +92,7 @@ function coreRequiredDirs(layout: Required<KbLayout>): readonly string[] {
  * the repo being maintained.
  *
  * Deliberately NOT a check against the reserved-root set in `kb-layout.ts`:
- * `Data`, `Agents` and `Pipelines` are all in that set, and they are precisely
+ * `Data`, `Agents` and `Workflows` are all in that set, and they are precisely
  * what a distribution passes here. Being reserved is what makes a name worth
  * claiming — the file tree renders it as its own root instead of folding it
  * into Knowledge — so rejecting reserved names would reject the only real use.
@@ -172,7 +171,7 @@ export class TemplateFilesStep implements OnServerStart {
      * applies the admin's names after this step was built. A snapshot taken
      * here scaffolded `Skills/` beside the `skills/` they had just chosen.
      */
-    private readonly kb: Pick<KbContext, 'layout'>,
+    private readonly kb: TemplateKb,
     private readonly extraRootDirs: readonly string[] = [],
   ) {
     // Validated NOW, so a bad extra fails at boot beside the rest of the

package/src/modules/workspace/startup/steps/template-source.ts

@@ -48,6 +48,14 @@ export const TEMPLATE_SOURCE_FALLBACKS: ReadonlyMap<string, string> = new Map([
  */
 export const SHARED_FILE_RULES_PLACEHOLDER = '{{sharedFileRules}}';
 
+/**
+ * What rendering a template reads of the knowledge base: its layout, and the
+ * default branch the shared rules name. The branch is optional so a caller
+ * that hands only `{ layout }` keeps compiling and gets the rules without the
+ * branch sentence, as before the branch was named.
+ */
+export type TemplateKb = Pick<KbContext, 'layout'> & Partial<Pick<KbContext, 'defaultBranch'>>;
+
 /**
  * Every placeholder a template file carries, filled: the layout's names on the
  * text an author wrote, THEN the shared file rules dropped into the hole they
@@ -70,10 +78,10 @@ export const SHARED_FILE_RULES_PLACEHOLDER = '{{sharedFileRules}}';
  * a template writes) that a string replacement would read as capture-group
  * syntax.
  */
-export function renderTemplateText(text: string, layout: KbLayout): string {
+export function renderTemplateText(text: string, layout: KbLayout, defaultBranch = ''): string {
   return renderKbLayoutPlaceholders(text, layout).replaceAll(
     SHARED_FILE_RULES_PLACEHOLDER,
-    () => sharedFileRulesSection(layout),
+    () => sharedFileRulesSection(layout, defaultBranch),
   );
 }
 
@@ -98,8 +106,11 @@ export class TemplateSource {
   constructor(
     private readonly disk: IFsProbe,
     private readonly templateDir: string,
-    /** The layout the placeholders render as — read per file, so a name applied by setup is the one written. */
-    private readonly kb: Pick<KbContext, 'layout'>,
+    /**
+     * The layout the placeholders render as, and the default branch the shared
+     * rules name — read per file, so a name applied by setup is the one written.
+     */
+    private readonly kb: TemplateKb,
   ) {}
 
   /**
@@ -188,9 +199,13 @@ export class TemplateSource {
     // happens to contain a placeholder as one.
     const layout = this.kb.layout;
     if (relPath === IGNORE_FILENAME) {
-      return renderTemplateText(raw, { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) });
+      return renderTemplateText(
+        raw,
+        { ...layout, agentsFile: gitignoreLiteral(layout.agentsFile) },
+        this.kb.defaultBranch,
+      );
     }
-    return renderTemplateText(raw, layout);
+    return renderTemplateText(raw, layout, this.kb.defaultBranch);
   }
 
   /**

package/src/modules/workspace/workspace-tmp.ts

@@ -1,6 +1,6 @@
 import { promises as fs, type Stats } from 'node:fs';
 import path from 'node:path';
-import { PathNotFoundError, WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { PathNotFoundError, VersionControlDomainError, VersionControlValidationError } from '../../shared/domain-errors.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
 import { sanitizedPath } from '../../shared/printable.js';
 import { hasControlCharacter, TMP_REF_PREFIX } from '../kb-fs/index.js';
@@ -55,9 +55,9 @@ export const TMP_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 export const TMP_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
 
 /** A ref that breaks one of the rules, with the rule named. */
-function invalidRef(ref: string, rule: string): WorkflowValidationError {
+function invalidRef(ref: string, rule: string): VersionControlValidationError {
   const shown = sanitizedPath(ref);
-  return new WorkflowValidationError(`"${shown}" is not a valid tmp ref: ${rule}`, { kind: 'tmp-ref-invalid', path: shown });
+  return new VersionControlValidationError(`"${shown}" is not a valid tmp ref: ${rule}`, { kind: 'tmp-ref-invalid', path: shown });
 }
 
 /**
@@ -97,7 +97,7 @@ function tmpRefFailure(ref: string, err: unknown): Error {
     return invalidRef(ref, 'it goes through a link that cannot be followed (a link that leads back to itself).');
   }
   log.warn('could not read a tmp ref:', { err, ref: shown });
-  return new WorkflowDomainError(`"${shown}" could not be read from the workspace's tmp folder.`, 500, {
+  return new VersionControlDomainError(`"${shown}" could not be read from the workspace's tmp folder.`, 500, {
     kind: 'tmp-ref-unreadable',
     path: shown,
   });

package/src/modules/workspace/workspace.routes.ts

@@ -7,7 +7,7 @@ import { isAbsence, type ITreeWalker } from '../../shared/fs.contract.js';
 import { printable } from '../../shared/printable.js';
 import type { IAdminAccessService } from '../admin/index.js';
 import express from 'express';
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import {
   KNOWLEDGE_DIR,
   canonicalRelativePath,
@@ -29,8 +29,8 @@ import type { AuthService } from '../auth/index.js';
 import type { IAccessControl } from '../access/index.js';
 import { canReadWorkspacePath, resolveReadableMap, toKbRelative, isRolesYamlPath, assertRolesYamlParsable } from '../access-model/index.js';
 import type { ICreatorAccess, IChangeReadGate } from '../access-model/index.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
-import { PathTraversalError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import { PathTraversalError, VersionControlDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
 import { normalizeWorkspacePath } from '../kb-fs/index.js';
@@ -52,7 +52,7 @@ import { OCTET_STREAM, rawExtensionOf, rawMimeFor } from './file-readers/raw-mim
  *
  * CANONICAL, because the mutating verbs on this surface coordinate on the
  * path: `PUT` takes an in-process write turn on it, all of them take the
- * workflow lock row keyed by it, and the bytes live at it. A save spelled
+ * version-control lock row keyed by it, and the bytes live at it. A save spelled
  * `x/a.md` and a delete spelled `./x//a.md` would otherwise take two
  * different lock rows for one file and interleave. See
  * `canonicalRelativePath` for what it refuses to touch.
@@ -72,7 +72,7 @@ function requestPath(value: unknown): string | null {
  * Every file-mutating route on this surface — `PUT /file`, `DELETE /file`,
  * `PATCH /file` (move), `POST /directory`, `POST /upload`, `POST /unzip` —
  * routes its write through `withLock(path, op)`: acquire the per-file
- * workflow lock, perform the op, then release. The release commits the
+ * version-control lock, perform the op, then release. The release commits the
  * file as a one-file change attributed to the user and pushes it to origin,
  * exactly like the lock-aware filesystem the agent writes through. There
  * is no separate "share" step; save and share are fused.
@@ -80,8 +80,8 @@ function requestPath(value: unknown): string | null {
 export function createWorkspaceRoutes(
   workspaceService: WorkspaceService,
   authService: AuthService,
-  workflowService: IWorkflowService,
-  eventBus: WorkflowEventBus,
+  versionControlService: IVersionControlService,
+  eventBus: VersionControlEventBus,
   accessControl: IAccessControl,
   kb: KbContext,
   creatorAccess: ICreatorAccess,
@@ -164,7 +164,7 @@ export function createWorkspaceRoutes(
 
   /**
    * Resolve `req.userId` to the full `AuthUser` record. Mirrors the helper
-   * in `workflow.routes.ts` so file-mutation routes can pass the user into
+   * in `version-control.routes.ts` so file-mutation routes can pass the user into
    * `acquireLock`/`releaseLock` (which need name + email for commit
    * attribution). Returns `null` and writes the response if unauthenticated.
    */
@@ -228,7 +228,7 @@ export function createWorkspaceRoutes(
   }
 
   /**
-   * Acquire the workflow lock for `(workspaceId, branch, targetPath)`, run
+   * Acquire the version-control lock for `(workspaceId, branch, targetPath)`, run
    * `op`, then release. Release commits + pushes the file as a one-file
    * change attributed to `user` — same pipeline the lock-aware filesystem
    * uses for the agent. Contention surfaces immediately as a 409-style
@@ -261,7 +261,7 @@ export function createWorkspaceRoutes(
        * platform file back, coming from `source`. Passed straight to
        * `acquireLock`, which VERIFIES both halves — that the move is a restore
        * at all, and that this caller may make it — rather than believing
-       * either. See the `IWorkflowService.acquireLock` contract.
+       * either. See the `IVersionControlService.acquireLock` contract.
        */
       platformRestore?: { source: string };
     },
@@ -277,7 +277,7 @@ export function createWorkspaceRoutes(
     // run the op without touching the lock and let the caller release
     // it on their own schedule (which is what fuses commit + push into
     // one atomic step the user explicitly triggered).
-    const existing = await workflowService.getLock(workspaceId, branch, targetPath);
+    const existing = await versionControlService.getLock(workspaceId, branch, targetPath);
     if (existing && existing.holderUserId === user.id) {
       const result = await op();
       // Disk write landed but no commit yet (caller will release later,
@@ -300,7 +300,7 @@ export function createWorkspaceRoutes(
       eventBus.emit({ kind: 'fs-tree-changed', workspaceId, branch });
       return result;
     }
-    const acquired = await workflowService.acquireLock(workspaceId, branch, targetPath, user, {
+    const acquired = await versionControlService.acquireLock(workspaceId, branch, targetPath, user, {
       platformRestore: options?.platformRestore,
     });
     if (!acquired.acquired) {
@@ -343,9 +343,9 @@ export function createWorkspaceRoutes(
       const untouched = wroteNothing(err);
       try {
         if (untouched) {
-          await workflowService.releaseLockUntouched(workspaceId, branch, targetPath, user);
+          await versionControlService.releaseLockUntouched(workspaceId, branch, targetPath, user);
         } else {
-          await workflowService.releaseLockNoCommit(workspaceId, branch, targetPath, user);
+          await versionControlService.releaseLockNoCommit(workspaceId, branch, targetPath, user);
         }
       } catch (releaseErr) {
         log.warn(
@@ -361,7 +361,7 @@ export function createWorkspaceRoutes(
       // explicit branch makes the intent obvious to readers.
       throw new Error('unreachable: opSucceeded false after try');
     }
-    await workflowService.releaseLock(workspaceId, branch, targetPath, user);
+    await versionControlService.releaseLock(workspaceId, branch, targetPath, user);
     // Signal sidebar / explorer to refresh even when no open tab matched
     // the changed path (e.g. someone else just created a new file).
     // `releaseLock` already fires `file-changed` for the path, but
@@ -427,14 +427,14 @@ export function createWorkspaceRoutes(
   /**
    * Map any thrown error to an HTTP response. Centralises the response
    * shape so each route handler stays focused on its own logic.
-   *   - `WorkflowDomainError` → its `.status` + `.payload` (a traversal is a
+   *   - `VersionControlDomainError` → its `.status` + `.payload` (a traversal is a
    *     403, an invalid path a 400, an unreadable archive a 422 — each by
    *     its TYPE; this surface used to recognise all three by their message)
    *   - Anything else with a `.status` → that status
    *   - Default → 500
    */
   function sendError(res: express.Response, err: unknown): void {
-    if (err instanceof WorkflowDomainError) {
+    if (err instanceof VersionControlDomainError) {
       res.status(err.status).json(domainErrorBody(err));
       return;
     }
@@ -479,7 +479,7 @@ export function createWorkspaceRoutes(
       // A typed domain answer — a branch origin no longer has (410), a name
       // git refuses (400) — is the client's to act on, not a failure of ours;
       // it keeps its status so the browser can say what happened.
-      if (error instanceof WorkflowDomainError) {
+      if (error instanceof VersionControlDomainError) {
         sendError(res, error);
         return;
       }
@@ -564,7 +564,7 @@ export function createWorkspaceRoutes(
    * `hasRole` can throw `AccessConfigError` when `roles.yaml` / `access.md`
    * fails to load (missing role refs, malformed YAML). Without a catch the
    * async rejection bubbles past Express and the request hangs. Route it
-   * through `sendError` so the rich `WorkflowDomainError` payload (status +
+   * through `sendError` so the rich `VersionControlDomainError` payload (status +
    * `accessConfigErrors`) surfaces to the caller — same shape the
    * `/access/has-role` endpoint returns.
    */
@@ -818,14 +818,14 @@ export function createWorkspaceRoutes(
       if (ref === null) {
         buffer = await workspaceService.readFileBinary(id, filePath);
       } else {
-        const at = await workflowService.fileBytesAtChange(id, filePath, ref, side);
+        const at = await versionControlService.fileBytesAtChange(id, filePath, ref, side);
         // Nothing at that path on that side of the save — for `before`, also
         // how a root commit answers, since it has no parent to read.
         if (at === null) {
           res.status(404).json({ error: 'File not found' });
           return;
         }
-        // `IWorkflowService` is isomorphic, so the bytes arrive typed as a
+        // `IVersionControlService` is isomorphic, so the bytes arrive typed as a
         // `Uint8Array`. `res.send` recognises a Buffer and JSON-encodes
         // anything else, so a zero-copy view over the same memory is what it
         // has to be handed — never a copy of a file that may be tens of MB.
@@ -888,7 +888,7 @@ export function createWorkspaceRoutes(
       // "File not found" would tell a reader their file had vanished. Only
       // the ref branch can raise one, so the working-tree read keeps the
       // blanket 404 it has always answered with.
-      if (ref !== null && error instanceof WorkflowDomainError) {
+      if (ref !== null && error instanceof VersionControlDomainError) {
         sendError(res, error);
         return;
       }
@@ -999,7 +999,7 @@ export function createWorkspaceRoutes(
       // to load while the entries were judged (`AccessConfigError`): both are
       // domain errors carrying their own status and payload, the same ones
       // the single-file gate answers with.
-      if (error instanceof WorkflowDomainError) {
+      if (error instanceof VersionControlDomainError) {
         sendError(res, error);
         return;
       }
@@ -1047,7 +1047,7 @@ export function createWorkspaceRoutes(
       // Traversal stays a 403 and a malformed workspace id its domain status:
       // both carry messages written to be read by the caller. (A traversal IS
       // a domain error now, so the one check covers both.)
-      if (error instanceof WorkflowDomainError) {
+      if (error instanceof VersionControlDomainError) {
         sendError(res, error);
         return;
       }
@@ -1331,7 +1331,7 @@ export function createWorkspaceRoutes(
     // ONE spelling of the target from here down. `x/a.md`, `./x/a.md` and
     // `x//a.md` are the same file and all pass the path validator, and this
     // route coordinates on that path three times over: the in-process write
-    // turn, the workflow lock row, and the bytes themselves. Two clients
+    // turn, the version-control lock row, and the bytes themselves. Two clients
     // spelling one file differently would otherwise take two different locks
     // and both pass their own precondition.
     const requested = requestPath(req.query.path);
@@ -1378,7 +1378,7 @@ export function createWorkspaceRoutes(
       // in this process may touch the path until the write is done. The write
       // inside takes the same turn re-entrantly.
       //
-      // Across instances the workflow lock below is still the coordinator;
+      // Across instances the version-control lock below is still the coordinator;
       // this only orders what this server is doing.
       await workspaceService.withPathTurn(id, filePath, async () => {
         // A stale `ifMatch` is refused before anything commits.

package/src/modules/workspace/workspace.service.ts

@@ -23,7 +23,7 @@ import {
 } from '../../shared/rename-no-replace.js';
 import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import { NodeGitRunner } from '../workflow/index.js';
+import { NodeGitRunner } from '../version-control/index.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { isZipNoiseEntry, readZipEntry, zipEntryName, zipEntryNameRefusal, zipEntrySegments } from './zip-entry-rules.js';
@@ -32,13 +32,13 @@ import {
   PathNotFoundError,
   PathTraversalError,
   UnreadableArchiveError,
-  WorkflowValidationError,
+  VersionControlValidationError,
 } from '../../shared/domain-errors.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import {
   BranchNotFoundError,
   RemoteBranchGoneError,
-  WorkflowDomainError,
+  VersionControlDomainError,
   isMissingRemoteBranchFailure,
 } from '../../shared/domain-errors.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
@@ -141,10 +141,10 @@ export class FolderTooLargeError extends Error {
  * Lives here rather than in `shared/domain-errors.ts` because the sentence is
  * built by `entryExistsMessage` and that file deliberately imports no VALUE
  * from `@bevel-software/platform-shared`, only a type. It still extends
- * `WorkflowDomainError`, so the routes' `sendError` maps it to 409 with
+ * `VersionControlDomainError`, so the routes' `sendError` maps it to 409 with
  * `{ kind: 'entry-exists', … }` without knowing this class exists.
  */
-export class EntryExistsError extends WorkflowDomainError {
+export class EntryExistsError extends VersionControlDomainError {
   readonly kind = 'entry-exists' as const;
   constructor(readonly entryKind: ExistingEntryKind, readonly destination: string) {
     super(entryExistsMessage(entryKind, destination), 409, {
@@ -202,7 +202,7 @@ async function readForConditionalWrite(absolutePath: string, relativePath: strin
  */
 function assertValidPath(relativePath: string): void {
   const reason = validateRelativePath(relativePath);
-  if (reason) throw new WorkflowValidationError(`Invalid path: ${reason}`);
+  if (reason) throw new VersionControlValidationError(`Invalid path: ${reason}`);
 }
 
 /** Throw the conditional write's 409 unless the file still holds `expectedContent`. */
@@ -1919,7 +1919,7 @@ export class WorkspaceService implements IWorkspaceService {
    * holding both turns would introduce the one shape that can deadlock here
    * (a move waiting on a target whose holder is waiting on the move's other
    * path). A rename onto a path being conditionally written is therefore
-   * outside that guarantee; the workflow lock on the moved path is what
+   * outside that guarantee; the version-control lock on the moved path is what
    * serializes it against the app's own editors.
    */
   async moveEntry(workspaceId: string, oldWsPath: string, newWsPath: string): Promise<void> {
@@ -2023,7 +2023,7 @@ export class WorkspaceService implements IWorkspaceService {
    * two requests from that holder would interleave.
    *
    * The reach of the guarantee, exactly: within this process, one mutation at
-   * a time per resolved path. ACROSS instances the workflow lock row is the
+   * a time per resolved path. ACROSS instances the version-control lock row is the
    * coordinator, and it agrees with this queue only because `PUT /file`
    * canonicalises the path before taking either (see `canonicalRelativePath`);
    * a caller that reaches the service directly with an odd spelling gets the
@@ -2055,7 +2055,7 @@ export class WorkspaceService implements IWorkspaceService {
    * Not re-entrant: take it once, and never around another folder's turn.
    *
    * The reach of the guarantee, like {@link withPathTurn}'s: within this
-   * process, over this process's clones. Across instances the workflow lock
+   * process, over this process's clones. Across instances the version-control lock
    * rows coordinate — the placeholder write takes its own path's lock, as the
    * folder delete takes each file's — and each clone's changes meet in git,
    * as any write into a folder another instance deletes already does.
@@ -2276,7 +2276,7 @@ export class WorkspaceService implements IWorkspaceService {
     assertNoGitInternalsSegment(zipRelativePath);
     await assertNotGitInternals(workspaceDir, zipRelativePath, zipAbsolute);
     if (!zipRelativePath.toLowerCase().endsWith('.zip')) {
-      throw new WorkflowValidationError('Only .zip files can be extracted');
+      throw new VersionControlValidationError('Only .zip files can be extracted');
     }
 
     // Inferred from the NORMALISED archive path, so an archive named without
@@ -2726,7 +2726,7 @@ export class WorkspaceService implements IWorkspaceService {
       // the type and surfacing as a 500. A malformed id (bad percent-escape)
       // decodes to itself, and `%` never passes the branch-name rules, so it
       // lands here as a BranchNameError like any other invalid name.
-      if (err instanceof WorkflowDomainError) throw err;
+      if (err instanceof VersionControlDomainError) throw err;
       const reason = err instanceof Error ? err.message : String(err);
       throw new Error(`Invalid workspace ID "${workspaceId}": ${reason}`);
     }

package/src/modules/workspace/workspace.tools.ts

@@ -15,9 +15,9 @@ import type { IRoutineWritePolicy } from './routine-write-policy.js';
 import type { ToolHandlerFactory } from '../tool-helpers/index.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import { GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { GitInternalsError, VersionControlValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
-// relies on) — not a workflow service, so this stays inside the module boundary.
+// relies on) — not a version-control service, so this stays inside the module boundary.
 import {
   assertInsideRepo,
   assertRepoRootNameFree,
@@ -669,7 +669,7 @@ function refuseEntry(entry: Record<string, unknown>, err: unknown): void {
     entry.message = err.message;
     return;
   }
-  if (err instanceof GitInternalsError || err instanceof WorkflowValidationError) {
+  if (err instanceof GitInternalsError || err instanceof VersionControlValidationError) {
     entry.error = (err.payload as { kind?: string } | undefined)?.kind ?? 'refused';
     entry.message = err.message;
     return;
@@ -1146,7 +1146,8 @@ export function registerWorkspaceTools(
   /**
    * The one tree walk (see `shared/fs.contract.ts`), for the `firstRun`
    * note's look at the knowledge folder. Optional for the harnesses about the
-   * file primitives; without it `start_session` answers the id alone.
+   * file primitives; without it `start_session` answers
+   * `{ sessionId, defaultBranch }` and never `firstRun`.
    */
   disk?: ITreeWalker,
   /**
@@ -1533,7 +1534,7 @@ export function registerWorkspaceTools(
 
   /**
    * The paths among `paths` the caller may NOT write, judged exactly as the
-   * lock gate judges them (`WorkflowService.acquireLock`): on a protected
+   * lock gate judges them (`VersionControlService.acquireLock`): on a protected
    * branch only, against the access tree at HEAD, with no rules at HEAD
    * meaning allow. Empty on a draft branch — changes there reach a protected
    * branch only through a change request.
@@ -2019,18 +2020,21 @@ export function registerWorkspaceTools(
   const startSessionDef = toolDef({
     name: 'start_session',
     description:
-      'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. Pass the returned id as `sessionId` to every tool whose arguments list it, inside `call_tool_chain` too; the others refuse it. Where the deployment offers an `ask` tool, hand it the SAME id: your reads and your questions are then one conversation. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId }`, plus `firstRun` while the knowledge base is still empty: a note to act on.',
+      'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. Pass the returned id as `sessionId` to every tool whose arguments list it, inside `call_tool_chain` too; the others refuse it. Where the deployment offers an `ask` tool, hand it the SAME id: your reads and your questions are then one conversation. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId, defaultBranch }`, plus `firstRun` while the knowledge base is empty: a note to act on.',
     path: '/api/agent/tools/start_session',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
       type: 'object',
       properties: {
         sessionId: str('The minted session id — pass it as `sessionId` to the tools that take one, and to `ask` where there is one.'),
+        defaultBranch: str(
+          "The deployment's default branch: the branch people read, and the one to pass as `branch` unless you are working on a draft.",
+        ),
         firstRun: str(
           `Present only while the knowledge base holds nothing but its starter guide (and a starter pack's untouched pages): what to offer the person (the guide's \`${FIRST_RUN_SECTION_ID}\` section says how).`,
         ),
       },
-      required: ['sessionId'],
+      required: ['sessionId', 'defaultBranch'],
     },
     tags: ['workspace'],
   });
@@ -2049,8 +2053,11 @@ export function registerWorkspaceTools(
     requireExternalSource,
     toolHandler(async (_args, ctx) => {
       const { sessionId } = await sessionSink.createSession(ctx.user.id, new Date());
+      // Read here, not at registration: the setup save applies a branch model
+      // to the running graph, and the name in effect is the one to give.
+      const defaultBranch = kb.defaultBranch;
       const firstRun = await firstRunFor(ctx);
-      return firstRun ? { sessionId, firstRun } : { sessionId };
+      return firstRun ? { sessionId, defaultBranch, firstRun } : { sessionId, defaultBranch };
     }),
   );
 
@@ -3084,7 +3091,7 @@ export function registerWorkspaceTools(
       for (const f of files) writePolicy.assertPathWritable(ctx.sessionId, f.path);
       const fs = await ctx.getFilesystem(a.branch as string);
       // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands the
-      // batch as one commit. Structural cast avoids a workflow-internal import.
+      // batch as one commit. Structural cast avoids a version-control-internal import.
       const batching = fs as unknown as {
         writeFiles(
           writes: { path: string; content: string }[],
@@ -3431,7 +3438,7 @@ export function registerWorkspaceTools(
         // ordering trick to keep the rest governed on the way — nothing lands
         // until all of it does. The placeholders go too: this is the one
         // operation that removes a folder. Structural cast, as `write_files`
-        // does, to avoid importing the workflow-internal class here.
+        // does, to avoid importing the version-control-internal class here.
         if (files.length > 0) {
           const batch = fs as unknown as {
             writeFiles(

package/src/shared/__tests__/canonical-file-identity.test.ts

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { describe, it, expect } from 'vitest';
 import { assertValidRelativePath } from '@bevel-software/platform-shared';
 import { canonicalFileIdentity } from '../canonical-file-identity.js';
-import { PathTraversalError, WorkflowValidationError } from '../domain-errors.js';
+import { PathTraversalError, VersionControlValidationError } from '../domain-errors.js';
 
 /**
  * Two properties, and the second is the one worth the file.
@@ -75,9 +75,9 @@ describe('canonicalFileIdentity', () => {
   });
 
   it('refuses a path that climbs out rather than resolving it away', () => {
-    expect(() => canonicalFileIdentity('../etc/passwd')).toThrow(WorkflowValidationError);
+    expect(() => canonicalFileIdentity('../etc/passwd')).toThrow(VersionControlValidationError);
     expect(() => canonicalFileIdentity('knowledge-base/../../etc/passwd')).toThrow(
-      WorkflowValidationError,
+      VersionControlValidationError,
     );
   });
 
@@ -86,7 +86,7 @@ describe('canonicalFileIdentity', () => {
     // containment check alone would wave it through under a second identity
     // for `knowledge-base/y.md`.
     expect(() => canonicalFileIdentity('knowledge-base/x/../y.md')).toThrow(
-      WorkflowValidationError,
+      VersionControlValidationError,
     );
   });
 
@@ -115,7 +115,7 @@ describe('canonicalFileIdentity', () => {
     // 400 for that same body.
     for (const notAPath of [123, true, {}, [], ['a.md'], null, undefined]) {
       expect(() => canonicalFileIdentity(notAPath as unknown as string)).toThrow(
-        WorkflowValidationError,
+        VersionControlValidationError,
       );
       expect(() => canonicalFileIdentity(notAPath as unknown as string)).toThrow(
         'Invalid path: Path is required',

package/src/shared/__tests__/fire-and-forget.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { capturingLogger } from '../../__tests__/capturing-logger.js';
+import { callFireAndForget } from '../fire-and-forget.js';
+
+const settled = () => new Promise<void>((resolve) => setImmediate(resolve));
+const FAILED = 'a listener failed:';
+
+describe('callFireAndForget — nothing a listener does reaches the caller', () => {
+  it('a listener that throws is logged as failed, and the call returns', () => {
+    const { logger, lines } = capturingLogger();
+    expect(() =>
+      callFireAndForget(
+        () => {
+          throw new Error('reactor exploded');
+        },
+        'event',
+        logger,
+        FAILED,
+      ),
+    ).not.toThrow();
+    expect(lines).toEqual([{ level: 'error', message: FAILED, fields: { err: expect.objectContaining({ message: 'reactor exploded' }) } }]);
+  });
+
+  it('a listener whose promise rejects is logged as failed — a rejection the try/catch alone would miss', async () => {
+    const { logger, lines } = capturingLogger();
+    callFireAndForget(async () => Promise.reject(new Error('reactor exploded later')), 'event', logger, FAILED);
+    expect(lines).toEqual([]);
+    await settled();
+    expect(lines).toEqual([{ level: 'error', message: FAILED, fields: { err: expect.objectContaining({ message: 'reactor exploded later' }) } }]);
+  });
+
+  it('a listener that returns, or whose promise resolves, logs nothing', async () => {
+    const { logger, lines } = capturingLogger();
+    callFireAndForget(() => undefined, 'event', logger, FAILED);
+    callFireAndForget(async () => undefined, 'event', logger, FAILED);
+    await settled();
+    expect(lines).toEqual([]);
+  });
+});