@bevel-software/platform-shared 0.14.0 → 0.15.1

package/dist/workspace/kb-layout.js

@@ -1,4 +1,5 @@
 import { branchSegment } from '../git/branchAuthor.js';
+import { validateFilename } from './filename.js';
 /**
  * Top-level layout of the KB repo (inside the `KB_DIR_NAME` clone).
  *
@@ -7,7 +8,8 @@ import { branchSegment } from '../git/branchAuthor.js';
  *
  *   <kbDirName>/
  *   ├── KnowledgeBase/   ← all team ontologies live here (the knowledge graph)
- *   ├── Plugins/         ← one folder per plugin; each holds BOTH skills and tools
+ *   ├── Skills/          ← shared skills, organised by ownership; plugins LINK to them
+ *   ├── Plugins/         ← one folder per plugin: manifest, MCP servers, tools, links
  *   ├── Data/            ← agent-produced records; parsed like KnowledgeBase/
  *   ├── Agents/          ← .agent files — agent role configurations (not the graph)
  *   ├── Pipelines/       ← .pipeline files — execution-layer processes (not the graph)
@@ -23,21 +25,44 @@ import { branchSegment } from '../git/branchAuthor.js';
  *
  * These names are the single source of truth for both sides of the app:
  *  - Backend: the graph parser discovers ontologies under the
- *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Plugins/`,
+ *    {@link ontologyRoots} (`KnowledgeBase/` and `Data/`); `Plugins/`,
  *    `Agents/`, `Pipelines/` (and anything else at the root) are ignored by
  *    parsing, validation, and the diagram.
  *  - Frontend: the file tree renders these root folders as distinct
  *    top-level sections.
  *
  * Don't hard-code these strings elsewhere — import them from here.
+ *
+ * CONFIGURABLE, WITH DEFAULTS. The three roots a deployment may rename
+ * (`KnowledgeBase/`, `Skills/`, `Plugins/`) are `let` bindings applied by
+ * {@link configureKbLayout} — the backend from its deployment settings, the
+ * browser from `GET /api/config` — the same live-binding pattern as the branch
+ * model in `git/protected.ts`. Unlike the branch model they carry defaults, so
+ * nothing has to wait for configuration; but the same rule applies: read them
+ * inside a function body, never capture one at module scope.
  */
 /** Folder under the repo root that contains all team ontologies. */
-export const KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
+export let KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
+/**
+ * Folder under the repo root that holds SHARED skills, organised by ownership:
+ *
+ *   Skills/<scope>/…/<skill>/SKILL.md     a skill, at any depth
+ *   Skills/<scope>/access.md              who owns / may read the scope
+ *
+ * A skill's readability comes from ITS OWN path walk — the scope folders'
+ * `access.md` files — never from the plugins that link it. Plugins point at
+ * skills here by path (see `HEXIS_LINKED_SKILLS_KEY`), so one definition can
+ * ship in several plugins, and a skill in no plugin at all is a normal state.
+ * Inline skills under `Plugins/<Plugin>/skills/` remain supported (personal
+ * folders, legacy layouts); the catalog is the union of both trees.
+ */
+export let SKILLS_DIR = 'Skills';
 /**
  * Folder under the repo root that holds the plugins.
  *
- *   Plugins/<Plugin>/plugin.json                  the Agent Plugins manifest
- *   Plugins/<Plugin>/skills/<skill>/SKILL.md      a skill
+ *   Plugins/<Plugin>/plugin.json                  the Agent Plugins manifest; its
+ *                                                 hexis extension lists LINKED skills
+ *   Plugins/<Plugin>/skills/<skill>/SKILL.md      an inline skill
  *   Plugins/<Plugin>/mcp.json                     MCP servers
  *   Plugins/<Plugin>/software.bevel.hexis/tools/  http + inline `.tool` manuals
  *   Plugins/<Plugin>/access.md                    who can read/write the plugin
@@ -56,10 +81,11 @@ export const KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
  *    `inline` types the spec has no slot for. `mcp`-type manuals are emitted as
  *    real `mcp.json` entries instead, so the portable half stays portable.
  *
- * Skills and tools live TOGETHER in one plugin because they share a single
- * access boundary: a tool a plugin cannot read is a skill that plugin cannot
- * run, so splitting them across two roots meant maintaining the same permission
- * twice and letting them drift.
+ * A plugin's own `access.md` governs what the plugin FOLDER holds: the
+ * manifest, the MCP servers, the tools, and any inline skills. Shared skills
+ * under `Skills/` are governed by their own scope and are made visible to a
+ * plugin's members by granting the plugin's principal (`plugin/<Name>/read`)
+ * on the skill — ownership decides, the plugin is a view.
  *
  * A plugin is not a registry of unique names — it is a folder. The same
  * integration may exist in several plugins as separate files (`Everyone/…/
@@ -71,7 +97,98 @@ export const KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
  * display casing. The lowercase slug the spec does constrain lives in the
  * manifest's `name` field.
  */
