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

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -18,6 +18,7 @@ import {
   type GitFailure,
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
+import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in
@@ -51,6 +52,16 @@ export interface KbStartupRunnerOptions {
   gitRunner: IGitRunner;
   kbRepoUrl: () => string;
   workspacesRoot: string;
+  /**
+   * Where a working copy of a repository that is no longer the configured
+   * one is moved to, under a folder named for the moment it happened — see
+   * `reconcileClonesWithConfiguredRepository`. NOT under `workspacesRoot`:
+   * the workspace service's orphan sweep removes every folder there that is
+   * not a known branch's, and what is set aside has to outlive that sweep.
+   * The composition root names a folder under the backups root, which is a
+   * persistent volume of its own. Default: a sibling of `workspacesRoot`.
+   */
+  setAsideRoot?: string;
   kbDirName: string;
   templateDir: string;
   defaultBranch: () => string;
@@ -301,6 +312,10 @@ export class KbStartupRunner {
         );
       }
       const heads = await this.ensureRemote();
+      // AFTER the remote answered: the configured address is known to be a
+      // repository we can reach, so a clone of a different one is stale, not
+      // a casualty of a typo in the address.
+      await this.reconcileClonesWithConfiguredRepository();
       const ctx = this.buildContext(heads, handles);
 
       for (const step of this.opts.steps) {
@@ -501,6 +516,150 @@ export class KbStartupRunner {
     };
   }
 
+  /**
+   * Bring every working copy on disk into line with the configured
+   * repository, WITHOUT DELETING ANYTHING.
+   *
+   * A clone fetches and pushes through the address stored in its own
+   * `remote.origin.url`, which nothing updates when the configured address
+   * changes. After an operator replaced the repository (2026-09-28: the old
+   * one deleted, a new one saved on the setup screen) every surviving clone
+   * kept asking the old address: Save and Retry failed, and the restart
+   * stopped the boot on `repository … not found`, taking the setup screen
+   * with it.
+   *
+   * A clone whose address differs from the configured one is one of two
+   * things, and the histories say which:
+   *
+   *  - THE SAME REPOSITORY AT A NEW ADDRESS — moved, renamed, mirrored. The
+   *    one change the setup screen tells an admin to make ("only change this
+   *    if the same repository was moved or renamed"). Its history is on the
+   *    configured remote, so the clone is pointed at the new address and
+   *    kept, unpushed commits included: they are pushed where they belonged
+   *    all along.
+   *  - ANOTHER REPOSITORY. Re-pointing it would push one repository's
+   *    commits into the other, so it cannot stay where the workspace service
+   *    would adopt it. It is MOVED to {@link KbStartupRunnerOptions.setAsideRoot}
+   *    and the log says where. Never removed: when the old repository is gone
+   *    — as it was that day — these clones are the last copy of the
+   *    knowledge base that exists, and the unpushed work in them exists
+   *    nowhere else at all.
+   *
+   * Every clone under the workspaces root, not only the branches this phase
+   * touches: the workspace service adopts whatever it finds there. A clone
+   * whose address cannot be read is left where it is — "could not tell" is
+   * no reason to move someone's work. One that cannot be set aside stops the
+   * boot with the reason: leaving it would fail the boot a step later with
+   * git's words about a repository nobody configured.
+   */
+  private async reconcileClonesWithConfiguredRepository(): Promise<void> {
+    const configured = this.opts.kbRepoUrl();
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
+    } catch {
+      return; // no workspaces yet
+    }
+    // One folder per run, so what was set aside together stays together.
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const setAsideRoot =
+      this.opts.setAsideRoot ?? path.resolve(this.opts.workspacesRoot, '..', 'replaced-working-copies');
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const repoDir = path.join(this.opts.workspacesRoot, entry.name, this.opts.kbDirName);
+      const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
+      if (!hasGit) continue;
+      let origin: string;
+      try {
+        origin = (await git(this.opts.gitRunner, repoDir, ['config', '--get', 'remote.origin.url'])).trim();
+      } catch {
+        continue;
+      }
+      if (origin === '' || sameRepository(origin, configured)) continue;
+      // The normalized form carries no userinfo, and the scrub covers the rest.
+      const was = this.redact(normalizeRepositoryAddress(origin));
+      if (await this.sharesHistoryWithConfigured(repoDir, configured)) {
+        await git(this.opts.gitRunner, repoDir, ['remote', 'set-url', 'origin', configured]);
+        startupLog.warn(
+          `working copy "${entry.name}" was cloned from ${was}, whose history the configured repository holds: ` +
+            'the same repository at a new address. Pointed at the configured address and kept, unpushed work included.',
+        );
+        continue;
+      }
+      const kept = path.join(setAsideRoot, stamp, entry.name);
+      await this.setAside(repoDir, kept);
+      startupLog.warn(
+        `working copy "${entry.name}" is a clone of another repository (${was}). Set aside at ${kept}; nothing was ` +
+          'deleted, and it will be cloned fresh from the configured one. Work that was never pushed is in that ' +
+          'folder: `git log` there shows it, and `git push <address> <branch>` from there sends it to a repository.',
+      );
+    }
+  }
+
+  /**
+   * Whether the configured repository holds history this clone has too —
+   * asked of git, not guessed from the two addresses. The configured
+   * remote's branches are fetched under a namespace of their own and the
+   * clone's HEAD is tested for a common ancestor with any of them.
+   *
+   * "Could not tell" answers false: a fetch that fails, a clone with no
+   * commit to compare. False sets the clone aside, which loses nothing, where
+   * a wrong true would push a stranger's commits into the configured
+   * repository.
+   */
+  private async sharesHistoryWithConfigured(repoDir: string, configured: string): Promise<boolean> {
+    const probe = 'refs/hexis-probe';
+    let theirs: string[] = [];
+    try {
+      await git(this.opts.gitRunner, repoDir, ['fetch', '--no-tags', '--quiet', configured, `+refs/heads/*:${probe}/*`]);
+      theirs = (await git(this.opts.gitRunner, repoDir, ['for-each-ref', '--format=%(refname)', `${probe}/`]))
+        .split('\n')
+        .map((ref) => ref.trim())
+        .filter(Boolean);
+      if (theirs.length === 0) return false;
+      // One question for all of them: a common ancestor of HEAD and ANY of
+      // their branches is a common ancestor of HEAD and their merge. Capped,
+      // so a remote with thousands of branches cannot outgrow a command line.
+      await git(this.opts.gitRunner, repoDir, ['merge-base', 'HEAD', ...theirs.slice(0, 200)]);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      // The probe leaves nothing behind in a clone that stays in use.
+      for (const ref of theirs) {
+        await git(this.opts.gitRunner, repoDir, ['update-ref', '-d', ref]).catch(() => undefined);
+      }
+    }
+  }
+
+  /**
+   * Move a working copy out of the workspaces root, whole. A rename where
+   * the two folders share a volume; a copy and then a removal where they do
+   * not (the backups root is a volume of its own in the shipped compose
+   * files), with the original removed only once the copy is complete.
+   */
+  private async setAside(repoDir: string, dest: string): Promise<void> {
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    try {
+      await fs.rename(repoDir, dest);
+      return;
+    } catch {
+      // Another volume, or a handle held open on it: copy instead.
+    }
+    try {
+      await fs.cp(repoDir, dest, { recursive: true, errorOnExist: true, force: false, verbatimSymlinks: true });
+    } catch (err) {
+      await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+      throw new Error(
+        `Could not set aside the working copy at ${repoDir}, a clone of a repository that is no longer the ` +
+          `configured one, into ${dest}: ${err instanceof Error ? err.message : String(err)}. Nothing was deleted. ` +
+          'Make room there, or move that folder away by hand, and start again.',
+        { cause: err },
+      );
+    }
+    await fs.rm(repoDir, { recursive: true, force: true });
+  }
+
   /**
    * The branch's working copy at the runtime layout
    * (`<workspacesRoot>/<id>/<kbDirName>`), so the workspace service finds it

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

@@ -649,15 +649,31 @@ export class WorkspaceService implements IWorkspaceService {
     }
     this.inFlightBootstraps.set(branch, bootstrap);
 
+    // `mkdir --recursive` answers with the first path it CREATED, or undefined
+    // when the directory was already there. That is the only honest signal for
+    // what the rollback below may remove: a directory this attempt made is ours
+    // to take back, one that predates us belongs to whatever put it there.
+    let createdWorkspaceDir: string | undefined;
     try {
       // A clone with `-b <branch>` against a never-seeded remote fails
       // naturally; seeding the remote is the KB startup phase's job, at boot.
-      await fs.mkdir(workspaceDir, { recursive: true });
+      createdWorkspaceDir = await fs.mkdir(workspaceDir, { recursive: true });
       await this.cloneProcessMapForBranch(workspaceDir, branch);
       this.registerBranchDir(branch, workspaceDir);
       resolveBootstrap();
     } catch (err) {
       this.branchDirs.delete(branch);
+      // A bootstrap that failed leaves NOTHING behind. The clone rolls its own
+      // target back, but the workspace directory around it would survive as an
+      // empty shell named after the branch — and a directory named after a
+      // branch is read as the platform having known that branch: by
+      // `hasHeardOfBranch`, which would turn the next attempt's honest 404 into
+      // "no longer exists on the remote" (410), and by anyone reading the
+      // workspaces root. Best-effort: a rollback that cannot delete must not
+      // replace the real failure (the clone's) with its own.
+      if (createdWorkspaceDir !== undefined) {
+        await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => {});
+      }
       rejectBootstrap(err);
       throw err;
     } finally {

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

@@ -18,6 +18,7 @@ import type { IRoutineWritePolicy } from './routine-write-policy.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { assertBranchProvided } 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.
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
@@ -1171,6 +1172,15 @@ export function registerWorkspaceTools(
     proposable?: boolean;
     /** False for a tool that is not a file tool (the shell), which the content rule does not describe. */
     fileTool?: boolean;
