@bevel-software/platform-core-backend 0.14.0 → 0.15.1

package/src/modules/workflow/workflow.service.ts

@@ -25,6 +25,7 @@ import type {
   AcquireLockResult,
   AuthUser,
   Branch,
+  BranchSyncOutcome,
   BranchWorkspaceStatus,
   CancelChangeRequestResult,
   Change,
@@ -40,6 +41,7 @@ import type {
   MergeChangeRequestOutcome,
   OpenChangeRequestInput,
   PostChangeRequestCommentInput,
+  RemoteSyncPullResult,
 } from '@bevel-software/platform-shared';
 import { isProtectedBranch, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { and, eq, or } from 'drizzle-orm';
@@ -65,6 +67,7 @@ import {
   RolesYamlPreservationError,
   PullRebaseConflictError,
   PushNeedsAgentResolutionError,
+  RemoteBranchGoneError,
   WorkflowDomainError,
   WorkflowValidationError,
 } from '../../shared/domain-errors.js';
@@ -100,6 +103,33 @@ function isOpenPairViolation(err: unknown): boolean {
   return typeof message === 'string' && message.includes(OPEN_PAIR_CONSTRAINT);
 }
 
+/**
+ * The one sentence a remote-sync conflict is reported with — in the sync
+ * response, on the branch's banner and in the log — so whoever sees any of
+ * the three reads the same thing: which branch, which files, that automatic
+ * recovery is under way, and what to do if it does not clear.
+ */
+export function syncConflictMessage(branch: string, conflictedPaths: string[]): string {
+  // Bounded: the same sentence goes to the response, the banner and the log,
+  // and it must be one sentence in all three whatever the conflict's size.
+  // The full path list rides beside it as `conflictedPaths`.
+  const shown = conflictedPaths.slice(0, SYNC_CONFLICT_FILES_NAMED);
+  const more = conflictedPaths.length - shown.length;
+  const files =
+    conflictedPaths.length === 0
+      ? 'some files'
+      : more > 0
+        ? `${shown.join(', ')} and ${more} more file${more === 1 ? '' : 's'}`
+        : shown.join(', ');
+  return (
+    `${branch} is not in sync yet: ${files} changed both in Hexis and on the git host. ` +
+    `Recovery is queued; if this stays, open the files on ${branch} in Hexis, keep what you want, and save.`
+  );
+}
+
+/** How many conflicted files the sync-conflict sentence names before "and N more". */
+const SYNC_CONFLICT_FILES_NAMED = 3;
+
 /** Redact the shared GitHub token from any error string before surfacing it. */
 function redactTokens(msg: string): string {
   const tokens = [process.env.GITHUB_TOKEN, process.env.GH_TOKEN].filter(
@@ -246,7 +276,10 @@ export class WorkflowService implements IWorkflowService {
    */
   private orphanSweepStarted = false;
 
-  async listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<Branch[]> {
+  async listBranches(
+    workspaceId: string,
+    opts?: { freshFetch?: boolean; strictFetch?: boolean },
+  ): Promise<Branch[]> {
     const branches = await this.git.listBranches(workspaceId, opts);
     if (!this.orphanSweepStarted) {
       this.orphanSweepStarted = true;
@@ -268,7 +301,14 @@ export class WorkflowService implements IWorkflowService {
   }
 
   createBranch(workspaceId: string, name: string, fromBase?: string): Promise<Branch> {
-    return this.git.createBranch(workspaceId, name, fromBase);
+    // Under the branch's lifecycle lock, like `deleteBranch` and the
+    // retirement of a clone the host deleted: creating a branch is the one
+    // operation that can bring a "gone" branch back, and the retirement's
+    // "still gone on origin?" check is only a guarantee if nothing can
+    // recreate the branch between that check and the delete.
+    return this.branchLifecycle.run(`branch:${name}`, () =>
+      this.git.createBranch(workspaceId, name, fromBase),
+    );
   }
 
   /**
@@ -445,9 +485,41 @@ export class WorkflowService implements IWorkflowService {
     return this.git.fetch(workspaceId);
   }
 
+  /**
+   * `git pull` on a workspace, plus the one announcement a pull owes the rest
+   * of the process.
+   *
+   * A pull rewrites a working tree without going through the write routes or
+   * the commit pipeline, so it emits neither of the signals those produce —
+   * and the catalogs that scan the DEFAULT branch's tree (skills, tool
+   * manuals, the plugin index) are keyed to exactly that tree. Every path that
+   * pulls the default workspace therefore has to say so, or those catalogs
+   * keep serving the pre-pull scan for the rest of their TTL: a merge landing
+   * an approved skill, the recovery ladder after a non-fast-forward push, and
+   * a user's update-from-remote alike. Routing every pull through here makes
+   * that ONE mechanism — "the default branch's tree changed" — instead of a
+   * separate special case per event. (The remote sync, `syncWorkspaceFromRemote`,
+   * pulls directly: it owes the same announcement to every branch and per
+   * file, and makes it from the same `treeChanged` verdict.)
+   *
+   * Announced only after the pull RESOLVES, and only when it CHANGED the
+   * tree's content: a pull that threw left the tree as it was, and so did an
+   * "already up to date" pull or one that landed only content-identical
+   * commits — dropping every catalog and making every attached browser
+   * refetch its file tree for a change that did not happen buys a re-scan
+   * and nothing else. The pull itself reports the change, since it is the
+   * only code that can observe it under the workspace mutex.
+   */
+  private async pullWorkspace(workspaceId: string): Promise<void> {
+    const { treeChanged } = await this.git.pull(workspaceId);
+    if (treeChanged && branchForWorkspaceId(workspaceId) === DEFAULT_BRANCH) {
+      this.events?.emit({ kind: 'fs-tree-changed', workspaceId, branch: DEFAULT_BRANCH });
+    }
+  }
+
   async updateFromRemote(workspaceId: string, user?: AuthUser): Promise<void> {
     try {
-      await this.git.pull(workspaceId);
+      await this.pullWorkspace(workspaceId);
     } catch (err) {
       if (err instanceof PullRebaseConflictError) {
         await this.queuePullConflictRecovery(workspaceId, err, user);
@@ -456,6 +528,157 @@ export class WorkflowService implements IWorkflowService {
     }
   }
 
+  async retireRemoteGoneClone(workspaceId: string): Promise<boolean> {
+    const branch = branchForWorkspaceId(workspaceId);
+    const id = workspaceIdForBranch(branch);
+    // The lock `createBranch` and `deleteBranch` take: no Hexis operation can
+    // bring this branch back into being while the clone is examined and
+    // removed. The sync's own hold on the clone ended when its outcome was
+    // returned, so the branch is asked about AGAIN here rather than trusted
+    // from then — a recreate that landed in between keeps its clone. A clone
+    // being bootstrapped right now is left alone too: it can only be cloning
+    // a branch that exists, so the retirement is already moot. What remains
+    // is a recreate pushed from OUTSIDE Hexis in the milliseconds between the
+    // origin check and the delete, with a bootstrap starting in that same
+    // window; the next sync of that branch clones it fresh.
+    return this.branchLifecycle.run(`branch:${branch}`, async () => {
+      if (!(await this.workspaceService.hasBootstrappedWorkspace(id))) return false;
+      if (this.workspaceService.isBootstrapInFlight(branch)) return false;
+      if (await this.git.remoteBranchExists(branch, branch)) return false;
+      await this.workspaceService.deleteWorkspace(id);
+      // Whatever a sync still owed that clone is owed to nothing now.
+      this.owedAnnouncements.delete(id);
+      return true;
+    });
+  }
+
+  /**
+   * Cap on per-path `file-changed` events one sync announces for a branch.
+   * Past it the tree event alone carries the news — a bulk import that
+   * rewrote hundreds of files would otherwise fan hundreds of events out to
+   * every open browser to say what one refresh says.
+   */
+  private static readonly SYNC_FILE_EVENT_CAP = 200;
+
+  /**
+   * Announcements a sync still OWES, per workspace: a pull landed but the
+   * events for it could not be sent. The pull is not redone on retry — HEAD
+   * has not moved since — so the announcement cannot be re-derived from sha
+   * movement; it is remembered here and delivered by the next sync of that
+   * workspace, merged with whatever that sync finds.
+   */
+  private readonly owedAnnouncements = new Map<string, { after: string; changedPaths: string[] }>();
+
+  async syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome> {
+    const branch = branchForWorkspaceId(workspaceId);
+    const id = workspaceIdForBranch(branch);
+    // Two spellings of one workspace id are in circulation — the encoded
+    // directory name (`ali%2Fx`, what the clone listing yields) and the
+    // Express-decoded form (`ali/x`, what every HTTP route hands the git
+    // layer) — and the git layer's mutex keys on the raw string. Speaking the
+    // routes' spelling to git is what puts a webhook's rebase in the same
+    // queue as the author's concurrent save on a slashed branch; the event
+    // bus gets the encoded form, which every SSE consumer canonicalises.
+    const gitId = branch;
+    // Every failure below is an OUTCOME, never a throw: the caller runs this
+    // over many clones, and one broken clone must not abort the others.
+    let pulled: RemoteSyncPullResult;
+    try {
+      pulled = await this.git.syncFromRemote(gitId);
+    } catch (err) {
+      if (err instanceof RemoteBranchGoneError) {
+        // Not a failure: the host deleted the branch, so there is nothing to
+        // sync and the caller retires the stale clone. No banner — nobody is
+        // editing a branch that no longer exists. An announcement still owed
+        // for that clone dies with it: a branch recreated under the same name
+        // is a different tree, and replaying the old paths against it would
+        // announce changes that never happened there.
+        this.owedAnnouncements.delete(id);
+        console.log(`[sync] branch "${branch}" no longer exists on the host`);
+        return { branch, outcome: 'remote-gone' };
+      }
+      if (err instanceof PullRebaseConflictError) {
+        // Same path as `updateFromRemote`: the rebase was aborted inside
+        // the pull (the clone is exactly what it was) and the divergence goes
+        // to the retry → recovery-agent → escalate ladder, attributed to the
+        // recovery bot since no person triggered this. It is still reported
+        // as a conflict because it is not resolved at request time — the
+        // caller's retry, or the ladder, settles it; the banner clears on the
+        // next clean pull or push.
+        await this.queuePullConflictRecovery(gitId, err);
+        const message = syncConflictMessage(branch, err.conflictedPaths);
+        console.warn(`[sync] ${message}`);
+        this.noteGitSyncFailed(gitId, branch, err, { paths: err.conflictedPaths, message });
+        return { branch, outcome: 'conflict', conflictedPaths: err.conflictedPaths, error: message };
+      }
+      const message = sanitizeError(err);
+      console.warn(`[sync] pull failed for branch "${branch}": ${message}`);
+      this.noteGitSyncFailed(gitId, branch, err);
+      return { branch, outcome: 'error', error: message };
+    }
+    // A clean pull is proof origin is reachable and this clone rebases onto
+    // it — the condition a `git-sync-failed` banner on this branch was
+    // waiting for, whether a sync or a push raised it.
+    this.noteGitSyncOk(gitId, branch);
+    const { before, after, treeChanged, changedPaths } = pulled;
+    // What this branch reports about ITS clone is decided by the pull alone:
+    // `updated` when HEAD moved, `up-to-date` otherwise.
+    const outcome: BranchSyncOutcome =
+      after === null || after === before
+        ? { branch, outcome: 'up-to-date', to: after ?? '' }
+        : { branch, outcome: 'updated', from: before, to: after };
+    // What it ANNOUNCES is what has changed since the last announcement that
+    // was actually delivered: this pull's content change, if any, plus one an
+    // earlier sync landed but could not send. The announcement keys on the
+    // pull's verdict about CONTENT — commits that left the tree identical are
+    // nothing for a browser to refetch or a catalog to drop.
+    const owed = this.owedAnnouncements.get(id);
+    if (!treeChanged && !owed) return outcome;
+    const announce = {
+      after: after ?? owed?.after ?? '',
+      changedPaths: [...new Set([...(owed?.changedPaths ?? []), ...changedPaths])],
+    };
+    try {
+      // Announce the new tree. The tree event alone already refreshes every
+      // open file explorer and, on the default branch, drops the skill / tool /
+      // plugin catalogues (`catalog-cache-invalidation.ts`); the CR list
+      // caches the touched paths it resolved against the old tree, so drop
+      // that too.
+      this.prs.invalidateListCache();
+      this.events?.emit({ kind: 'fs-tree-changed', workspaceId: id, branch });
+      // Per-file events so an open tab on a file the host rewrote refetches
+      // instead of showing stale bytes until its next tree refresh. The paths
+      // were observed under the same hold as the pull, so they are exactly
+      // this sync's — never a save that landed alongside. Capped: a bulk
+      // import would otherwise fan hundreds of events out to say what one
+      // refresh says.
+      if (announce.changedPaths.length <= WorkflowService.SYNC_FILE_EVENT_CAP) {
+        for (const p of announce.changedPaths) {
+          this.events?.emit({
+            kind: 'file-changed',
+            workspaceId: id,
+            branch,
+            path: `${this.kbDirName}/${p}`,
+            newSha: announce.after,
+            byUserId: 'system',
+            byUserName: 'Git sync',
+          });
+        }
+      }
+    } catch (err) {
+      // The pull landed, so origin is fine and no banner is raised — but the
+      // caller must hear that this branch's announcement did not happen, and
+      // the announcement stays owed: the retry the error invites will not
+      // move HEAD again, so it must find the debt here rather than in the shas.
+      this.owedAnnouncements.set(id, announce);
+      const message = sanitizeError(err);
+      console.warn(`[sync] pulled "${branch}" but could not announce it: ${message}`);
+      return { branch, outcome: 'error', error: message };
+    }
+    this.owedAnnouncements.delete(id);
+    return outcome;
+  }
+
   /**
    * A pull hit a rebase conflict — the workspace carries local commits that
    * conflict with origin, a state that never resolves on its own (every
@@ -782,7 +1005,7 @@ export class WorkflowService implements IWorkflowService {
         let recoveryError: unknown = null;
         if (looksLikeNonFastForward) {
           try {
-            await this.git.pull(workspaceId);
+            await this.pullWorkspace(workspaceId);
             await this.git.push(workspaceId, user);
             recovered = true;
             this.noteGitSyncOk(workspaceId, branch);
@@ -1033,7 +1256,34 @@ export class WorkflowService implements IWorkflowService {
    * machinery is unaffected — all this adds is that someone finds out, rather
    * than the deployment looking healthy while nothing reaches the remote.
    */
-  private noteGitSyncFailed(workspaceId: string, branch: string, err: unknown): void {
+  private noteGitSyncFailed(
+    workspaceId: string,
+    branch: string,
+    err: unknown,
+    /**
+     * The files a person must reconcile, and the sentence we composed about
+     * them. That sentence is ours (branch name + repo paths, no git stderr),
+     * so it goes out verbatim — the same string the sync response and the
+     * log carry — rather than through the sanitiser, whose 200-character
+     * clip would make the banner disagree with them. Callers that already
+     * hold the sentence pass it; otherwise it is derived below.
+     */
+    explicitConflict?: { paths: string[]; message: string },
+  ): void {
+    // A rebase conflict is a conflict whichever path ran into it. The remote
+    // sync names its files on purpose; the push-recovery paths (autosave, the
+    // lock release, the queued retries) raise the same banner with the raw
+    // error — and the banner keeps the LATEST failure per branch, so a retry
+    // landing after the sync would replace the conflict variant, with the
+    // files as links, by the generic "check the server logs" one. Seen on
+    // staging: the sync's 409 named the file, the worker's retry a moment
+    // later took the links away. Derive the paths from the error itself so
+    // every path agrees.
+    const conflict =
+      explicitConflict ??
+      (err instanceof PullRebaseConflictError
+        ? { paths: err.conflictedPaths, message: syncConflictMessage(branch, err.conflictedPaths) }
+        : undefined);
     // Same canonicalization as `noteGitSyncOk` — the pair must agree on keys.
     const id = branchForWorkspaceId(workspaceId);
     this.gitSyncFailing.add(id);
@@ -1043,7 +1293,8 @@ export class WorkflowService implements IWorkflowService {
       branch,
       // Git stderr can quote a credentialed URL; the banner is user-facing and
       // the string also lands in client logs, so sanitize before it leaves.
-      reason: sanitizeError(err),
+      reason: conflict ? conflict.message : sanitizeError(err),
+      ...(conflict ? { conflictedPaths: conflict.paths } : {}),
     });
   }
 
@@ -1102,7 +1353,7 @@ export class WorkflowService implements IWorkflowService {
       let recoveryError: unknown = null;
       if (looksLikeNonFastForward) {
         try {
-          await this.git.pull(workspaceId);
+          await this.pullWorkspace(workspaceId);
           await this.git.push(workspaceId, user, opts);
           recovered = true;
           this.noteGitSyncOk(workspaceId, branch);
@@ -1710,7 +1961,7 @@ export class WorkflowService implements IWorkflowService {
     // refs, but the restore commits from the working tree — a stale tree
     // would push non-fast-forward and fail loudly anyway; this just makes
     // that rare.
-    await this.git.pull(ws.id).catch(() => undefined);
+    await this.pullWorkspace(ws.id).catch(() => undefined);
 
     // The verb acts on the request as it is NOW — never a cached file list.
     const paths = await this.git.changedPathsForPr(ws.id, baseBranch, headBranch);
@@ -2221,7 +2472,7 @@ export class WorkflowService implements IWorkflowService {
     try {
       const targetWorkspace = await this.workspaceService.getOrCreateForBranch(baseBranch);
       targetWorkspaceId = targetWorkspace.id;
-      await this.git.pull(targetWorkspace.id);
+      await this.pullWorkspace(targetWorkspace.id);
     } catch (err) {
       // Still best-effort for the merge response (the merge already landed
       // on origin) — but a rebase CONFLICT here means the target workspace

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

@@ -182,11 +182,10 @@ describe('read-permission gates on human read routes', () => {
 
   it('keeps the structural root folders visible even when nothing is readable', async () => {
     // A user with no read grants: the access batch denies everything. The
-    // structural top-level folders (KnowledgeBase, Data, Agents, Pipelines,
-    // Plugins) must still resolve readable (so the explorer renders its
-    // section view), while their contents stay gated. The retired Skills/
-    // and Tools/ roots get NO structural treatment — they are ordinary
-    // (denied) folders now.
+    // structural top-level folders (KnowledgeBase, Skills, Data, Agents,
+    // Pipelines, Plugins) must still resolve readable (so the explorer renders
+    // its section view), while their contents stay gated. The retired Tools/
+    // root gets NO structural treatment — it is an ordinary (denied) folder.
     h = await makeHarness({ allowFn: () => false });
     expect((await get('/files')).status).toBe(200);
     const filter = h.listFilesFilter();
@@ -208,8 +207,8 @@ describe('read-permission gates on human read routes', () => {
     expect(verdict.get(`${KB}/Agents`)).toBe(true);
     expect(verdict.get(`${KB}/Pipelines`)).toBe(true);
     expect(verdict.get(`${KB}/Plugins`)).toBe(true);
-    // Retired roots: no override, the deny-all batch verdict stands.
-    expect(verdict.get(`${KB}/Skills`)).toBe(false);
+    expect(verdict.get(`${KB}/Skills`)).toBe(true);
+    // Retired root: no override, the deny-all batch verdict stands.
     expect(verdict.get(`${KB}/Tools`)).toBe(false);
     // Their contents: still gated (the override matches only the exact folder).
     expect(verdict.get(`${KB}/KnowledgeBase/Open/a.md`)).toBe(false);

package/src/modules/workspace/__tests__/workspace.service.list-cloned.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * `listClonedWorkspaces` is what the remote sync enumerates. It must read the
+ * DISK, not the in-memory bootstrap cache: clones survive a restart, and a
+ * hook that fires before anyone has opened a branch must still find them.
+ */
+describe('WorkspaceService.listClonedWorkspaces', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-list-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function clone(dirName: string, withGit = true) {
+    const repo = path.join(root, dirName, 'knowledge-base');
+    await fs.mkdir(withGit ? path.join(repo, '.git') : repo, { recursive: true });
+  }
+
+  it('finds every finished clone on disk without any branch having been opened this process', async () => {
+    await clone('main');
+    await clone('ali%2Fnew-skill');
+    // Half-built: the directory exists but the clone never finished.
+    await clone('juan%2Fabandoned', false);
+    // Not one of ours: the name is not the encoding of any branch.
+    await clone('weird%zz');
+    // A stray file at the root is ignored.
+    await fs.writeFile(path.join(root, 'notes.txt'), 'x');
+
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base');
+    const found = await svc.listClonedWorkspaces();
+    expect(found.sort((a, b) => a.branch.localeCompare(b.branch))).toEqual([
+      { id: 'ali%2Fnew-skill', branch: 'ali/new-skill' },
+      { id: 'main', branch: 'main' },
+    ]);
+  });
+
+  it('is empty when the workspaces root does not exist yet', async () => {
+    const svc = new WorkspaceService(path.join(root, 'missing'), 'https://example.test/kb.git', 'knowledge-base');
+    expect(await svc.listClonedWorkspaces()).toEqual([]);
+  });
+});
+
+describe('WorkspaceService.listClonedWorkspaces — what is not a clone', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-list-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('a directory whose name round-trips but is not a branch git accepts', async () => {
+    // `foo!`, `-leading-dash` and `a..b` survive encodeURIComponent unchanged, so
+    // only the validator can exclude them; `has space` does not round-trip and
+    // is excluded one step earlier. Both guards have to hold.
+    for (const name of ['main', 'foo!', '-leading-dash', 'a..b', 'has space']) {
+      await fs.mkdir(path.join(root, name, 'knowledge-base', '.git'), { recursive: true });
+    }
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base');
+    expect(await svc.listClonedWorkspaces()).toEqual([{ id: 'main', branch: 'main' }]);
+  });
+
+  it('a branch whose bootstrap is in flight right now', async () => {
+    await fs.mkdir(path.join(root, 'main', 'knowledge-base', '.git'), { recursive: true });
+    await fs.mkdir(path.join(root, 'ali%2Fx', 'knowledge-base', '.git'), { recursive: true });
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base');
+    // While a clone runs, `.git` exists but the tree is not checked out yet.
+    // The listing asks the public predicate, which is stubbed here rather than
+    // the tracker behind it — no public seam can hold a real clone open.
+    vi.spyOn(svc, 'isBootstrapInFlight').mockImplementation((branch) => branch === 'ali/x');
+    expect(await svc.listClonedWorkspaces()).toEqual([{ id: 'main', branch: 'main' }]);
+  });
+
+  it('a root that is a file counts as no root, not as a clone list', async () => {
+    // A FILE where the root should be: readdir fails with ENOTDIR on POSIX and
+    // ENOENT on Windows — both "no root", so an empty list. A permission
+    // failure is the case that must propagate, and there is no portable way
+    // to stage one in a temp dir; the code path is the same `throw err`.
+    const file = path.join(root, 'not-a-dir');
+    await fs.writeFile(file, 'x');
+    const svc = new WorkspaceService(file, 'https://example.test/kb.git', 'knowledge-base');
+    expect(await svc.listClonedWorkspaces()).toEqual([]);
+  });
+});

package/src/modules/workspace/__tests__/workspace.service.missing-branch.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { isMissingRemoteBranchFailure } from '../../../shared/domain-errors.js';
+
+/**
+ * The one line that decides whether a failed bootstrap is "this branch does
+ * not exist" (410, the browser says so) or "something is wrong" (500). Git's
+ * two wordings for a missing ref are matched; an unreachable host or a
+ * refused credential must NOT be, or a deployment outage would read as
+ * "your branch is gone".
+ */
+describe('isMissingRemoteBranchFailure', () => {
+  it('recognises both of git’s wordings for a ref origin does not have', () => {
+    expect(
+      isMissingRemoteBranchFailure(
+        "Command failed: git clone -b sync-test/conflict-2 https://[REDACTED]@github.com/x/y.git /w\nfatal: Remote branch sync-test/conflict-2 not found in upstream origin",
+      ),
+    ).toBe(true);
+    expect(isMissingRemoteBranchFailure("fatal: couldn't find remote ref refs/heads/ali/x")).toBe(true);
+  });
+
+  it('does not mistake an unreachable host or a refused credential for a missing branch', () => {
+    expect(
+      isMissingRemoteBranchFailure("fatal: unable to access 'https://github.com/x/y.git/': Could not resolve host: github.com"),
+    ).toBe(false);
+    expect(isMissingRemoteBranchFailure('remote: Invalid username or password.\nfatal: Authentication failed')).toBe(false);
+    expect(isMissingRemoteBranchFailure('fatal: repository not found')).toBe(false);
+  });
+});

package/src/modules/workspace/__tests__/workspace.service.read-filter.test.ts

@@ -38,8 +38,14 @@ describe('WorkspaceService.listFiles — read filter', () => {
     await mkFile(workspaceDir, 'Open/a.md');
     await mkFile(workspaceDir, 'Open/b.md');
     await mkFile(workspaceDir, 'Secret/s1.md');
+    await mkFile(workspaceDir, 'Secret/Vault/v1.md');
     await mkFile(workspaceDir, 'Mixed/hidden.md');
     await mkFile(workspaceDir, 'top.md');
+    // A denied folder with a grant below it: Scopes/ itself is closed, but
+    // Scopes/Deploy/ is shared (a linked skill's folder opened to a plugin's
+    // readers, say), and its files are readable.
+    await mkFile(workspaceDir, 'Scopes/Deploy/SKILL.md');
+    await mkFile(workspaceDir, 'Scopes/other.md');
     svc = new WorkspaceService(root, 'https://example.invalid/repo.git', KB);
     await svc.getWorkspacePath(workspaceId);
   });
@@ -64,27 +70,51 @@ describe('WorkspaceService.listFiles — read filter', () => {
     expect(filtered).toEqual(unfiltered);
   });
 
-  it('drops denied files and denied directories (subtree skipped)', async () => {
-    const asked: string[] = [];
-    const filter: ReadTreeFilter = async (ps) => {
-      asked.push(...ps);
-      return new Map(ps.map((p) => [p, !(p.includes('Secret') || p.endsWith('hidden.md'))]));
-    };
-    const tree = await svc.listFiles(workspaceId, filter);
-    const all = paths(tree);
+  it('drops denied files, and a denied directory with nothing readable beneath it', async () => {
+    const filter: ReadTreeFilter = async (ps) =>
+      new Map(ps.map((p) => [p, !(p.includes('Secret') || p.includes('Scopes') || p.endsWith('hidden.md'))]));
+    const all = paths(await svc.listFiles(workspaceId, filter));
 
     // Readable files survive.
     expect(all).toContain('Open/a.md');
     expect(all).toContain('Open/b.md');
     expect(all).toContain('top.md');
-    // Denied directory and its whole subtree are gone.
+    // A denied directory whose whole subtree is denied is gone, with the
+    // subtree — including a nested folder the walk did look into.
     expect(all).not.toContain('Secret');
     expect(all).not.toContain('Secret/s1.md');
+    expect(all).not.toContain('Secret/Vault');
+    expect(all).not.toContain('Scopes');
     // Denied file is gone.
     expect(all).not.toContain('Mixed/hidden.md');
-    // The denied directory's subtree is never walked — the filter is never
-    // asked about a path inside Secret/.
-    expect(asked.some((p) => p.startsWith('Secret/'))).toBe(false);
+  });
+
+  it('keeps a denied directory as the way to what is readable beneath it', async () => {
+    // Scopes/ is closed; Scopes/Deploy/ and its file are shared. The closed
+    // folder shows as a container — the reader can reach the skill through
+    // the tree — with its own contents still filtered (other.md is gone).
+    const filter: ReadTreeFilter = async (ps) =>
+      new Map(ps.map((p) => [p, p.startsWith('Scopes/Deploy') || (!p.includes('Secret') && !p.includes('Scopes') && !p.endsWith('hidden.md'))]));
+    const all = paths(await svc.listFiles(workspaceId, filter));
+    expect(all).toContain('Scopes');
+    expect(all).toContain('Scopes/Deploy');
+    expect(all).toContain('Scopes/Deploy/SKILL.md');
+    expect(all).not.toContain('Scopes/other.md');
+    // Unchanged for a subtree with nothing readable in it.
+    expect(all).not.toContain('Secret');
+  });
+
+  it('keeps a closed folder whose only readable content is an EMPTY sub-folder', async () => {
+    // A readable folder is kept on its own verdict, children or not — so the
+    // closed folder above it has a child, and stays as the way there.
+    await fs.mkdir(path.join(workspaceDir, 'Scopes', 'Empty'), { recursive: true });
+    const filter: ReadTreeFilter = async (ps) =>
+      new Map(ps.map((p) => [p, p === 'Scopes/Empty' || (!p.includes('Secret') && !p.includes('Scopes') && !p.endsWith('hidden.md'))]));
+    const all = paths(await svc.listFiles(workspaceId, filter));
+    expect(all).toContain('Scopes');
+    expect(all).toContain('Scopes/Empty');
+    expect(all).not.toContain('Scopes/Deploy');
+    expect(all).not.toContain('Scopes/other.md');
   });
 
   it('keeps a readable directory left empty after filtering (D4)', async () => {