@bevel-software/platform-core-backend 0.1.0

package/src/modules/workspace/kb-seed.service.ts

@@ -0,0 +1,361 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import {
+  AGENTS_DIR,
+  DATA_DIR,
+  KNOWLEDGE_BASE_DIR,
+  PIPELINES_DIR,
+  SKILLS_DIR,
+  TOOLS_DIR,
+} from '@bevel-software/platform-shared';
+import type { IKbSeedService } from './kb-seed.interface.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Fallback committer identity for seed commits. Mirrors the workspace clone's
+ * bot identity so seed commits attribute to the same bot in `git log`.
+ */
+const BOT_NAME = 'Bevel Workflow';
+const BOT_EMAIL = 'bevel-workflow@bevel.software';
+
+/**
+ * The **required scaffolding** — the minimum an operational KB needs. When a
+ * branch is loaded, any of these that are missing are added to it; the sample
+ * ontology is NOT (it only seeds a fully-empty repo).
+ *
+ * Two kinds:
+ *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
+ *  - {@link REQUIRED_DIRS}: well-known root dirs the app expects to exist; when a
+ *    dir is entirely absent it's created by adding its `<dir>/.gitkeep`. Keyed on
+ *    the *directory's* existence, not the `.gitkeep` file — so a branch that
+ *    already has content under `KnowledgeBase/` never gets a pointless placeholder.
+ *
+ * `roles.yaml` is in neither, and is not part of the template at all: it is
+ * generated from `SEED_ADMIN_EMAILS` (see {@link renderRolesYaml}) and written
+ * directly, so a repo can't be seeded with a stale hard-coded Admin list.
+ */
+const REQUIRED_FILES: readonly string[] = ['access.md', 'CLAUDE.md', '.bevelignore', '.gitignore'];
+const REQUIRED_DIRS: readonly string[] = [
+  KNOWLEDGE_BASE_DIR,
+  DATA_DIR,
+  AGENTS_DIR,
+  PIPELINES_DIR,
+  SKILLS_DIR,
+  TOOLS_DIR,
+];
+
+/** Redact the token from any string that might surface in a log or error. */
+function redact(s: string): string {
+  const token = process.env.GITHUB_TOKEN;
+  return token ? s.replaceAll(token, '***') : s;
+}
+
+/** Generate `roles.yaml` granting Admin to each seed email. */
+function renderRolesYaml(adminEmails: readonly string[]): string {
+  const lines = adminEmails.map((e) => `    - ${e}`).join('\n');
+  return (
+    '# Identity → role mapping for access control.\n' +
+    '# Role names are case- and whitespace-insensitive. The `Admin` role is special:\n' +
+    '# only Admins may edit this file, and at least one Admin must always exist.\n' +
+    '#\n' +
+    '# Generated by the Bevel platform at KB-seed time from SEED_ADMIN_EMAILS.\n' +
+    'roles:\n' +
+    '  Admin:\n' +
+    `${lines}\n`
+  );
+}
+
+/**
+ * Seeds/tops-up the KB *remote* so the rest of the app's assumption — that the
+ * repo it clones already carries the protected branches and base scaffolding —
+ * holds even for a brand-new or partially-populated GitHub repo. The template
+ * ships inside the platform (`kb-template/`); this reads from it.
+ *
+ * Split into two moments so the file-level top-up rides along with the clone the
+ * app already performs, rather than doing its own extra clones:
+ *  - {@link ensureRemoteSeeded} runs once before the first clone (an empty remote
+ *    can't be `clone -b`'d): it seeds an empty repo and makes sure every
+ *    protected branch *exists* as a ref.
+ *  - {@link topUpWorkspace} runs on the freshly-cloned workspace of whatever
+ *    branch a user loads: it fills in any missing base files on that branch.
+ */
+export class KbSeedService implements IKbSeedService {
+  /** Single-flight: the first caller runs the remote pass; the rest await its result. */
+  private inFlight: Promise<void> | null = null;
+
+  /**
+   * @param kbRepoUrl        Clone/push URL of the KB remote.
+   * @param kbTemplateDir    Filesystem path to the `kb-template/` seed source.
+   * @param protectedBranches Branch names that must exist (e.g. current/target-company-state).
+   * @param defaultBranch    The branch new checkouts land on — used as the init
+   *                         branch of the empty-seed commit and the preferred
+   *                         base when creating a missing protected branch.
+   * @param seedAdminEmails  Admins written into the generated `roles.yaml`.
+   * @param gitUsername      Basic-auth username for git-over-HTTPS (provider-specific).
+   */
+  constructor(
+    private readonly kbRepoUrl: string,
+    private readonly kbTemplateDir: string,
+    private readonly protectedBranches: readonly string[],
+    private readonly defaultBranch: string,
+    private readonly seedAdminEmails: readonly string[],
+    private readonly gitUsername: string = 'x-access-token',
+  ) {}
+
+  ensureRemoteSeeded(): Promise<void> {
+    // Cache the promise, not just a boolean, so concurrent first-callers share
+    // one run. On failure we clear it so a later call can retry (a transient
+    // network blip on ls-remote shouldn't wedge seeding for the whole process).
+    if (!this.inFlight) {
+      this.inFlight = this.run().catch((err) => {
+        this.inFlight = null;
+        throw err;
+      });
+    }
+    return this.inFlight;
+  }
+
+  private async run(): Promise<void> {
+    const heads = await this.lsRemoteHeads();
+
+    if (heads.size === 0) {
+      if (this.seedAdminEmails.length === 0) {
+        throw new Error(
+          `KB remote ${redact(this.kbRepoUrl)} is empty and cannot be seeded: ` +
+            'set SEED_ADMIN_EMAILS to the initial Admin email(s). A seeded KB with ' +
+            'no Admin is unusable (access resolution requires at least one Admin).',
+        );
+      }
+      await this.seedEmptyRemote();
+      return;
+    }
+
+    // Non-empty remote: make sure every protected branch exists as a ref so a
+    // later `clone -b <branch>` succeeds. This creates the branch pointer only;
+    // per-branch file top-up happens in `topUpWorkspace` when the branch loads.
+    const base = this.pickBase(heads);
+    for (const branch of this.protectedBranches) {
+      if (!heads.has(branch)) {
+        await this.createBranchOnRemote(branch, base);
+      }
+    }
+  }
+
+  /**
+   * Add any missing base scaffolding to an already-cloned workspace of `branch`,
+   * then commit + push it. Called once per fresh clone (any branch a user loads),
+   * so the check reuses the clone the app already made instead of a dedicated one.
+   *
+   * Best-effort: never throws. If the push is rejected (e.g. a concurrent update
+   * to the branch), the local scaffolding commit is rolled back so the workspace
+   * stays consistent with origin, and the top-up is retried on a future clone.
+   */
+  async topUpWorkspace(repoDir: string, branch: string): Promise<void> {
+    try {
+      const added: string[] = [];
+      for (const rel of REQUIRED_FILES) {
+        if (!(await this.exists(path.join(repoDir, rel)))) {
+          await this.copyTemplateFile(rel, repoDir);
+          added.push(rel);
+        }
+      }
+      for (const rootDir of REQUIRED_DIRS) {
+        if (!(await this.exists(path.join(repoDir, rootDir)))) {
+          const keep = `${rootDir}/.gitkeep`;
+          await this.copyTemplateFile(keep, repoDir);
+          added.push(keep);
+        }
+      }
+      if (!(await this.exists(path.join(repoDir, 'roles.yaml')))) {
+        if (this.seedAdminEmails.length > 0) {
+          await fs.writeFile(
+            path.join(repoDir, 'roles.yaml'),
+            renderRolesYaml(this.seedAdminEmails),
+            'utf8',
+          );
+          added.push('roles.yaml');
+        } else {
+          console.warn(
+            `[kb-seed] Branch "${branch}" is missing roles.yaml but SEED_ADMIN_EMAILS ` +
+              'is unset — leaving it absent. Access resolution will fail until an ' +
+              'Admin roles.yaml exists; set SEED_ADMIN_EMAILS or add roles.yaml manually.',
+          );
+        }
+      }
+
+      if (added.length === 0) return; // already fully scaffolded → no-op
+
+      // Stamp the bot identity so the commit has an author even if the clone
+      // wasn't configured with one (the workspace clone already sets the same
+      // values, so this is a harmless no-op there).
+      await this.stampIdentity(repoDir);
+      await this.git(repoDir, ['add', '--', ...added]);
+      await this.git(repoDir, ['commit', '-m', `Add missing KB scaffolding: ${added.join(', ')}`]);
+      try {
+        await this.git(repoDir, ['push', 'origin', `HEAD:refs/heads/${branch}`]);
+        console.log(`[kb-seed] Topped up "${branch}" with: ${added.join(', ')}`);
+      } catch (err) {
+        // Roll the local branch back to origin so the workspace never sits ahead
+        // of the remote (which would confuse the workflow git layer). The files
+        // simply aren't present this session; a later fresh clone retries.
+        console.warn(
+          `[kb-seed] Could not push scaffolding to "${branch}", rolling back local commit:`,
+          err instanceof Error ? redact(err.message) : String(err),
+        );
+        await this.git(repoDir, ['reset', '--hard', `origin/${branch}`]).catch(() => {});
+      }
+    } catch (err) {
+      // Top-up is best-effort infrastructure — a failure here must not block the
+      // user from loading the branch.
+      console.warn(
+        `[kb-seed] Scaffolding top-up for "${branch}" failed (non-fatal):`,
+        err instanceof Error ? redact(err.message) : String(err),
+      );
+    }
+  }
+
+  /** Prefer the default branch as a base, else the first protected branch present, else any head. */
+  private pickBase(heads: Set<string>): string {
+    if (heads.has(this.defaultBranch)) return this.defaultBranch;
+    const protectedPresent = this.protectedBranches.find((b) => heads.has(b));
+    if (protectedPresent) return protectedPresent;
+    // Deterministic pick so repeated runs behave identically.
+    return [...heads].sort()[0];
+  }
+
+  /** `-c` args that inject credentials + longpaths, mirroring the workspace clone. */
+  private credArgs(): string[] {
+    const args = ['-c', 'core.longpaths=true'];
+    const token = process.env.GITHUB_TOKEN;
+    if (token) {
+      // The helper reads GITHUB_TOKEN at runtime, so the value never appears in argv.
+      // Username is provider-specific; the token is always the Basic-auth password.
+      args.push(
+        '-c',
+        `credential.helper=!f() { echo "username=${this.gitUsername}"; echo "password=$GITHUB_TOKEN"; }; f`,
+      );
+    }
+    return args;
+  }
+
+  private async git(cwd: string | null, args: string[]): Promise<string> {
+    try {
+      const { stdout } = await execFileAsync('git', args, {
+        cwd: cwd ?? undefined,
+        env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+        maxBuffer: 32 * 1024 * 1024,
+      });
+      return stdout.toString();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      let i = 0;
+      while (i < args.length && args[i] === '-c') i += 2;
+      throw new Error(`git ${args[i] ?? args[0]} failed: ${redact(msg)}`);
+    }
+  }
+
+  /** Set of branch names on the remote (empty ⇒ uninitialised repo). */
+  private async lsRemoteHeads(): Promise<Set<string>> {
+    const out = await this.git(null, [...this.credArgs(), 'ls-remote', '--heads', this.kbRepoUrl]);
+    const heads = new Set<string>();
+    for (const line of out.split('\n')) {
+      const m = line.match(/\srefs\/heads\/(.+)$/);
+      if (m) heads.add(m[1].trim());
+    }
+    return heads;
+  }
+
+  /** Run a block against a throwaway temp dir, always cleaned up. */
+  private async withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-seed-'));
+    try {
+      return await fn(dir);
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  private async stampIdentity(repo: string): Promise<void> {
+    await this.git(repo, ['config', 'user.name', BOT_NAME]);
+    await this.git(repo, ['config', 'user.email', BOT_EMAIL]);
+  }
+
+  /** Copy the entire template tree into `dest` (roles.yaml isn't in it — it's generated). */
+  private async copyTemplateTree(dest: string): Promise<void> {
+    const walk = async (relDir: string): Promise<void> => {
+      const abs = path.join(this.kbTemplateDir, relDir);
+      const entries = await fs.readdir(abs, { withFileTypes: true });
+      for (const entry of entries) {
+        const rel = relDir ? path.join(relDir, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+          await walk(rel);
+        } else {
+          await this.copyTemplateFile(rel, dest);
+        }
+      }
+    };
+    await walk('');
+  }
+
+  /** Copy one template file (by repo-relative path) into `dest`, creating parents. */
+  private async copyTemplateFile(relPath: string, dest: string): Promise<void> {
+    const from = path.join(this.kbTemplateDir, relPath);
+    const to = path.join(dest, relPath);
+    await fs.mkdir(path.dirname(to), { recursive: true });
+    await fs.copyFile(from, to);
+  }
+
+  /** `git init` a temp repo, lay down the full template + generated roles.yaml, commit. */
+  private async buildSeedCommit(dir: string): Promise<void> {
+    await this.git(dir, ['init', '-b', this.defaultBranch]);
+    await this.stampIdentity(dir);
+    await this.copyTemplateTree(dir);
+    await fs.writeFile(path.join(dir, 'roles.yaml'), renderRolesYaml(this.seedAdminEmails), 'utf8');
+    await this.git(dir, ['add', '-A']);
+    await this.git(dir, ['commit', '-m', 'Seed knowledge base from Bevel template']);
+  }
+
+  /** Empty remote → one seed commit pushed to every protected branch. */
+  private async seedEmptyRemote(): Promise<void> {
+    await this.withTempDir(async (dir) => {
+      await this.buildSeedCommit(dir);
+      // Point every protected branch at the seed commit. The init branch is
+      // already `defaultBranch`; create the rest as refs to HEAD.
+      for (const branch of this.protectedBranches) {
+        if (branch !== this.defaultBranch) {
+          await this.git(dir, ['branch', branch]);
+        }
+      }
+      await this.git(dir, ['remote', 'add', 'origin', this.kbRepoUrl]);
+      // Push only the protected branches — never the stray init branch if it
+      // isn't itself protected.
+      await this.git(dir, [...this.credArgs(), 'push', '-u', 'origin', ...this.protectedBranches]);
+      console.log(
+        `[kb-seed] Seeded empty KB remote with branches: ${this.protectedBranches.join(', ')}`,
+      );
+    });
+  }
+
+  /** Create a missing protected branch on the remote, pointed at `base`'s tip. */
+  private async createBranchOnRemote(branch: string, base: string): Promise<void> {
+    await this.withTempDir(async (dir) => {
+      await this.git(dir, [...this.credArgs(), 'clone', '--depth', '1', '-b', base, this.kbRepoUrl, dir]);
+      // Push base's fetched tip up under the new branch name.
+      await this.git(dir, [...this.credArgs(), 'push', 'origin', `HEAD:refs/heads/${branch}`]);
+      console.log(`[kb-seed] Created missing protected branch "${branch}" from "${base}"`);
+    });
+  }
+
+  private async exists(p: string): Promise<boolean> {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/modules/workspace/routine-write-policy.ts

@@ -0,0 +1,79 @@
+/**
+ * Per-run write restriction for background/routine agents.
+ *
+ * The ontology-session gate ({@link ../workflow/session-ontology.service}) bounds
+ * WHICH ontology a run may write; this narrower gate bounds WHAT KIND of file a
+ * run may write, by extension. It exists for the `watchlist_check` routine, which is
+ * allowed to refresh dashboard views (`.html`) but must never touch the
+ * knowledge-graph nodes (`.md`) or any other file — a hard, code-level guarantee
+ * rather than a prompt request (a prompt-only rule has already proven insufficient).
+ *
+ * Keyed by the agent run's `sessionId` (the background agent passes its run id as
+ * the session id, which the internal token then carries onto every loopback tool
+ * call as `ctx.sessionId`). A restriction lives only for the duration of one
+ * in-process run, so the store is a plain in-memory map — no durability needed,
+ * unlike the ontology touched-set which must survive restarts and span the MCP
+ * proxy. The executor sets the restriction before streaming and clears it after.
+ */
+
+import { ToolError } from '../tool-helpers/tool.contract.js';
+
+export interface IRoutineWritePolicy {
+  /**
+   * Confine a session's writes to the given file extensions (each including the
+   * leading dot, e.g. `['.html', '.htm']`). Overwrites any prior restriction for
+   * the session. A session with no restriction is unrestricted (the default for
+   * chat + `ontology_ingest` runs).
+   */
+  restrictToExtensions(sessionId: string, extensions: readonly string[]): void;
+  /** Drop a session's restriction (called at run end). */
+  clear(sessionId: string): void;
+  /**
+   * Throw a 403 `ToolError` when the session is restricted and `wsPath`'s
+   * extension is not on its allow-list. No session id, or no active restriction,
+   * always passes — so this is a no-op for every non-restricted caller.
+   */
+  assertPathWritable(sessionId: string | undefined, wsPath: string): void;
+  /**
+   * Throw a 403 `ToolError` when the session is restricted at all — for write
+   * tools with no single target path to check (arbitrary shell), which a
+   * restricted run must not be able to use as a write bypass.
+   */
+  assertUnrestricted(sessionId: string | undefined): void;
+}
+
+export class RoutineWritePolicyService implements IRoutineWritePolicy {
+  /** sessionId → allowed lowercased extensions. Absent = unrestricted. */
+  private readonly restrictions = new Map<string, Set<string>>();
+
+  restrictToExtensions(sessionId: string, extensions: readonly string[]): void {
+    this.restrictions.set(sessionId, new Set(extensions.map((e) => e.toLowerCase())));
+  }
+
+  clear(sessionId: string): void {
+    this.restrictions.delete(sessionId);
+  }
+
+  assertPathWritable(sessionId: string | undefined, wsPath: string): void {
+    const allowed = sessionId ? this.restrictions.get(sessionId) : undefined;
+    if (!allowed) return;
+    const lower = wsPath.toLowerCase();
+    for (const ext of allowed) {
+      if (lower.endsWith(ext)) return;
+    }
+    throw new ToolError(
+      `This run may only write ${[...allowed].join(', ')} files (dashboard views); "${wsPath}" is blocked. ` +
+        'Knowledge-graph nodes and other files are read-only for this routine.',
+      403,
+    );
+  }
+
+  assertUnrestricted(sessionId: string | undefined): void {
+    if (sessionId && this.restrictions.has(sessionId)) {
+      throw new ToolError(
+        'This run is restricted to writing dashboard views only, so shell commands (which could write any file) are disabled.',
+        403,
+      );
+    }
+  }
+}

package/src/modules/workspace/session-ontology.gate.ts

@@ -0,0 +1,189 @@
+/**
+ * Ontology-session boundary — the per-call gate used by the agent tool handlers.
+ *
+ * One decision fn, called by every gated file/graph handler:
+ *   READS  (isWrite=false) record the touched ontology and always allow.
+ *   WRITES (isWrite=true)  run the registered BLOCKING `preWrite` hooks
+ *                          (`WorkflowHooks`), then record. The core registers
+ *                          no hook, so core alone only TRACKS; the enterprise
+ *                          overlay registers the ontology block (see
+ *                          `modules/kb/ontology-block.hook.ts`), restoring
+ *                          "allowed only while the session is confined to a
+ *                          single ontology; once it has touched ≥2, all
+ *                          writes are blocked".
+ *
+ * Skips entirely when: the flag is off, the path is neutral (`ontologyOf` →
+ * null), the caller is not an agent, or the caller is the recovery bot. Fails
+ * CLOSED for an agent named-path operation that carries no `sessionId`.
+ *
+ * Lives beside `assertCanRead` in the workspace tools — it does NOT touch
+ * `acquireLock` (that gate is protected-branch-only; this boundary applies on
+ * all branches and to reads). See `docs/rp4-ontology-boundary-plan-v2.md`.
+ */
+
+import { ontologyOf } from '../../shared/kb-layout.js';
+import type { JsonSchema } from '../tool-registry/tool.contract.js';
+import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
+import type { ISessionOntologyService } from '../workflow/session-ontology.service.js';
+import type { WorkflowHooks } from '../workflow/workflow-hooks.js';
+
+/**
+ * The `sessionId` input the ontology-session boundary reads: the agent run /
+ * conversation id. The in-process agent supplies its thread id automatically
+ * (via its per-run internal token); an external agent has no ambient run id,
+ * so it must first mint one with the `start_session` tool and then pass it
+ * EXPLICITLY on every gated call — the MCP proxy is a pure passthrough and
+ * never injects args.
+ */
+export const SESSION_ID_INPUT: JsonSchema = {
+  type: 'string',
+  description:
+    'The KnowledgeBase session id that scopes this run to one ontology. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here on EVERY gated call. The in-process agent runtime supplies this automatically (do not set it yourself).',
+};
+
+/**
+ * Boundary warning appended to ontology-gated tool descriptions so the agent
+ * knows the restriction before it calls one. Action-then-why phrasing per
+ * docs/glossary.md.
+ */
+export const ONTOLOGY_BOUNDARY_NOTE =
+  ' Stay within one KnowledgeBase ontology per conversation: once this run has read or written files in two different ontologies, every later content write (write_file/edit_file/mkdir/unzip, and both endpoints of move_file/copy_file) is blocked with a 403 and no override. Reads and delete_file never block — but each one records the ontology it touched and can poison a later content write, so do broad cross-ontology exploration only when you do not intend to write. Note move_file/copy_file are blocked outright when source and destination are different ontologies, since they would carry content across.';
+
+/** Thrown when a write is refused because the session has crossed ontologies. */
+export class OntologyWriteBlockedError extends ToolError {
+  constructor(touched: string[], attempted: string, reason: 'multi-ontology' | 'different-ontology') {
+    const msg =
+      reason === 'multi-ontology'
+        ? `This conversation has already read across multiple ontologies (${touched.join(', ')}), so writing is no longer allowed. Start a new conversation to write to "${attempted}".`
+        : `This conversation is working in ${touched.join(', ')}, so it can't write to a different ontology ("${attempted}"). Start a new conversation to work in "${attempted}".`;
+    super(msg, 403);
+    this.name = 'OntologyWriteBlockedError';
+  }
+}
+
+/** Thrown when an agent op on a named ontology carries no session id (fail closed). */
+export class MissingSessionError extends ToolError {
+  constructor() {
+    super(
+      'This operation needs a KnowledgeBase session id and none was provided. Call the `start_session` tool once at the start of your work to obtain a sessionId, then pass it explicitly as `sessionId` on every gated call (direct MCP calls and `call_tool_chain` alike).',
+      403,
+    );
+    this.name = 'MissingSessionError';
+  }
+}
+
+export interface SessionOntologyGate {
+  service: ISessionOntologyService;
+  enabled: boolean;
+  kbDirName: string;
+  /** Lowercased email of the recovery/merge bot, which is exempt. */
+  recoveryBotEmail: string;
+  /**
+   * The workflow lifecycle-hook registry whose BLOCKING `preWrite` hooks
+   * decide whether a gated write/shell op proceeds. Core registers none (the
+   * gate then only tracks); the enterprise composition root registers the
+   * ontology block against `workflowService.hooks` — pass that same instance
+   * here.
+   */
+  hooks: WorkflowHooks;
+}
+
+/** Only internal/external agent callers are gated; `session` (browser JWT) and humans are not. */
+function isAgentSource(ctx: ToolContext): boolean {
+  return ctx.source === 'internal' || ctx.source === 'external';
+}
+
+/**
+ * Shared gate preamble for the two per-path operations below. Returns `'skip'`
+ * when the boundary doesn't apply to this call (flag off, neutral path,
+ * non-agent caller, or recovery bot), otherwise the session id to evaluate
+ * against — throwing `MissingSessionError` (fail closed) when an agent op on a
+ * named ontology carries none.
+ */
+function resolveGatedSession(gate: SessionOntologyGate, ctx: ToolContext, wsPath: string): string | 'skip' {
+  if (!gate.enabled) return 'skip';
+  // Neutral paths never pin/record/block — skip before any identity work.
+  if (ontologyOf(wsPath, gate.kbDirName) === null) return 'skip';
+  // Humans (UI routes) and browser-JWT callers never hit these tools; only
+  // agent tool calls are gated.
+  if (!isAgentSource(ctx)) return 'skip';
+  // The recovery/merge bot legitimately spans ontologies — exempt by identity.
+  if (ctx.user.email.toLowerCase() === gate.recoveryBotEmail) return 'skip';
+  // Fail closed: an agent operation on a named ontology must carry a session id.
+  if (!ctx.sessionId) throw new MissingSessionError();
+  return ctx.sessionId;
+}
+
+/**
+ * Record a read of `wsPath`'s ontology into the session's touched set. Reads are
+ * always allowed — recording is the only effect — but each one widens the
+ * touched set and so can poison a later write (see {@link assertOntologyWriteAllowed}).
+ * Fails closed (`MissingSessionError`) for an agent read of a named ontology
+ * with no session id.
+ */
+export async function recordOntologyRead(gate: SessionOntologyGate, ctx: ToolContext, wsPath: string): Promise<void> {
+  const sessionId = resolveGatedSession(gate, ctx, wsPath);
+  if (sessionId === 'skip') return;
+  // checkOperation(isWrite=false) records the touch and always allows.
+  await gate.service.checkOperation(sessionId, wsPath, false, gate.kbDirName);
+}
+
+/**
+ * Assert a write to `wsPath` is allowed, then record it. A write that would
+ * carry information into a second ontology is the thing the boundary blocks:
+ * permitted only while the session stays confined to the target ontology, and
+ * refused with `OntologyWriteBlockedError` once it has touched ≥2. Note `delete`
+ * is NOT a write here — removing a node propagates no cross-ontology
+ * information, so it goes through {@link recordOntologyRead}.
+ *
+ * The BLOCKING decision itself lives behind the `preWrite` hooks: the
+ * enterprise-registered ontology block evaluates-and-records atomically via
+ * `checkOperation(isWrite=true)` and throws to refuse (identical behavior to
+ * the previous in-gate decision). Core registers no hook, so with none the
+ * write is allowed and only the touch is recorded (tracking stays core). The
+ * follow-up read-record after the hooks is idempotent — a no-op when a hook
+ * already recorded the allowed write.
+ */
+export async function assertOntologyWriteAllowed(
+  gate: SessionOntologyGate,
+  ctx: ToolContext,
+  wsPath: string,
+): Promise<void> {
+  const sessionId = resolveGatedSession(gate, ctx, wsPath);
+  if (sessionId === 'skip') return;
+  await gate.hooks.runPreWrite({ kind: 'file-write', sessionId, wsPath });
+  // Tracking stays core: record the (now-allowed) write's ontology touch.
+  // A blocked write never reaches this line, so it records nothing — same as
+  // before the hook split.
+  await gate.service.checkOperation(sessionId, wsPath, false, gate.kbDirName);
+}
+
+/**
+ * Session-level write-eligibility gate for write-capable tools that have no
+ * single resolvable target path to check per-call — currently `execute_command`
+ * (arbitrary shell). Such a tool cannot be path-confined, so we enforce the
+ * boundary at the coarser session level: once the run has crossed into ≥2
+ * ontologies (the point at which EVERY path-checked write is already refused),
+ * we refuse the tool outright, so shell can't become a write path around the
+ * boundary. A fresh or single-ontology session is still allowed; a residual gap
+ * remains (a single-ontology session could shell-write a *different* ontology),
+ * accepted because arbitrary shell cannot be path-confined and blocking all
+ * shell after one KB read would gut its read-style diagnostic use (git/grep/ls).
+ *
+ * Skips when: the flag is off, the caller is not an agent, the caller is the
+ * recovery bot, or there is no session id — there is no named path here to fail
+ * closed on, and with no session there is no touched set to evaluate.
+ *
+ * Like {@link assertOntologyWriteAllowed}, the refusal itself is the
+ * enterprise-registered `preWrite` hook's (it evaluates the touched set and
+ * throws); core registers none, so shell is never refused in a core-only
+ * deployment.
+ */
+export async function assertShellAllowedWithinOntology(gate: SessionOntologyGate, ctx: ToolContext): Promise<void> {
+  if (!gate.enabled) return;
+  if (!isAgentSource(ctx)) return;
+  if (ctx.user.email.toLowerCase() === gate.recoveryBotEmail) return;
+  if (!ctx.sessionId) return;
+
+  await gate.hooks.runPreWrite({ kind: 'shell', sessionId: ctx.sessionId });
+}

package/src/modules/workspace/session-sink.ts

@@ -0,0 +1,25 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Port behind `start_session` (workspace.tools.ts): mints the session id an
+ * external agent scopes its ontology boundary under. The workspace module owns
+ * the port; WHAT backs the id is the composition root's choice:
+ *
+ * - Core default ({@link UuidSessionSink}): a bare random id — sufficient for
+ *   the session-ontology gate, with no app-side session record.
+ * - The enterprise app substitutes a sink that mints a REAL chat thread, so the
+ *   same id also works end to end with `ask` (its sessionId IS a chat thread).
+ *   See the `start_session` comment in workspace.tools.ts for why that
+ *   unification matters.
+ */
+export interface ISessionSink {
+  /** Mint a session id for an external agent run started at `startedAt`. */
+  createSession(userId: string, startedAt: Date): Promise<{ sessionId: string }>;
+}
+
+/** Core default: a bare random id — no app-side session record. */
+export class UuidSessionSink implements ISessionSink {
+  async createSession(): Promise<{ sessionId: string }> {
+    return { sessionId: randomUUID() };
+  }
+}