-export const PLUGINS_DIR = 'Plugins';
+export let PLUGINS_DIR = 'Plugins';
+/** The layout a deployment gets when it names nothing. */
+export const DEFAULT_KB_LAYOUT = Object.freeze({
+    knowledgeBaseDir: 'KnowledgeBase',
+    skillsDir: 'Skills',
+    pluginsDir: 'Plugins',
+});
+/**
+ * What is wrong with one root name, or null. A root is joined onto the repo
+ * root and onto `<dir>/.gitkeep`, so a separator or `..` would write outside
+ * the repository; a dot-prefixed name would be skipped by every scanner that
+ * treats dot-entries as bookkeeping; `.git` in any case would corrupt the clone.
+ */
+export function validateKbRootName(name) {
+    const v = name.trim();
+    if (!v)
+        return 'A folder name is required.';
+    if (v.includes('/') || v.includes('\\'))
+        return 'Use a single folder name — no slashes.';
+    // The ONE rule for what a path segment may be called — the same one every
+    // file and folder made through the platform passes (reserved Windows
+    // names, trailing dots, forbidden characters, length) — plus what a ROOT
+    // must not be: dot-prefixed, which every scanner skips as bookkeeping.
+    const asName = validateFilename(v);
+    if (asName)
+        return asName;
+    if (v.startsWith('.'))
+        return 'The name can\'t start with a dot.';
+    return null;
+}
+/**
+ * What is wrong with a layout, or null — the same rule {@link configureKbLayout}
+ * enforces, without applying anything. Separate so the setup screen can judge a
+ * proposed layout before it is saved. The three names must differ, compared
+ * case-insensitively: the workspaces live on case-insensitive filesystems too,
+ * where `Skills` and `skills` are one folder.
+ */
+export function validateKbLayout(layout) {
+    for (const [label, value] of [
+        ['knowledge base', layout.knowledgeBaseDir],
+        ['skills', layout.skillsDir],
+        ['plugins', layout.pluginsDir],
+    ]) {
+        const problem = validateKbRootName(value ?? '');
+        if (problem)
+            return `The ${label} folder: ${problem}`;
+    }
+    const names = [layout.knowledgeBaseDir, layout.skillsDir, layout.pluginsDir].map((n) => n.trim().toLowerCase());
+    if (new Set(names).size !== names.length) {
+        return 'The knowledge base, skills and plugins folders must have three different names.';
+    }
+    // The fixed reserved roots are taken too: naming the skills folder `Data`
+    // would give one directory two reserved roles.
+    const fixed = [DATA_DIR, AGENTS_DIR, PIPELINES_DIR].map((n) => n.toLowerCase());
+    const clash = names.find((n) => fixed.includes(n));
+    if (clash)
+        return `"${clash}" is a reserved folder name (${[DATA_DIR, AGENTS_DIR, PIPELINES_DIR].join(', ')}).`;
+    return null;
+}
+/**
+ * Apply the layout. Called once during boot on each side; throws on an invalid
+ * one so a bad deployment setting fails beside the rest of the wiring rather
+ * than scattering a half-renamed tree. Applying the defaults is a no-op.
+ */
+export function configureKbLayout(layout) {
+    const problem = validateKbLayout(layout);
+    if (problem)
+        throw new Error(problem);
+    KNOWLEDGE_BASE_DIR = layout.knowledgeBaseDir.trim();
+    SKILLS_DIR = layout.skillsDir.trim();
+    PLUGINS_DIR = layout.pluginsDir.trim();
+}
+/** The layout currently in effect. */
+export function currentKbLayout() {
+    return { knowledgeBaseDir: KNOWLEDGE_BASE_DIR, skillsDir: SKILLS_DIR, pluginsDir: PLUGINS_DIR };
+}
+/**
+ * Render the layout placeholders a managed template carries —
+ * `{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}` — with the
+ * names in effect. The packaged `AGENTS.md` and `.bevelignore` are written
+ * this way so a deployment that renamed its roots hands the agent a guide
+ * that names the folders it will actually find. Text without placeholders
+ * passes through unchanged.
+ */
+export function renderKbLayoutPlaceholders(text, layout = currentKbLayout()) {
+    // Replacer FUNCTIONS: a string replacement would interpret `$&`, `$$` and
+    // friends inside a folder name, and `$` is a legal character in one.
+    return text
+        .replaceAll('{{knowledgeBaseDir}}', () => layout.knowledgeBaseDir)
+        .replaceAll('{{skillsDir}}', () => layout.skillsDir)
+        .replaceAll('{{pluginsDir}}', () => layout.pluginsDir);
+}
 /**
  * The pre-rename name of {@link PLUGINS_DIR}. Referenced ONLY by the migration
  * that renames it — every other consumer should be reading the new name, and a
@@ -94,6 +211,105 @@ export const PLUGIN_SKILLS_DIR = 'skills';
 export const HEXIS_EXTENSION_NS = 'software.bevel.hexis';
 /** UTCP manuals whose `http`/`inline` types the spec cannot express. */
 export const HEXIS_TOOLS_DIR = `${HEXIS_EXTENSION_NS}/tools`;
