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

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

@@ -1,6 +1,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { KNOWLEDGE_BASE_DIR, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import {
+  KNOWLEDGE_BASE_DIR,
+  PLUGINS_DIR,
+  SKILLS_DIR,
+  renderKbLayoutPlaceholders,
+  validateKbRootName,
+} from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME } from '../../bevel-ignore.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
@@ -43,8 +49,8 @@ export const TEMPLATE_SOURCE_FALLBACKS: Readonly<Record<string, string>> = {
 };
 
 /**
- * The two roots CORE gives a knowledge base: the ontologies, and the plugins
- * that hold skills and tools.
+ * 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
  * the agentic execution layer, which is not part of this platform — a core
@@ -54,8 +60,13 @@ export const TEMPLATE_SOURCE_FALLBACKS: Readonly<Record<string, string>> = {
  * READMEs); the names stay reserved in `kb-layout.ts` either way, so a KB
  * that has them still renders them as roots rather than folding them into
  * Knowledge.
+ *
+ * A function: the three names are deployment-configurable live bindings, and
+ * a module-scope array would snapshot the defaults before configuration.
  */
-const CORE_REQUIRED_DIRS: readonly string[] = [KNOWLEDGE_BASE_DIR, PLUGINS_DIR];
+function coreRequiredDirs(): readonly string[] {
+  return [KNOWLEDGE_BASE_DIR, SKILLS_DIR, PLUGINS_DIR];
+}
 
 /**
  * A reserved root must be ONE path segment — `Data`, not `Data/x`, `../x` or
@@ -102,7 +113,7 @@ export function reservedRootDirs(extraRootDirs: readonly string[]): readonly str
       );
     }
   }
-  return [...CORE_REQUIRED_DIRS, ...extraRootDirs];
+  return [...coreRequiredDirs(), ...extraRootDirs];
 }
 
 /**
@@ -200,14 +211,18 @@ export class TemplateFilesStep implements OnServerStart {
             'Remove or rename it — the platform requires this name to be a readable file.',
         );
       }
-      let content: Uint8Array | string = await readTemplate(templateDir, rel);
+      let content = await readTemplate(templateDir, rel);
       // The on-disk merge below only runs against an EXISTING ignore file; a
       // freshly-declared one was merely assumed to carry the AGENTS.md rule —
       // true of the packaged template, not necessarily of a distribution's
       // custom one. Make it true here, so the managed conventions doc is
       // hidden from the file tree from the first boot either way.
+      // …and a template still shipping the skills rule an earlier release
+      // had (a distribution's copy, a stale packaged one) must not declare
+      // it: the on-disk reconciliation below never sees a file that was
+      // absent, so the declared content is reconciled here instead.
       if (rel === IGNORE_FILENAME) {
-        content = withIgnorePattern(new TextDecoder().decode(content), 'AGENTS.md');
+        content = withoutPlatformIgnorePattern(withIgnorePattern(content, 'AGENTS.md'), `${SKILLS_DIR}/`);
       }
       branch.write(rel, content);
       added.push(rel);
@@ -224,7 +239,20 @@ export class TemplateFilesStep implements OnServerStart {
     // LINE PRESENCE, not effective outcome: a later `!AGENTS.md` negation is
     // the operator explicitly choosing to SHOW the file, and hiding it is a
     // default this step provides, not a mandate it re-imposes every boot.
-    added.push(...(await mergeIgnorePattern(repoDir, branch, 'AGENTS.md')));
+    //
+    // The shared-skills root goes the OTHER way. An earlier release hid it
+    // like `Plugins/`; the Skills & Tools sidebar now renders it as a file
+    // tree read from the workspace tree, which the ignore file filters — so a
+    // KB still carrying that rule would show an empty Skills section. The
+    // line that release wrote comes out, recognised by the PLATFORM'S OWN
+    // COMMENT above it — an operator who wrote the same rule by hand keeps
+    // it, for the same reason the negation above is kept: the file is
+    // theirs. The Knowledge explorer never rendered the root and still does
+    // not. Spelled with the CONFIGURED root name, since a deployment may
+    // have renamed it. ONE read-modify-write for both rules: two passes
+    // would each read the on-disk file and the second declared write would
+    // lose the first's.
+    added.push(...(await reconcileIgnoreRules(repoDir, branch, { add: ['AGENTS.md'], drop: [`${SKILLS_DIR}/`] })));
 
     // AGENTS.md is MANAGED, not merely seeded: the platform owns its content,
     // and a stale copy is replaced with the packaged template's every startup
@@ -293,59 +321,135 @@ export class TemplateFilesStep implements OnServerStart {
   }
 }
 
-/** The template's content for `relPath`, bytes as shipped. */
-async function readTemplate(templateDir: string, relPath: string): Promise<Uint8Array> {
-  return fs.readFile(await templateSource(templateDir, relPath));
+/**
+ * The template's content for `relPath`, RENDERED: the managed files name the
+ * three root folders, and a deployment may have renamed those, so the
+ * placeholders the template carries (`{{pluginsDir}}` …) are filled with the
+ * names in effect. Every required file is text; a template without
+ * placeholders passes through unchanged.
+ */
+async function readTemplate(templateDir: string, relPath: string): Promise<string> {
+  return renderKbLayoutPlaceholders(await fs.readFile(await templateSource(templateDir, relPath), 'utf8'));
 }
 
 /**
- * Whether the repo's copy of `relPath` differs from the template's, modulo
- * line endings — a CRLF checkout of identical content must read as "same",
- * or the managed-file refresh would commit churn on every boot forever.
+ * Whether the repo's copy of `relPath` differs from the RENDERED template's,
+ * modulo line endings — a CRLF checkout of identical content must read as
+ * "same", or the managed-file refresh would commit churn on every boot
+ * forever. Rendered, so a renamed root is compared against the guide that
+ * names it, not against the placeholders.
  */
 async function templateDiffers(templateDir: string, repoDir: string, relPath: string): Promise<boolean> {
   const norm = (text: string) => text.replace(/\r\n?/g, '\n');
   const [current, template] = await Promise.all([
     fs.readFile(path.join(repoDir, relPath), 'utf8'),
-    templateSource(templateDir, relPath).then((from) => fs.readFile(from, 'utf8')),
+    readTemplate(templateDir, relPath),
   ]);
   return norm(current) !== norm(template);
 }
 
 /**
- * Ensure `.bevelignore` carries `pattern`, declaring the appended content when
- * absent. Returns the paths changed, for the note.
+ * Reconcile the platform's OWN rules in `.bevelignore`: every `add` pattern
+ * guaranteed present as a line, every `drop` pattern taken out. Returns the
+ * paths changed, for the note.
  *
- * APPENDS — never rewrites. The file is the operator's, and every rule
- * already in it is theirs to keep; this adds one line under a comment saying
- * where it came from. Absent file, or a file that already lists the pattern,
- * is a no-op — an absent file means the template's copy (declared in the same
- * step) arrives with the pattern in it.
+ * Never rewrites the rest. The file is the operator's, and every rule already
+ * in it is theirs to keep: adding puts one line under a comment saying where
+ * it came from, and dropping removes exactly the line (and the comment) an
+ * earlier release put there — never a line the operator wrote. Absent file is
+ * a no-op — it means the template's copy (declared in the same step, and
+ * reconciled the same way at declaration) arrives with the right rules in it.
  *
  * Matched line-wise rather than by substring: a rule for `Plugins/AGENTS.md`
  * is not a rule for the root `AGENTS.md`, and treating it as one would leave
  * the mismatch this exists to close.
  */
-async function mergeIgnorePattern(repoDir: string, branch: KbBranch, pattern: string): Promise<string[]> {
+async function reconcileIgnoreRules(
+  repoDir: string,
+  branch: KbBranch,
+  rules: { add: string[]; drop: string[] },
+): Promise<string[]> {
   let current: string;
   try {
     current = await fs.readFile(path.join(repoDir, IGNORE_FILENAME), 'utf8');
   } catch {
     // No ignore file — the copy declared from the template arrives with the
-    // pattern in it (guaranteed at declaration time, see the required-files
-    // loop above).
+    // right rules in it (guaranteed at declaration time, see the
+    // required-files loop above).
     return [];
   }
-  const merged = withIgnorePattern(current, pattern);
+  const added = rules.add.reduce((text, pattern) => withIgnorePattern(text, pattern), current);
+  const merged = rules.drop.reduce((text, pattern) => withoutPlatformIgnorePattern(text, pattern), added);
   if (merged === current) return [];
   branch.write(IGNORE_FILENAME, merged);
   return [IGNORE_FILENAME];
 }
 
+/** The comment `withIgnorePattern` writes above a line it appends. */
+const PLATFORM_RULE_COMMENT = '# Added by the platform: the conventions doc is not node content.';
+
+/**
+ * The template line an earlier release shipped above the shared-skills rule,
+ * split around its one variable: the plugins root's name, which a deployment
+ * may have renamed since. Everything else is fixed.
+ */
+const LEGACY_SKILLS_RULE_COMMENT_OPENING = '# The shared-skills root is rendered by the Skills & Tools app, like ';
+const LEGACY_SKILLS_RULE_COMMENT_CLOSING = '/.';
+
+/**
+ * Whether a line is EXACTLY a comment the platform wrote above a rule it
+ * added. For the legacy template line that means the fixed opening, the
+ * fixed closing, and between them a name the platform could have rendered
+ * there — judged by the ONE rule that decides what a root may be called
+ * (`validateKbRootName`), not by a second grammar written here: a hand-made
+ * character class either admits names the validator refuses, or refuses
+ * names it admits (a space, say), and either way a line the platform did
+ * write would be left standing. A looser match (an opening, a substring)
+ * errs the other way and takes a line the operator wrote.
+ */
+function isPlatformRuleComment(line: string): boolean {
+  const trimmed = line.trim();
+  if (trimmed === PLATFORM_RULE_COMMENT) return true;
+  if (
+    !trimmed.startsWith(LEGACY_SKILLS_RULE_COMMENT_OPENING) ||
+    !trimmed.endsWith(LEGACY_SKILLS_RULE_COMMENT_CLOSING)
+  ) {
+    return false;
+  }
+  const name = trimmed.slice(
+    LEGACY_SKILLS_RULE_COMMENT_OPENING.length,
+    trimmed.length - LEGACY_SKILLS_RULE_COMMENT_CLOSING.length,
+  );
+  return name === name.trim() && validateKbRootName(name) === null;
+}
+
+/**
+ * `text` without the `pattern` lines THE PLATFORM WROTE — the ones sitting
+ * directly under its own comment (the one `withIgnorePattern` writes, or the
+ * template line an earlier release shipped) — and without that comment, plus
+ * the blank line that opened an appended block. Provenance is the comment:
+ * an identical line with no platform comment above it is the operator's and
+ * stays, as does a `!pattern` negation. Nothing else moves.
+ */
+function withoutPlatformIgnorePattern(text: string, pattern: string): string {
+  const lines = text.split('\n');
+  const kept: string[] = [];
+  for (const line of lines) {
+    const above = kept[kept.length - 1];
+    if (line.trim() !== pattern || above === undefined || !isPlatformRuleComment(above)) {
+      kept.push(line);
+      continue;
+    }
+    kept.pop();
+    if (above.trim() === PLATFORM_RULE_COMMENT && kept.length > 1 && kept[kept.length - 1]?.trim() === '') kept.pop();
+  }
+  return kept.join('\n');
+}
+
 /**
  * `text` with `pattern` guaranteed present as a LINE — appended under a
  * comment naming its origin when absent, returned unchanged when present.
- * Line-wise match, same rationale as {@link mergeIgnorePattern}.
+ * Line-wise match, same rationale as {@link mergeIgnorePatterns}.
  *
  * An explicit `!pattern` line also returns the text unchanged: that is the
  * operator choosing to SHOW the file, and ordered matching means a positive

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

@@ -4,15 +4,7 @@ import { IGNORE_FILENAME } from './bevel-ignore.js';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
 import express from 'express';
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
-import {
-  AGENTS_DIR,
-  DATA_DIR,
-  DEFAULT_BRANCH,
-  KNOWLEDGE_BASE_DIR,
-  KNOWLEDGE_DIR,
-  PIPELINES_DIR,
-  PLUGINS_DIR,
-} from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, KNOWLEDGE_DIR, reservedRootDirNames } from '@bevel-software/platform-shared';
 import { FolderTooLargeError, type ReadTreeFilter } from './workspace.service.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkspaceService } from './workspace.service.js';
@@ -290,6 +282,13 @@ export function createWorkspaceRoutes(
       );
       res.json({ workspace, fileTree });
     } catch (error) {
+      // 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) {
+        sendError(res, error);
+        return;
+      }
       // Log the full stack so the next 500 isn't a guessing game — the
       // bare `error.message` we returned before lost most diagnostic
       // signal (cause chain, stack frames, error class).
@@ -476,14 +475,7 @@ export function createWorkspaceRoutes(
       // same treatment so legacy clones don't collapse. Only the folders
       // themselves are forced visible — their contents stay gated by the
       // verdict above.
-      const structuralRoots = new Set([
-        KNOWLEDGE_BASE_DIR,
-        DATA_DIR,
-        AGENTS_DIR,
-        PIPELINES_DIR,
-        PLUGINS_DIR,
-        KNOWLEDGE_DIR,
-      ]);
+      const structuralRoots = new Set([...reservedRootDirNames(), KNOWLEDGE_DIR]);
       for (const wp of wsRelPaths) {
         const rel = toKbRelative(wp, kbDirName);
         if (rel !== null && structuralRoots.has(rel)) verdict.set(wp, true);

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

@@ -7,7 +7,11 @@ import type { AuthUser, IWorkspaceService, WorkspaceInfo, FileTreeEntry } from '
 import { assertValidRelativePath, validateFilename, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { BevelIgnoreStack } from './bevel-ignore.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import {
+  RemoteBranchGoneError,
+  WorkflowDomainError,
+  isMissingRemoteBranchFailure,
+} from '../../shared/domain-errors.js';
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import {
   cloneCredentialArgs,
@@ -248,6 +252,73 @@ export class WorkspaceService implements IWorkspaceService {
     return null;
   }
 
+  /**
+   * Every branch with a finished clone on disk, whether or not this process
+   * has touched it yet. The remote sync reads this: clones survive a restart,
+   * and a hook that fires before anyone opens a branch must still find its
+   * clone. Same disk scan as `findAnyWorkspaceId`.
+   *
+   * What is listed: directories holding a `<kbDirName>/.git`, whose name is
+   * the encoding of a branch git would accept, and whose bootstrap is not in
+   * flight right now. The in-flight exclusion matters because `git clone`
+   * creates `.git` long before the working tree is checked out — pulling a
+   * clone mid-bootstrap would run git against a half-written tree — and a
+   * clone that is being created this instant is current by definition. A
+   * clone left behind by a crash mid-checkout is NOT distinguished here: the
+   * rest of this service treats a directory with `.git` as a clone too, and
+   * the pull's own errors are how such a tree surfaces.
+   *
+   * A missing root means no clones (nothing has been bootstrapped yet); any
+   * other failure to read it is propagated, so a sync cannot report success
+   * over a root it could not see. One entry that cannot be probed (an ACL, a
+   * half-deleted directory) is returned with `unreadable` set rather than
+   * thrown, so it fails as one branch and not as the whole listing.
+   */
+  async listClonedWorkspaces(): Promise<Array<{ id: string; branch: string; unreadable?: string }>> {
+    let entries: Array<{ name: string; isDirectory: () => boolean }>;
+    try {
+      entries = await fs.readdir(this.workspacesRoot, { withFileTypes: true });
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException | null)?.code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') return [];
+      throw err;
+    }
+    const cloned: Array<{ id: string; branch: string; unreadable?: string }> = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const branch = branchForWorkspaceId(entry.name);
+      // Not one of ours unless the name is the encoding of a branch git
+      // accepts: `branchForWorkspaceId` returns a malformed name unchanged, so
+      // the round-trip catches those, and the validator catches a stray
+      // directory whose name merely round-trips.
+      if (workspaceIdForBranch(branch) !== entry.name) continue;
+      try {
+        assertValidBranchName(branch);
+      } catch {
+        continue;
+      }
+      try {
+        await fs.access(path.join(this.workspacesRoot, entry.name, this.kbDirName, '.git'));
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException | null)?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') continue;
+        cloned.push({
+          id: entry.name,
+          branch,
+          unreadable: `Could not read this branch's clone: ${redactError(err)}`,
+        });
+        continue;
+      }
+      // AFTER the probe, with no await in between: a bootstrap registers
+      // itself before it creates `.git`, so any clone whose `.git` was found
+      // while its bootstrap is running is in this map by now. Checking before
+      // the probe left a window where the clone started in between.
+      if (this.isBootstrapInFlight(branch)) continue;
+      cloned.push({ id: entry.name, branch });
+    }
+    return cloned;
+  }
+
   /**
    * Run the clone. When a `referenceRepo` is supplied and the referenced
    * clone fails (e.g. the sibling's object store is corrupt or mid-write),
@@ -408,6 +479,15 @@ export class WorkspaceService implements IWorkspaceService {
     }
   }
 
+  /**
+   * Whether a clone of `branch` is being created at this moment. Read by the
+   * retirement of a clone the host deleted: a bootstrap in flight means the
+   * branch exists again, so there is nothing stale to remove.
+   */
+  isBootstrapInFlight(branch: string): boolean {
+    return this.inFlightBootstraps.has(branch);
+  }
+
   /**
    * Bring an adopted clone's config back to what a fresh clone would carry.
    *
@@ -620,9 +700,18 @@ export class WorkspaceService implements IWorkspaceService {
       }
     } catch (err) {
       const redacted = redactError(err);
-      console.error(`[workspace] Failed to clone for branch "${branch}":`, redacted);
       // Roll back partial state so the next bootstrap retries cleanly.
       await fs.rm(targetDir, { recursive: true, force: true }).catch(() => {});
+      // A branch origin does not have is a fact about the branch, not a
+      // failure of ours: the host deleted it (and the sync retired the
+      // clone), or the link was to a branch that never existed. Typed, so the
+      // routes answer 410 with the branch named and the browser can say "this
+      // branch no longer exists" instead of "something went wrong".
+      if (isMissingRemoteBranchFailure(redacted)) {
+        console.log(`[workspace] branch "${branch}" does not exist on origin — nothing to clone`);
+        throw new RemoteBranchGoneError(branch);
+      }
+      console.error(`[workspace] Failed to clone for branch "${branch}":`, redacted);
       throw new Error(`Failed to clone process map: ${redacted}`);
     }
   }
@@ -1433,23 +1522,25 @@ export class WorkspaceService implements IWorkspaceService {
       });
     }
 
-    // Read-permission filter: ONE batched check per directory. Drops files AND
-    // directories the caller can't read; a hidden directory's subtree is never
-    // walked (skip-and-don't-recurse). A readable directory left empty after
-    // filtering stays visible (the folder itself is readable). Fail-closed:
-    // anything not explicitly readable is dropped. No filter → identical to the
-    // pre-feature tree (regression-safe).
-    let visible = candidates;
-    if (readFilter && candidates.length > 0) {
-      const verdict = await readFilter(candidates.map((c) => c.rel));
-      visible = candidates.filter((c) => verdict.get(c.rel) === true);
-    }
+    // Read-permission filter: ONE batched check per directory. Drops files the
+    // caller can't read. A directory is kept when the caller can read it — a
+    // readable directory left empty after filtering stays visible, the folder
+    // itself is readable — OR when something readable survives beneath it: a
+    // grant below (a linked skill's folder opened to a plugin's readers, a
+    // sub-folder shared on its own) makes the folders above it the way there,
+    // shown as containers whose own contents stay filtered. So an unreadable
+    // directory is walked, not skipped, and dropped only when the walk finds
+    // nothing. Fail-closed: anything not explicitly readable is dropped. No
+    // filter → identical to the pre-feature tree (regression-safe).
+    const verdict = readFilter && candidates.length > 0 ? await readFilter(candidates.map((c) => c.rel)) : null;
+    const readable = (rel: string) => verdict === null || verdict.get(rel) === true;
 
     const children: FileTreeEntry[] = [];
-    for (const { entry, entryPath, rel } of visible) {
+    for (const { entry, entryPath, rel } of candidates) {
       if (entry.isDirectory()) {
-        children.push(await this.buildFileTree(entryPath, workspaceRoot, ignoreStack, readFilter));
-      } else {
+        const sub = await this.buildFileTree(entryPath, workspaceRoot, ignoreStack, readFilter);
+        if (readable(rel) || (sub.children?.length ?? 0) > 0) children.push(sub);
+      } else if (readable(rel)) {
         children.push({ name: entry.name, relativePath: rel, type: 'file' });
       }
     }

package/src/shared/__tests__/fs-walk.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+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';
@@ -39,4 +39,25 @@ describe('walkFiles', () => {
 
     expect(await walkFiles(root, (n) => n.endsWith('.tool'))).toEqual(['visible.tool']);
   });
+
+  it('skips a directory it cannot list by default, and throws for a strict caller', async () => {
+    await fs.mkdir(path.join(root, 'locked'), { recursive: true });
+    await fs.writeFile(path.join(root, 'locked/a.tool'), '');
+    await fs.writeFile(path.join(root, 'b.tool'), '');
+    const real = fs.readdir;
+    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) => {
+      if (String(dir).endsWith('locked')) {
+        return Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }));
+      }
+      return (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts);
+    }) as never);
+    try {
+      // A catalog shows what it can…
+      expect(await walkFiles(root, (n) => n.endsWith('.tool'))).toEqual(['b.tool']);
+      // …a caller that must see everything gets the error, not a list with a hole.
+      await expect(walkFiles(root, (n) => n.endsWith('.tool'), { strict: true })).rejects.toThrow('EACCES');
+    } finally {
+      spy.mockRestore();
+    }
+  });
 });

package/src/shared/__tests__/kb-walk.test.ts

@@ -0,0 +1,107 @@
+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 { walkKb, type KbWalkListener } from '../kb-walk.js';
+
+/**
+ * The one walk: what it skips, in what order it visits, what it calls a hole
+ * — and that every listener on it is told exactly the same things.
+ */
+describe('walkKb', () => {
+  let root: string;
+  const write = async (rel: string, text = '') => {
+    const abs = path.join(root, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+  /** A listener that records every event it is told, in order. */
+  const recorder = () => {
+    const events: string[] = [];
+    const listener: KbWalkListener = {
+      onDir: (rel, entries) => void events.push(`dir ${rel || '.'} [${entries.map((e) => e.name).join(' ')}]`),
+      onFile: (dir, name) => void events.push(`file ${dir ? `${dir}/${name}` : name}`),
+      onHole: (rel) => void events.push(`hole ${rel || '.'}`),
+    };
+    return { events, listener };
+  };
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-walk-'));
+  });
+  afterEach(() => fs.rm(root, { recursive: true, force: true }));
+
+  it('visits every folder once, in component order, skipping dot-entries and node_modules', async () => {
+    await write('Plugins/a-b/plugin.json');
+    await write('Plugins/a/b/plugin.json');
+    await write('KnowledgeBase/x.md');
+    await write('.git/HEAD');
+    await write('node_modules/dep/index.js');
+    await write('Plugins/.parked/plugin.json');
+    const { events, listener } = recorder();
+    const { holes } = await walkKb(root, [listener]);
+    expect(holes).toEqual([]);
+    expect(events).toEqual([
+      'dir . [KnowledgeBase Plugins]',
+      'dir KnowledgeBase [x.md]',
+      'file KnowledgeBase/x.md',
+      'dir Plugins [a a-b]', // "a" before "a-b": the walk order every consumer agrees on
+      'dir Plugins/a [b]',
+      'dir Plugins/a/b [plugin.json]',
+      'file Plugins/a/b/plugin.json',
+      'dir Plugins/a-b [plugin.json]',
+      'file Plugins/a-b/plugin.json',
+    ]);
+  });
+
+  it('tells every listener the same things', async () => {
+    await write('Plugins/GTM/plugin.json');
+    await write('Skills/Eng/deploy/SKILL.md');
+    const a = recorder();
+    const b = recorder();
+    await walkKb(root, [a.listener, b.listener]);
+    expect(a.events.length).toBeGreaterThan(0);
+    expect(b.events).toEqual(a.events);
+  });
+
+  it('a folder that exists but cannot be listed is a hole — reported to every listener and in the result', async () => {
+    await write('Plugins/locked/plugin.json');
+    await write('Plugins/open/plugin.json');
+    const real = fs.readdir;
+    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) =>
+      String(dir).endsWith('locked')
+        ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
+        : (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts)) as never);
+    try {
+      const { events, listener } = recorder();
+      const { holes } = await walkKb(root, [listener]);
+      expect(holes).toEqual(['Plugins/locked']);
+      expect(events).toContain('hole Plugins/locked');
+      // The rest of the tree is still walked.
+      expect(events).toContain('file Plugins/open/plugin.json');
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('a missing root is an empty walk; a folder that vanished between listing and visiting is not a hole', async () => {
+    const empty = recorder();
+    expect(await walkKb(path.join(root, 'nope'), [empty.listener])).toEqual({ holes: [] });
+    expect(empty.events).toEqual([]);
+
+    await write('Plugins/gone/plugin.json');
+    const real = fs.readdir;
+    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) =>
+      String(dir).endsWith('gone')
+        ? Promise.reject(Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' }))
+        : (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts)) as never);
+    try {
+      const { events, listener } = recorder();
+      const { holes } = await walkKb(root, [listener]);
+      expect(holes).toEqual([]);
+      expect(events.some((e) => e.startsWith('hole'))).toBe(false);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/shared/__tests__/path-order.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { comparePathComponents } from '../path-order.js';
+
+describe('comparePathComponents', () => {
+  it('orders component by component, the way a sorted directory walk visits paths', () => {
+    // A whole-string compare would weigh "-" against "/" and put a-b/x first.
+    expect(comparePathComponents('a/b/x', 'a-b/x')).toBeLessThan(0);
+    expect(comparePathComponents('Plugins/GTM', 'Plugins/GTM/skills')).toBeLessThan(0);
+    expect(comparePathComponents('Plugins/GTM', 'Plugins/GTM')).toBe(0);
+  });
+
+  it('never calls two distinct paths equal: a collation tie falls through to code-unit order', () => {
+    // Precomposed é and its decomposed spelling collate as equal; two folders
+    // so named must still have ONE first, or discovery and principal synthesis
+    // could each claim a different one for the same slug.
+    const composed = 'Plugins/café';
+    const decomposed = 'Plugins/café';
+    // (Whether the host's collation equates them is the host's business —
+    // the property under test holds either way: distinct paths never tie.)
+    const order = comparePathComponents(composed, decomposed);
+    expect(order).not.toBe(0);
+    expect(comparePathComponents(decomposed, composed)).toBe(-order);
+  });
+});