+    /**
+     * This tool resolves `branch` ITSELF and must not be pre-checked here.
+     * Only `execute_command` sets it: for an internal session that leaves the
+     * argument off, it falls back to the caller's own focused branch (from its
+     * signed token) rather than refusing. It still answers the same
+     * `branch-required` kind when there is nothing to fall back on — see its
+     * handler. Every other tool takes the check below.
+     */
+    resolvesBranchItself?: boolean;
     handler: ToolHandler;
   }): void => {
     const path = `/api/agent/tools/${spec.name}`;
@@ -1178,6 +1188,12 @@ export function registerWorkspaceTools(
     // tool the one content rule, and every tool a permission can refuse the
     // proposal route — appended once here so no tool (especially the
     // read-only ones a session hits first) can miss them.
+    // Whether a call to this tool MUST name a branch, read off the tool's own
+    // declaration rather than assumed of the family. Every tool mounted here
+    // requires `branch` today; keying on the schema means a tool that declares
+    // it optional (and resolves absence itself, as `list_tool_setup` does on its
+    // own route) is not handed a refusal it never asked for.
+    const requiresBranch = ((spec.inputs as { required?: string[] }).required ?? []).includes('branch');
     const describe = (): string =>
       (typeof spec.description === 'function' ? spec.description() : spec.description) +
       (spec.proposable ? PROPOSAL_ROUTE_NOTE : '') +
@@ -1223,6 +1239,16 @@ export function registerWorkspaceTools(
       // never reached the repository — the whole bug, spelled with a prefix.
       toolHandler(
         async (args, ctx) => {
+          // FIRST, before the path work and before any handler: every tool
+          // mounted here declares `branch` as a required, non-empty string, and
+          // nothing enforced that, so a call that named none was carried down
+          // until `workspaceIdForBranch` made a workspace directory out of the
+          // missing value. Most of these tools would meet the same refusal one
+          // layer down at `getFilesystem`, but not all of them do — `unzip`
+          // hands `branch` straight to the workspace service by id — so the
+          // check belongs on the mount every one of them shares rather than on
+          // the resolver only some of them reach.
+          if (requiresBranch && !spec.resolvesBranchItself) assertBranchProvided(args.branch);
           // BEFORE the normaliser: see `assertToolPathsNotGitInternals`.
           if (spec.fileTool !== false) await assertToolPathsNotGitInternals(args, ctx);
           const normalized = normalizePathArgs(
@@ -2594,6 +2620,9 @@ export function registerWorkspaceTools(
       ONTOLOGY_BOUNDARY_NOTE,
     internalOnly: true,
     fileTool: false,
+    // The one tool the mount's branch check skips: the handler below resolves an
+    // omitted `branch` to the internal caller's focused branch before refusing.
+    resolvesBranchItself: true,
     inputs: {
       type: 'object',
       properties: {
@@ -2650,6 +2679,11 @@ export function registerWorkspaceTools(
         throw new ToolError(
           'execute_command requires a `branch`: pass the branch (draft) whose workspace to run the command in — the one you are currently working on.',
           400,
+          // The same discriminator every other KB tool answers a branch-less
+          // call with, so a client switches on one kind across the surface.
+          // The MESSAGE stays this tool's own: it can name the focused-branch
+          // fallback that only applies here.
+          { kind: 'branch-required' },
         );
       }
       // A stringified absent value. Both are syntactically valid git branch names,
@@ -2662,6 +2696,7 @@ export function registerWorkspaceTools(
           `execute_command got the literal string "${branch}" as \`branch\` — that is a stringified absent value, not a branch. ` +
             'Pass the real branch (draft) whose workspace to run the command in.',
           400,
+          { kind: 'branch-required' },
         );
       }
       // Then the SHAPE, via the one canonical validator every other branch path

package/src/shared/domain-errors.ts

@@ -167,6 +167,64 @@ export class PullRebaseConflictError extends WorkflowDomainError {
   }
 }
 
+/**
+ * The one sentence a branch-less call is answered with. Names the input and
+ * what to pass, and carries NO stringified value of what was actually
+ * received: the whole point of this refusal is that the caller sent nothing,
+ * and echoing `undefined` back at them is how the branch "undefined" got
+ * invented in the first place.
+ */
+export const BRANCH_REQUIRED_MESSAGE =
+  '`branch` is required: pass the branch (draft) you are working on.';
+
+/**
+ * The caller named no branch — the input is missing, empty, not a string, or
+ * one of the stringified absent values (`"undefined"` / `"null"`) that a
+ * client produces by interpolating a variable it never set.
+ *
+ * Refused, never defaulted. A knowledge-base tool's workspace is NEVER implied
+ * by the credential (identity-only) — it always comes from this argument — so
+ * falling back to the deployment's default branch would make an omitted
+ * argument silently act on the protected branch. And it is refused HERE, at
+ * the boundary, because everything downstream treats the value as a real
+ * branch name: `workspaceIdForBranch` would turn it into a workspace directory
+ * literally named `undefined`, and the clone of that "branch" would fail with
+ * a story about a branch that never existed.
+ *
+ * 400 with kind `branch-required`, so a client tells it apart from the 404
+ * (no such branch) and the 410 (the branch was deleted) without reading prose.
+ */
+export class BranchRequiredError extends WorkflowDomainError {
+  readonly kind = 'branch-required' as const;
+  constructor() {
+    super(BRANCH_REQUIRED_MESSAGE, 400, { kind: 'branch-required' });
+    this.name = 'BranchRequiredError';
+  }
+}
+
+/**
+ * The stringified absent values. Both are syntactically valid git branch
+ * names, so the shape validator (`assertValidBranchName`) accepts them
+ * happily — accepting one is exactly the bug this guard exists for. They are
+ * refused BY NAME, which is why this check cannot be folded into the shape
+ * check however tempting that looks.
+ */
+const STRINGIFIED_ABSENT_VALUES = new Set(['undefined', 'null']);
+
+/**
+ * Refuse a call that names no branch, before anything downstream can turn the
+ * missing value into a directory name, a clone attempt or a log line.
+ *
+ * Deliberately NOT a shape check: a well-formed name this platform has never
+ * seen is a 404 the caller can act on, and a malformed one is a
+ * `BranchNameError` from the canonical validator. This answers only "you sent
+ * nothing", which is the one case where naming the branch back is impossible.
+ */
+export function assertBranchProvided(branch: unknown): asserts branch is string {
+  if (typeof branch !== 'string' || branch.length === 0) throw new BranchRequiredError();
+  if (STRINGIFIED_ABSENT_VALUES.has(branch)) throw new BranchRequiredError();
+}
+
 /**
  * The platform has never heard of this branch: nothing it has cloned, and
  * nothing any listing of origin's branches has mentioned. Distinct from

package/src/shared/git.contract.ts

@@ -62,6 +62,16 @@ export interface GitCredentials {
   username(): string;
   /** The token in effect, or null when the deployment has none configured. */
   token(): string | null;
+  /**
+   * Make sure {@link token} answers with a credential that is still good,
+   * for one that is not fixed: a token a host issues for an hour has to be
+   * renewed by asking the host, which `token` cannot do, being read where
+   * nothing can wait. The runner awaits this before every call it makes. A
+   * failure here is not the call's failure: git runs with the token in
+   * hand, and the host says what it thinks of it. Absent for a credential
+   * that does not expire.
+   */
+  prepare?(): Promise<void>;
 }
 
 /** The username git is given when a deployment names none. */