+/**
+ * The manifest key under which a plugin LINKS shared skills:
+ *
+ *   plugin.json → extensions["software.bevel.hexis"].skills: [
+ *     "Skills/Engineering/deploy",   ← one skill folder
+ *     "Skills/Sales"                 ← a folder of skills: every skill beneath
+ *   ]
+ *
+ * Entries are repo-root-relative folder paths. A plugin's effective skill set
+ * is its inline `skills/` folder PLUS everything these roots resolve to. The
+ * spec reserves `extensions` for exactly this kind of client-specific data, so
+ * a conformant client that ignores it still gets a valid manifest; the
+ * compiled distribution copies the linked skills in for it.
+ *
+ * Linking is a reference, not a grant: a member of the plugin can read a
+ * linked skill only because the skill's own access rules name the plugin's
+ * principal (`plugin/<Name>/read`). The link service writes both together.
+ */
+export const HEXIS_LINKED_SKILLS_KEY = 'skills';
+/**
+ * Normalise a linked-skill root, or null when it cannot be one: a
+ * repo-root-relative POSIX folder path with no `..`, no leading slash, no
+ * backslashes and no empty segments. Trailing slashes are dropped.
+ */
+export function normalizeSkillRoot(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.includes('\\') || trimmed.startsWith('/'))
+        return null;
+    const segments = trimmed.split('/');
+    // Only TRAILING slashes are forgiven; an empty segment anywhere else
+    // (`Skills//deploy`) is a malformed path, not a spelling of a valid one.
+    while (segments.length > 0 && segments[segments.length - 1] === '')
+        segments.pop();
+    if (segments.length === 0)
+        return null;
+    if (segments.some((s) => s === '' || s === '.' || s === '..'))
+        return null;
+    return segments.join('/');
+}
+/**
+ * The linked-skill roots a parsed manifest declares — invalid entries are
+ * dropped, duplicates collapsed, order kept. A manifest with no extension
+ * block links nothing.
+ */
+export function linkedSkillRoots(manifest) {
+    if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest))
+        return [];
+    const ext = manifest.extensions;
+    if (typeof ext !== 'object' || ext === null)
+        return [];
+    const ns = ext[HEXIS_EXTENSION_NS];
+    if (typeof ns !== 'object' || ns === null)
+        return [];
+    const raw = ns[HEXIS_LINKED_SKILLS_KEY];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const root = normalizeSkillRoot(typeof entry === 'string' ? entry : '');
+        if (root !== null && !out.includes(root))
+            out.push(root);
+    }
+    return out;
+}
+/**
+ * The manifest with its linked-skill roots REPLACED by `roots`, every other
+ * byte of the object preserved (the MCP extension block beside it, the
+ * portable fields above it). An empty list removes the key rather than
+ * leaving `skills: []` behind.
+ */
+export function withLinkedSkillRoots(manifest, roots) {
+    const extensions = typeof manifest.extensions === 'object' && manifest.extensions !== null && !Array.isArray(manifest.extensions)
+        ? { ...manifest.extensions }
+        : {};
+    const current = extensions[HEXIS_EXTENSION_NS];
+    const ns = typeof current === 'object' && current !== null && !Array.isArray(current)
+        ? { ...current }
+        : {};
+    if (roots.length > 0)
+        ns[HEXIS_LINKED_SKILLS_KEY] = [...roots];
+    else
+        delete ns[HEXIS_LINKED_SKILLS_KEY];
+    if (Object.keys(ns).length > 0)
+        extensions[HEXIS_EXTENSION_NS] = ns;
+    else
+        delete extensions[HEXIS_EXTENSION_NS];
+    const out = { ...manifest };
+    if (Object.keys(extensions).length > 0)
+        out.extensions = extensions;
+    else
+        delete out.extensions;
+    return out;
+}
+/** Whether `skillPath` (a skill folder) falls under `root` (a skill folder or a folder of skills). */
+export function skillUnderRoot(skillPath, root) {
+    return skillPath === root || skillPath.startsWith(`${root}/`);
+}
 /**
  * The manifest `name` for a plugin folder: lowercased, anything outside
  * `[a-z0-9.-]` folded to `-`, runs collapsed, ends trimmed to alphanumerics.
@@ -123,19 +339,50 @@ export const AGENT_PLUGINS_SCHEMA_VERSION = '1.0.0';
 export const PLUGIN_MANIFEST_SCHEMA = `https://agent-plugins.org/schemas/${AGENT_PLUGINS_SCHEMA_VERSION}/plugin.schema.json`;
 export const PLUGIN_MCP_SCHEMA = `https://agent-plugins.org/schemas/${AGENT_PLUGINS_SCHEMA_VERSION}/mcp.schema.json`;
 /**
- * A minimal, valid `plugin.json` for a plugin folder.
- *
- * Deliberately only the two required fields. `version`, `license` and the rest
- * are optional metadata about a DISTRIBUTED package, and inventing values for a
- * folder someone just made in the app would be asserting things nobody said —
- * a plugin here is a place a team keeps skills, not something published.
- *
- * The display name is the folder, which is why nothing here carries one: the
- * manifest's `name` is constrained to a lowercase slug, and the field set is
- * closed, so there is no conformant home for "Sales" other than an extension.
+ * The Agent Plugins `name`: a kebab-case identifier — lowercase letters and
+ * digits in hyphen-separated runs, nothing else. It is the plugin's IDENTITY:
+ * what the marketplace publishes it as, what the access principals are
+ * spelled from (`plugin/<name>/<verb>`), what the catalog and the URLs key
+ * on. `pluginManifestName` folds any spelling into one of these.
+ */
+export const PLUGIN_IDENTIFIER_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isPluginIdentifier(name) {
+    return typeof name === 'string' && PLUGIN_IDENTIFIER_RE.test(name);
+}
+/**
+ * The identity of a plugin folder: the manifest's `name` when it IS an
+ * identifier, else the folder name folded into one. A manifest naming
+ * something that cannot be an identifier is not silently reinterpreted; the
+ * folder stands in, and discovery says so.
+ */
+export function pluginIdentityOf(manifest, folderName) {
+    const declared = manifest?.name;
+    return isPluginIdentifier(declared) ? declared : pluginManifestName(folderName);
+}
+/**
+ * What a person sees the plugin called: the manifest's `displayName` (the
+ * vendor field Claude Code shows in its picker; any casing, spaces allowed),
+ * else the folder name — which is what every plugin made before this field
+ * existed was called, so nothing renames itself on upgrade.
+ */
+export function pluginDisplayNameOf(manifest, folderName) {
+    const declared = manifest?.displayName;
+    return typeof declared === 'string' && declared.trim() ? declared.trim() : folderName;
+}
+/**
+ * A minimal, valid `plugin.json` for a plugin folder: the identifier the
+ * folder name folds into, and — when the folder is spelled differently — the
+ * folder's spelling as `displayName`, so a client's picker shows "Sales
+ * Team" for `sales-team`. Nothing else: `version`, `license` and the rest
+ * are metadata about a DISTRIBUTED package, and inventing values for a
+ * folder someone just made in the app would be asserting things nobody said.
  */
 export function renderPluginManifest(folderName) {
-    return `${JSON.stringify({ $schema: PLUGIN_MANIFEST_SCHEMA, name: pluginManifestName(folderName) }, null, 2)}\n`;
+    const name = pluginManifestName(folderName);
+    const manifest = { $schema: PLUGIN_MANIFEST_SCHEMA, name };
+    if (folderName !== name)
+        manifest.displayName = folderName;
+    return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 /**
  * The reserved name prefix marking a personal folder under `Plugins/` —
@@ -164,6 +411,17 @@ export function personalPluginFolderName(userId) {
 export function isPersonalPluginFolder(folderName) {
     return folderName.startsWith(PERSONAL_PLUGIN_PREFIX);
 }
+/**
+ * THE structural rule for a personal shelf: a repo-relative folder that is a
+ * DIRECT child of the plugins root and carries the personal prefix. A deeper
+ * folder so named is just a name, and a plugin whose manifest name happens
+ * to start with the prefix is a plugin — discovery, the principal picker and
+ * the item pages all ask this one question of the FOLDER.
+ */
+export function isPersonalPluginDir(repoRelDir) {
+    const segments = repoRelDir.split('/').filter(Boolean);
+    return segments.length === 2 && segments[0] === PLUGINS_DIR && isPersonalPluginFolder(segments[1]);
+}
 /**
  * The plugin a repo-root-relative path belongs to, or `null` for content that
  * sits outside any plugin.
@@ -199,8 +457,19 @@ export const PIPELINES_DIR = 'Pipelines';
 /**
  * The roots whose subfolders are discovered as ontologies by the graph parser
  * (each subfolder with both `NodeTypes/` and `Knowledge/` is an ontology).
+ * A function, not a constant: `KNOWLEDGE_BASE_DIR` is configurable, and a
+ * module-scope array would snapshot the default before configuration.
+ */
+export function ontologyRoots() {
+    return [KNOWLEDGE_BASE_DIR, DATA_DIR];
+}
+/**
+ * Every reserved root name, as currently configured — the set the file tree
+ * renders as its own sections rather than folding into Knowledge.
  */
-export const ONTOLOGY_ROOTS = [KNOWLEDGE_BASE_DIR, DATA_DIR];
+export function reservedRootDirNames() {
+    return new Set([KNOWLEDGE_BASE_DIR, SKILLS_DIR, PLUGINS_DIR, DATA_DIR, AGENTS_DIR, PIPELINES_DIR]);
+}
 /** The `Knowledge/` marker subfolder of an ontology (holds the graph nodes). */
 export const KNOWLEDGE_DIR = 'Knowledge';
 /** The `NodeTypes/` marker subfolder of an ontology (holds the type definitions). */

package/dist/workspace/kb-layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"kb-layout.js","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kb-layout.js","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-shared",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Shared types and pure domain utilities of the Bevel core platform (auth, workspace, git/workflow contracts, branch registry).",
   "type": "module",
   "main": "./dist/index.js",

package/src/git/types.ts

@@ -68,9 +68,21 @@ export interface ValidationReport {
   rawOutput: string;
 }
 
+/** What `IGitService.syncFromRemote` observed under its one hold of the clone. */
+export interface RemoteSyncPullResult {
+  /** HEAD before the pull; null when the clone had no commits yet. */
+  before: string | null;
+  /** HEAD after the pull; null only when origin is still empty too. */
+  after: string | null;
+  /** Whether the working tree's CONTENT differs — tree ids, not commit ids. */
+  treeChanged: boolean;
+  /** Repo-relative paths whose content changed; empty unless `treeChanged`. */
+  changedPaths: string[];
+}
+
 export interface IGitService {
   status(workspaceId: string): Promise<WorkingTreeStatus>;
-  listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<BranchInfo[]>;
+  listBranches(workspaceId: string, opts?: { freshFetch?: boolean; strictFetch?: boolean }): Promise<BranchInfo[]>;
   createBranch(
     workspaceId: string,
     name: string,
@@ -129,7 +141,39 @@ export interface IGitService {
     },
   ): Promise<void>;
   fetch(workspaceId: string): Promise<void>;
-  pull(workspaceId: string): Promise<void>;
+  /**
+   * `treeChanged` is whether the pull left the working tree holding different
+   * CONTENT than before the call — tree ids compared, not commit ids, so a
+   * pull that only moves HEAD across content-identical commits (an empty
+   * commit, a rebase that replays to the same result) reports false. Only the
+   * pull itself can answer that (it holds the workspace mutex across the
+   * rebase; any before/after probe a caller ran around it would race), and
+   * callers that announce "this tree changed" to the rest of the process need
+   * the distinction: an "already up to date" pull that broadcast anyway would
+   * drop every catalog cache and reload every attached browser for nothing.
+   */
+  pull(workspaceId: string): Promise<{ treeChanged: boolean }>;
+  /**
+   * The remote sync's pull, observed as ONE serialized operation: where HEAD
+   * was, the pull, where HEAD is, and which repo-relative paths changed
+   * (rename-aware: both ends). `pull` bracketed by separate reads would let a
+   * concurrent save land between them and be announced as the sync's own.
+   *
+   * Tolerant of an unborn HEAD (a clone of an empty upstream): `before` is
+   * null, and paths are diffed against the empty tree. Throws the typed
+   * pull-conflict error like `pull`, and a typed "remote branch gone" error
+   * when origin no longer has the branch — including for an unborn clone,
+   * once origin has any branch at all. The one exception: an unborn clone
+   * against an origin with NO branches (a fresh deployment nobody has pushed
+   * to) resolves to `after: null`, since there is nothing to sync and nothing
+   * stale.
+   */
+  syncFromRemote(workspaceId: string): Promise<RemoteSyncPullResult>;
+  /**
+   * Whether origin still has `branch` right now (`ls-remote`). Used to
+   * revalidate that a clone is still stale before it is retired.
+   */
+  remoteBranchExists(workspaceId: string, branch: string): Promise<boolean>;
   diffStat(workspaceId: string, base?: string): Promise<string[]>;
   /**
    * Paths in the working tree that the next commit would include — the set

package/src/workflow/events.ts

@@ -132,6 +132,13 @@ export interface GitSyncFailedEvent {
   branch: string;
   /** Sanitised git error — safe to display, tokens already redacted. */
   reason: string;
+  /**
+   * Present when the failure is a REMOTE-SYNC CONFLICT (`POST /api/sync`
+   * found Hexis-side commits that contradict what landed on the host): the
+   * repo-relative files a person has to reconcile. Unlike a failing push,
+   * this is the author's to act on, so the banner offers to open them.
+   */
+  conflictedPaths?: string[];
 }
 
 /**

package/src/workflow/interface.ts

@@ -21,6 +21,7 @@ import type { AuthUser } from '../auth/types.js';
 import type {
   AcquireLockResult,
   Branch,
+  BranchSyncOutcome,
   BranchWorkspaceStatus,
   CancelChangeRequestResult,
   Change,
@@ -40,11 +41,18 @@ import type {
 export interface IWorkflowService {
   // ── Branches ──────────────────────────────────────────────────────────────
 
-  listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<Branch[]>;
+  /**
+   * `freshFetch` bypasses the fetch TTL; `strictFetch` makes a failed fetch
+   * throw instead of serving the stale refs — for a caller that uses the
+   * list to prove a branch ABSENT (a stale list proves nothing).
+   */
+  listBranches(workspaceId: string, opts?: { freshFetch?: boolean; strictFetch?: boolean }): Promise<Branch[]>;
   /**
    * Create a new unprotected branch. Protected branches cannot be created
    * via the workflow — the protected set is bootstrapped from the KB repo's
-   * initial state and never grown at runtime.
+   * initial state and never grown at runtime. Holds the branch-lifecycle
+   * lock for `name`, so creation is serialised with the branch's deletion
+   * and with the retirement of a stale clone under that name.
    */
   createBranch(workspaceId: string, name: string, fromBase?: string): Promise<Branch>;
   /**
@@ -101,6 +109,31 @@ export interface IWorkflowService {
    * `user` when provided (falls back to the recovery bot).
    */
   updateFromRemote(workspaceId: string, user?: AuthUser): Promise<void>;
+  /**
+   * The remote-sync step for ONE branch's clone, driven by a git host's
+   * webhook or a pipeline rather than by a person's save. Pulls with the same
+   * rebase-and-autostash `updateFromRemote` uses and, when HEAD moved,
+   * announces the new tree (`fs-tree-changed`, one `file-changed` per path)
+   * so open browsers, agents and the catalogues see it at once.
+   *
+   * On a conflict it does what `updateFromRemote` does — the divergence goes
+   * to the same background recovery ladder (attributed to the recovery bot,
+   * since no person triggered the sync) — and, because that is not resolved
+   * at request time, reports it as a `conflict` outcome naming the files, so
+   * the caller can fail and a person can step in if recovery does not clear
+   * it. Never throws for a per-branch failure; every failure is an outcome.
+   */
+  syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome>;
+  /**
+   * Retire the clone of a branch the host has deleted (a `remote-gone`
+   * outcome). Runs under the branch-lifecycle lock — the one `createBranch`
+   * and `deleteBranch` hold, so no Hexis operation can recreate the branch
+   * while the clone is examined and removed — revalidates against origin
+   * first, and backs off while a clone of the branch is being bootstrapped.
+   * A branch recreated in the meantime therefore keeps its clone. Returns
+   * whether the clone was removed.
+   */
+  retireRemoteGoneClone(workspaceId: string): Promise<boolean>;
   /**
    * Hard-reset the workspace's checked-out branch to `origin/<branch>` (fetch
    * first), discarding any local divergence. Break-glass primitive for

package/src/workflow/types.ts

@@ -163,3 +163,30 @@ export interface OpenChangeRequestInput {
 export type MergeChangeRequestOutcome =
   | { kind: 'merged'; result: MergeChangeRequestResult }
   | { kind: 'conflicts-need-resolution'; conflictedPaths: string[] };
+
+/**
+ * What a remote sync did to one branch's clone. One entry per branch in the
+ * `POST /api/sync` response, so a pipeline can read exactly which branch
+ * moved, which was already current, and which needs a person.
+ *
+ *  - `updated`     — the clone moved from `from` (null when it had no commits
+ *                    yet) to `to`.
+ *  - `up-to-date`  — origin had nothing new; `to` is the unchanged HEAD.
+ *  - `not-cloned`  — Hexis has no clone of this branch, so there is nothing
+ *                    to refresh (the first visit clones it fresh).
+ *  - `remote-gone` — the branch no longer exists on the host; the stale clone
+ *                    is removed. Not a failure: a deleted branch has nothing
+ *                    to sync.
+ *  - `conflict`    — Hexis-side commits contradict what landed on the host.
+ *                    The clone is untouched; `error` is the message to show
+ *                    and `conflictedPaths` the files a person must reconcile.
+ *  - `error`       — the pull failed for another reason (origin unreachable,
+ *                    credential refused); `error` is the sanitised message.
+ */
+export type BranchSyncOutcome =
+  | { branch: string; outcome: 'updated'; from: string | null; to: string }
+  | { branch: string; outcome: 'up-to-date'; to: string }
+  | { branch: string; outcome: 'not-cloned' }
+  | { branch: string; outcome: 'remote-gone' }
+  | { branch: string; outcome: 'conflict'; conflictedPaths: string[]; error: string }
+  | { branch: string; outcome: 'error'; error: string };

package/src/workspace/filename.ts

@@ -23,9 +23,13 @@ const WINDOWS_RESERVED_NAMES = new Set([
 
 /** Characters Windows forbids in any filename component. `/` is the path
  *  separator on Unix, included for the same reason. `\` is also a path
- *  separator on Windows. Control chars (0x00–0x1F) are rejected separately. */
+ *  separator on Windows. Control characters are rejected with them: NUL and
+ *  0x01–0x1F because Windows refuses them, and DEL (0x7F) — which every
+ *  filesystem would write — as a matter of hygiene: a name carrying a
+ *  character nobody can see or type is not a name people can share, and the
+ *  knowledge-base root names are validated by this same rule. */
 // eslint-disable-next-line no-control-regex
-const FORBIDDEN_CHARS = /[<>:"/\\|?*\x00-\x1F]/;
+const FORBIDDEN_CHARS = /[<>:"/\\|?*\x00-\x1F\x7F]/;
 
 /** Per-component byte limit: NTFS = 255 UTF-16 units, ext4 = 255 bytes,
  *  APFS = 255 UTF-8 bytes. Use UTF-8 bytes — the strictest of the three. */
@@ -45,7 +49,7 @@ export function validateFilename(name: string): string | null {
   if (name === '.' || name === '..') return 'Name cannot be "." or ".."';
 
   if (FORBIDDEN_CHARS.test(name)) {
-    return 'Name cannot contain any of these characters: < > : " / \\ | ? *';
+    return 'Name cannot contain control characters or any of: < > : " / \\ | ? *';
   }
 
   // Windows trims trailing dots and spaces silently — a name ending in either