@bevel-software/platform-core-backend 0.12.0 → 0.13.1

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

@@ -9,7 +9,12 @@ import { BevelIgnoreStack } from './bevel-ignore.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
-import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../kb-fs/clone-config.js';
+import {
+  cloneCredentialArgs,
+  cloneCredentialConfigArgs,
+  cloneTrackingConfigArgs,
+  SAFE_IMPLICIT_FETCH_ARGS,
+} from '../kb-fs/clone-config.js';
 import type { IDiffService } from '../diff/diff.interface.js';
 
 /**
@@ -155,9 +160,13 @@ export class WorkspaceService implements IWorkspaceService {
     this.onWorkspaceCloned = listener;
   }
 
-  /** Build git clone args that inject credentials via -c headers so the token never appears in the repo URL. */
+  /**
+   * Build git clone args. Credentials go in as `clone --config`, which both
+   * authenticates this clone and leaves the helper in the new repo's config for
+   * every later push — and keeps the token itself out of the repo URL, out of
+   * argv, and out of `.git/config` (the helper reads it from the environment).
+   */
   private gitCloneArgs(targetDir: string, branch: string, referenceRepo?: string): string[] {
-    const token = process.env.GITHUB_TOKEN;
     // core.longpaths=true: KB has paths >260 chars; without this the clone silently drops those files on Windows.
     const args = ['clone', '-c', 'core.longpaths=true', '-b', branch];
     // Borrow the object database of an existing sibling clone. Every commit
@@ -171,14 +180,10 @@ export class WorkspaceService implements IWorkspaceService {
     if (referenceRepo) {
       args.push('--reference', referenceRepo, '--dissociate');
     }
-    if (token) {
-      // The helper script reads from GITHUB_TOKEN at runtime — the token value never appears in args.
-      // Username is provider-specific (GitHub `x-access-token`, GitLab `oauth2`, …); the token is
-      // always the Basic-auth password, which every major host accepts.
-      args.push(
-        '-c', `credential.helper=!f() { echo "username=${this.gitUsername()}"; echo "password=$GITHUB_TOKEN"; }; f`,
-      );
-    }
+    // Persisted into the new repo's config (`clone --config`), not just applied
+    // to this invocation — every later push from this clone depends on finding
+    // the helper there. See `cloneCredentialArgs`.
+    args.push(...cloneCredentialArgs(this.gitUsername()));
     args.push(this.kbRepoUrl(), targetDir);
     return args;
   }
@@ -288,6 +293,11 @@ export class WorkspaceService implements IWorkspaceService {
     // back a half-cloned workspace.
     if (this.branchDirs.has(branch)) {
       await this.awaitBootstrapOrEvict(branch);
+      // A token or username set/changed through the setup screen after this
+      // branch was first opened has to reach the already-cached clone, or its
+      // pushes keep failing — the fast path is exactly where that rotation is
+      // otherwise missed.
+      await this.refreshCredentialHelperIfStale(branch, repoDir);
       return this.buildWorkspaceInfo(branch, workspaceDir);
     }
 
@@ -301,6 +311,7 @@ export class WorkspaceService implements IWorkspaceService {
     // single-flight wait the cached fast path already uses.
     await this.awaitBootstrapOrEvict(branch);
     if (this.branchDirs.has(branch)) {
+      await this.refreshCredentialHelperIfStale(branch, repoDir);
       return this.buildWorkspaceInfo(branch, workspaceDir);
     }
 
@@ -313,7 +324,7 @@ export class WorkspaceService implements IWorkspaceService {
       // (duplicate fetch refspec / merge ref) is repaired before anything
       // pulls it. Once per branch per process — the cached paths above return
       // before reaching here.
-      await this.normalizeCloneTracking(repoDir, branch);
+      await this.normalizeCloneConfig(repoDir, branch);
       this.branchDirs.set(branch, workspaceDir);
       return this.buildWorkspaceInfo(branch, workspaceDir);
     } catch {
@@ -396,17 +407,26 @@ export class WorkspaceService implements IWorkspaceService {
   }
 
   /**
-   * Collapse the clone's tracking config to a single fetch refspec and a single
-   * upstream ref for `branch` (see `kb-fs/clone-config.ts`). A clone that
-   * accumulated a second `remote.origin.fetch` refspec or `branch.<b>.merge`
-   * value makes git refuse to refresh it — "Cannot rebase onto multiple
-   * branches" — which is how a post-merge pull of the target branch fails.
+   * Bring an adopted clone's config back to what a fresh clone would carry.
+   *
+   * Tracking: collapse it to a single fetch refspec and a single upstream ref
+   * for `branch` (see `kb-fs/clone-config.ts`). A clone that accumulated a
+   * second `remote.origin.fetch` refspec or `branch.<b>.merge` value makes git
+   * refuse to refresh it — "Cannot rebase onto multiple branches" — which is
+   * how a post-merge pull of the target branch fails.
+   *
+   * Credentials: re-stamp the helper. This is the repair for clones that never
+   * got one — anything created by a build whose clone authenticated only its
+   * own invocation, or by a deployment that had no token configured until
+   * after the clone existed. Without it those clones are permanently
+   * unpushable: nothing re-clones a directory that is already on disk, so no
+   * restart, re-pull or settings change would ever fix them.
    *
    * Never throws: it only ever touches `.git/config`, so a failure leaves the
    * workspace exactly as usable as it was, and the git layer self-heals the
-   * same keys before it pulls.
+   * tracking keys before it pulls.
    */
-  private async normalizeCloneTracking(repoDir: string, branch: string): Promise<void> {
+  private async normalizeCloneConfig(repoDir: string, branch: string): Promise<void> {
     try {
       for (const args of cloneTrackingConfigArgs(branch)) {
         await execFileAsync('git', ['-C', repoDir, ...args]);
@@ -415,12 +435,99 @@ export class WorkspaceService implements IWorkspaceService {
       // One line per branch, not per key: every key writes to the same
       // `.git/config`, so what fails for one fails for all.
       console.warn(
-        `[workspace] could not normalize the tracking config of the "${branch}" clone:`,
+        `[workspace] could not normalize the config of the "${branch}" clone:`,
+        redactError(err),
+      );
+    }
+    await this.stampCredentialHelper(repoDir, branch);
+  }
+
+  /**
+   * Fingerprint of the credential state a clone's helper is derived from: the
+   * username (baked into the helper literal) and whether a token exists at all
+   * (the helper is present-or-absent on that). The token VALUE is deliberately
+   * excluded — the helper reads `$GITHUB_TOKEN` at call time, so rotating the
+   * token needs no re-stamp; only a username change or a token appearing /
+   * disappearing does.
+   */
+  private credentialFingerprint(): string {
+    return `${this.gitUsername()}::${process.env.GITHUB_TOKEN ? '1' : '0'}`;
+  }
+
+  /** Last credential fingerprint stamped into each branch's clone, this process. */
+  private readonly stampedCredentialFingerprint = new Map<string, string>();
+
+  /**
+   * Bring `repoDir`'s credential helper into line with the current deployment
+   * config (stamp when a token is set, unset when none is), and record the
+   * fingerprint so the cached fast path can skip a no-op re-stamp. Runs the
+   * config args tolerantly and one at a time: `--unset-all` on a clone that
+   * never had a helper exits non-zero, and that must neither abort the rest
+   * nor read as a failure.
+   */
+  private async stampCredentialHelper(repoDir: string, branch: string): Promise<void> {
+    let argLists: string[][];
+    try {
+      argLists = cloneCredentialConfigArgs(this.gitUsername());
+    } catch (err) {
+      // `credentialHelperValue` fails closed on a username outside its safe
+      // charset. Normally unreachable (CoreConfig and the settings service
+      // validate first), but if a fourth, unvalidated path ever appears the
+      // throw must not escape here: in the disk-adoption block it would land
+      // in a catch that reads every error as "not on disk" and kick off a
+      // re-clone that fails on the same validation — masking the real cause.
+      // Contain it as a loud non-stamp instead; `normalizeCloneConfig`'s
+      // never-throws contract stays true.
+      console.warn(
+        `[workspace] refusing to stamp the credential helper of the "${branch}" clone:`,
         redactError(err),
       );
+      this.stampedCredentialFingerprint.delete(branch);
+      return;
+    }
+    let stamped = true;
+    for (const args of argLists) {
+      try {
+        await execFileAsync('git', ['-C', repoDir, ...args]);
+      } catch (err) {
+        // `--unset-all` with no matching value (exit 5) is the expected no-op
+        // for a clone that never carried an app helper; anything else is a
+        // real failure.
+        const code = (err as { code?: number } | null)?.code;
+        if (!(args.includes('--unset-all') && code === 5)) {
+          stamped = false;
+          console.warn(
+            `[workspace] could not stamp the credential helper of the "${branch}" clone:`,
+            redactError(err),
+          );
+        }
+      }
+    }
+    if (stamped) {
+      this.stampedCredentialFingerprint.set(branch, this.credentialFingerprint());
+    } else {
+      // Recording the fingerprint after a FAILED write would make every later
+      // cached open skip the retry as "already up to date" — the clone would
+      // keep pushing with stale or missing credentials until a restart.
+      // Dropping the entry keeps the fast path retrying until a stamp lands.
+      this.stampedCredentialFingerprint.delete(branch);
     }
   }
 
+  /**
+   * Re-stamp a cached clone's credential helper when the deployment's
+   * credential config changed since we last stamped it — the rotation case the
+   * disk-adoption path in `getOrCreateForBranch` never reaches, because the
+   * fast path returns before it. Without this, a token added (or a username
+   * changed) through the setup screen after a branch was first opened would
+   * never reach that branch's clone until a process restart, and its pushes
+   * would keep failing exactly as in the original incident.
+   */
+  private async refreshCredentialHelperIfStale(branch: string, repoDir: string): Promise<void> {
+    if (this.stampedCredentialFingerprint.get(branch) === this.credentialFingerprint()) return;
+    await this.stampCredentialHelper(repoDir, branch);
+  }
+
   private async cloneProcessMapForBranch(workspaceDir: string, branch: string): Promise<void> {
     const targetDir = path.join(workspaceDir, this.kbDirName);
 
@@ -465,10 +572,10 @@ export class WorkspaceService implements IWorkspaceService {
       }
       if (alreadyCloned) {
         // We don't auto-pull because that could clobber another user's
-        // in-progress lock-held edits. The tracking config IS re-stamped —
-        // it never touches the working tree, and a drifted config is what
-        // breaks the next pull.
-        await this.normalizeCloneTracking(targetDir, branch);
+        // in-progress lock-held edits. The CONFIG is re-stamped though — it
+        // never touches the working tree, and a clone with drifted tracking
+        // or a missing credential helper is one that can't pull or push.
+        await this.normalizeCloneConfig(targetDir, branch);
         return;
       }
       // Half-built dir — wipe and re-clone.
@@ -492,7 +599,7 @@ export class WorkspaceService implements IWorkspaceService {
       // this branch. `git clone -b` already produces that shape; stamping it
       // explicitly means the shape is asserted rather than assumed, and the
       // same call is what repairs an existing clone that drifted.
-      await this.normalizeCloneTracking(targetDir, branch);
+      await this.normalizeCloneConfig(targetDir, branch);
       console.log(
         `[workspace] Cloned ${this.kbDirName} for branch "${branch}"` +
           (reference ? ' (referenced a sibling clone)' : ''),

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

@@ -20,6 +20,7 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.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';
+import { assertInsideRepo } from '../kb-fs/repo-path.js';
 import type { ISessionSink } from './session-sink.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
@@ -111,6 +112,22 @@ const int = (description: string): JsonSchema => ({ type: 'integer', description
 
 const str = (description: string): JsonSchema => ({ type: 'string', description });
 
+/**
+ * A path input that names the clone folder. The tools are rooted at the
+ * WORKSPACE dir, one level above the git clone, so a path only reaches git
+ * when it starts with that folder; an agent that reads `KnowledgeBase/Foo.md`
+ * in a URL or a doc and passes it verbatim would otherwise write beside the
+ * repository. Saying so in the input itself, not only in prose, is what the
+ * agent actually sees when it fills the argument. `refused` is false for the
+ * inputs that may legitimately name a stray (a source to rescue, a file to
+ * remove).
+ */
+const wsPath = (kbDirName: string, what: string, refused = true): JsonSchema =>
+  str(
+    `${what}: starts with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`).` +
+      (refused ? ' A path without that prefix is outside the repository and is refused.' : ''),
+  );
+
 function asText(content: string | Buffer): string {
   return typeof content === 'string' ? content : content.toString('utf8');
 }
@@ -394,7 +411,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path, or a `__tool_chain_spill__/…` ref from a truncated `call_tool_chain`.'),
+        path: str(`Path to read, starting with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), or a \`__tool_chain_spill__/…\` ref from a truncated \`call_tool_chain\`.`),
         offset: int('Start character index (default 0).'),
         limit: int('Max characters to return from `offset`.'),
         sessionId: SESSION_ID_INPUT,
@@ -453,13 +470,13 @@ export function registerWorkspaceTools(
   mount({
     name: 'list_files',
     description:
-      'List a directory. Returns `{ path, entries: [{ name, type, size? }] }`. Omit `path` for the workspace root.' +
+      `List a directory. Returns \`{ path, entries: [{ name, type, size? }] }\`. Omit \`path\` for the workspace root, which holds the repository as the \`${kbDirName}/\` folder: every content path starts with it (e.g. \`${kbDirName}/KnowledgeBase\`).` +
       ONTOLOGY_BOUNDARY_NOTE,
     inputs: {
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative directory (default: root).'),
+        path: str(`Directory to list, starting with \`${kbDirName}/\` (default: the workspace root, where the repository is the \`${kbDirName}/\` folder).`),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch'],
@@ -501,7 +518,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -610,7 +627,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path'),
         content: str('Full file content.'),
         sessionId: SESSION_ID_INPUT,
       },
@@ -657,7 +674,7 @@ export function registerWorkspaceTools(
           description: 'Files to write; each created or overwritten.',
           items: {
             type: 'object',
-            properties: { path: str('Workspace-relative path.'), content: str('Full file content.') },
+            properties: { path: wsPath(kbDirName, 'Path'), content: str('Full file content.') },
             required: ['path', 'content'],
             additionalProperties: false,
           },
@@ -705,7 +722,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path'),
         old_string: str('Exact text to replace (include enough context to be unique).'),
         new_string: str('Replacement text.'),
         replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring a unique match.' },
@@ -750,7 +767,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative path.'),
+        path: wsPath(kbDirName, 'Path to the file', false),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -781,7 +798,7 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative directory.'),
+        path: wsPath(kbDirName, 'Directory to create'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -808,8 +825,8 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        src: str('Source path.'),
-        dest: str('Destination path.'),
+        src: wsPath(kbDirName, 'Source path', false),
+        dest: wsPath(kbDirName, 'Destination path'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'src', 'dest'],
@@ -842,8 +859,8 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        src: str('Source path.'),
-        dest: str('Destination path.'),
+        src: wsPath(kbDirName, 'Source path', false),
+        dest: wsPath(kbDirName, 'Destination path'),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'src', 'dest'],
@@ -877,8 +894,8 @@ export function registerWorkspaceTools(
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
-        path: str('Workspace-relative .zip path.'),
-        destination: str("Directory to extract into (default: the zip's parent)."),
+        path: wsPath(kbDirName, 'Path to the .zip archive', false),
+        destination: wsPath(kbDirName, "Directory to extract into (default: the zip's parent)"),
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'path'],
@@ -916,6 +933,9 @@ export function registerWorkspaceTools(
         // extension policy applies per entry too, so a restricted run can't unzip a
         // `.md` into the graph.
         (wsRelPath) => {
+          // An entry that would land beside the repository is skipped with the
+          // corrected-path reason, like any other refused entry.
+          assertInsideRepo(wsRelPath, kbDirName);
           writePolicy.assertPathWritable(ctx.sessionId, wsRelPath);
           return assertOntologyWriteAllowed(sessionOntologyGate, ctx, wsRelPath);
         },