@bevel-software/platform-core-backend 0.31.0 → 0.33.0

package/src/modules/workspace/kb-repository.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { logger } from '../../shared/logging.js';
-import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
+import type { GitRunError} from '../../shared/git.contract.js';
+import { type IGitRunner } from '../../shared/git.contract.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import type { AddWorktreeOptions, FetchOptions, IKbRepository } from './kb-repository.contract.js';
@@ -12,7 +13,7 @@ import {
   cloneTrackingConfigArgs,
   ORIGIN_FETCH_REFSPEC,
   SAFE_IMPLICIT_FETCH_ARGS,
-} from '../kb-fs/clone-config.js';
+} from '../kb-fs/index.js';
 
 const log = logger('kb-repository');
 

package/src/modules/workspace/not-found.ts

@@ -1,4 +1,4 @@
-import { ToolError } from '../tool-helpers/tool.contract.js';
+import { ToolError } from '../tool-helpers/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { NOT_FOUND_NEXT_STEP, PathNotFoundError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';

package/src/modules/workspace/pattern-matcher.contract.ts

@@ -1,4 +1,4 @@
-import { ToolError } from '../tool-helpers/tool.contract.js';
+import { ToolError } from '../tool-helpers/index.js';
 
 /**
  * The contract for running a CALLER'S regular expression: what `grep` (REST,

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

@@ -15,7 +15,7 @@
  * The executor sets the restriction before streaming and clears it after.
  */
 
-import { ToolError } from '../tool-helpers/tool.contract.js';
+import { ToolError } from '../tool-helpers/index.js';
 
 export interface IRoutineWritePolicy {
   /**

package/src/modules/workspace/startup/kb-git.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { cloneCredentialArgs, credentialHelperValue } from '../../kb-fs/clone-config.js';
+import { cloneCredentialArgs, credentialHelperValue } from '../../kb-fs/index.js';
 import { GitRunError, type IGitRunner } from '../../../shared/git.contract.js';
 import { ClassifiedFailure, classifyGitFailure } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -19,12 +19,11 @@ import {
   type GitFailureKind,
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
-import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
+import { normalizeRepositoryAddress, sameRepository, assertValidBranchName } from '../../kb-fs/index.js';
 import { setAsideClone, setAsideRepository, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
 import { workingCopyShape, type WorkingCopyShape } from '../kb-repository.js';
 import type { FetchOptions, IKbRepository } from '../kb-repository.contract.js';
 import { fetchInstant } from '../fetch-instant.js';
-import { assertValidBranchName } from '../../kb-fs/branch-name.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in

package/src/modules/workspace/startup/steps/groups-to-plugins.step.ts

@@ -11,9 +11,9 @@ import {
   PLUGIN_SKILLS_DIR,
   renderPluginManifest,
 } from '@bevel-software/platform-shared';
-import type { ToolManualDescriptor } from '../../../tool-manuals/tool-manuals.contract.js';
-import { normalizeToolManual } from '../../../tool-manuals/tool-manuals.service.js';
-import { parseOwnAccessEntries } from '../../../access-model/access-grammar.js';
+import type { ToolManualDescriptor } from '../../../tool-manuals/index.js';
+import { normalizeToolManual } from '../../../tool-manuals/index.js';
+import { parseOwnAccessEntries } from '../../../access-model/index.js';
 import { containsVariableReference } from '../../../../shared/variable-refs.js';
 import { IGNORE_FILENAME, isAbsence, isSkippedEntry, type IFsProbe, type ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';

package/src/modules/workspace/startup/steps/personal-spaces.step.ts

@@ -11,8 +11,8 @@ import {
   sourceVerbsFor,
   type ParsedEntry,
   type Verb,
-} from '../../../access-model/access-grammar.js';
-import { spliceGrant } from '../../../access-model/access-splice.js';
+} from '../../../access-model/index.js';
+import { spliceGrant } from '../../../access-model/index.js';
 import { isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 

package/src/modules/workspace/startup/steps/plugin-layout.ts

@@ -4,7 +4,7 @@ import {
   PLUGIN_MCP_FILE,
   PLUGIN_SKILLS_DIR,
 } from '@bevel-software/platform-shared';
-import { BUNDLE_FILE } from '../../../plugins/discovery/bundle-dialect/bundle.source.js';
+import { BUNDLE_FILE } from '../../../plugins/index.js';
 import { isSkippedEntry, type ITreeWalker, type WalkedEntry } from '../../../../shared/fs.contract.js';
 
 /**

package/src/modules/workspace/startup/steps/roles-yaml.step.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import type { IFsProbe } from '../../../../shared/fs.contract.js';
-import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../access-model/index.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 
 /**

package/src/modules/workspace/startup/steps/seed-tree.ts

@@ -2,12 +2,12 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { IFsProbe, ITreeWalker } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
-import { renderRolesYaml } from '../../../access-model/render-roles-yaml.js';
+import { renderRolesYaml } from '../../../access-model/index.js';
 import { reservedRootDirs } from './template-files.step.js';
 import { TEMPLATE_SOURCE_FALLBACKS, TemplateSource, renderTemplateText } from './template-source.js';
 import { assertNotGitInternals, hasGitInternalsSegment } from '../../../../shared/git-internals.js';
 import { GitInternalsError } from '../../../../shared/domain-errors.js';
-import { isManagedGuide } from '../../../agent-guide/agent-guide.js';
+import { isManagedGuide } from '../../../agent-guide/index.js';
 import { utf8Text } from '../../../../shared/utf8-text.js';
 
 /**

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

@@ -7,8 +7,8 @@ import {
 } from '@bevel-software/platform-shared';
 import { IGNORE_FILENAME, isAbsence, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
-import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
-import { isManagedGuide } from '../../../agent-guide/agent-guide.js';
+import { PREAMBLE_FILE } from '../../../agent-instructions/index.js';
+import { isManagedGuide } from '../../../agent-guide/index.js';
 import { TemplateSource } from './template-source.js';
 import type { KbBranch, OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 import { hasGitInternalsSegment } from '../../../../shared/git-internals.js';

package/src/modules/workspace/startup/steps/template-source.ts

@@ -3,8 +3,8 @@ import { gitignoreLiteral, renderKbLayoutPlaceholders, type KbLayout } from '@be
 import { IGNORE_FILENAME, isAbsence, type EntryStat, type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
 
-import { PREAMBLE_FILE } from '../../../agent-instructions/compose.js';
-import { sharedFileRulesSection } from '../../../agent-instructions/shared-file-rules.js';
+import { PREAMBLE_FILE } from '../../../agent-instructions/index.js';
+import { sharedFileRulesSection } from '../../../agent-instructions/index.js';
 import { defaultKbTemplateDir } from '../../../../assets.js';
 import { logger } from '../../../../shared/logging.js';
 

package/src/modules/workspace/worker-pool.ts

@@ -0,0 +1,193 @@
+import type { Worker } from 'node:worker_threads';
+
+/**
+ * The pooled worker threads that keep CPU-bound work off the request thread:
+ * the mechanics every worker kind shares, whatever its worker runs. Two kinds
+ * use it today, each with a pool of its own — the regex matcher `grep` runs a
+ * caller's pattern in (`bounded-matcher.ts`) and the document extractor every
+ * office, PDF and email extraction runs in (`file-readers/extract-in-worker.ts`).
+ *
+ * What a kind brings is how to start its worker; what the pool owns is the
+ * rest: at most `poolMax` workers, a capped queue of jobs waiting for one,
+ * idle workers that never hold a process's exit open, a worker that dies (or
+ * is discarded over its budget) leaving the pool and being replaced for the
+ * next waiting job, and `close()`, which ends them all.
+ *
+ * The owner of a pool is its kind's instance, and the owner of that is the
+ * composition root, which closes it when the graph stops (`lifecycle.ts`), so
+ * no worker outlives what it served.
+ */
+export interface WorkerPoolSizing {
+  /** Workers kept at once; a job past this waits for one to free up. */
+  poolMax: number;
+  /** Jobs that may wait for a worker at once; past it `acquire` refuses with the kind's busy error. */
+  maxWaiting: number;
+}
+
+type Waiter = { resolve: (w: Worker) => void; reject: (err: Error) => void };
+
+export class WorkerPool {
+  private readonly idle: Worker[] = [];
+  private readonly all = new Set<Worker>();
+  private readonly waiting: Waiter[] = [];
+  private closed = false;
+
+  constructor(
+    /** Starts one worker of this pool's kind. */
+    private readonly spawnWorker: () => Worker,
+    private readonly sizing: WorkerPoolSizing,
+    /** The kind's answer for "no worker now, and no room to wait for one" (and for any job after `close`). */
+    private readonly busy: () => Error,
+  ) {}
+
+  /** A worker for one job, given back with `release` — or, when it must not be reused, `discard`. */
+  async acquire(): Promise<Worker> {
+    if (this.closed) throw this.busy();
+    if (this.idle.length === 0 && this.all.size >= this.sizing.poolMax && this.waiting.length >= this.sizing.maxWaiting) {
+      throw this.busy();
+    }
+    const w =
+      this.idle.pop() ??
+      (this.all.size < this.sizing.poolMax
+        ? this.spawn()
+        : await new Promise<Worker>((resolve, reject) => this.waiting.push({ resolve, reject })));
+    w.ref();
+    return w;
+  }
+
+  /**
+   * A worker that has run no job yet, for a job that must not share a thread
+   * with any other job's leftovers. With the pool full, the worker `acquire`
+   * hands over (idle, or freed by another job after waiting in the same queue)
+   * is swapped for a new one in its own place, so the pool never holds more
+   * than `poolMax`.
+   */
+  async acquireFresh(): Promise<Worker> {
+    if (this.closed) throw this.busy();
+    if (this.all.size < this.sizing.poolMax) {
+      const w = this.spawn();
+      w.ref();
+      return w;
+    }
+    return this.swap(await this.acquire());
+  }
+
+  /** A worker whose job ended cleanly goes to the next waiting job, or idles. */
+  release(w: Worker): void {
+    const next = this.waiting.shift();
+    if (next) return next.resolve(w);
+    // An idle worker must not hold a process's exit open.
+    w.unref();
+    this.idle.push(w);
+  }
+
+  /**
+   * A worker that must not run another job — over its budget, or left in a
+   * state its job cannot vouch for — is terminated. Terminating is what stops
+   * a thread mid-computation. It leaves the pool at once, and a fresh worker
+   * goes to the next waiting job.
+   */
+  discard(w: Worker): void {
+    this.leave(w);
+    void w.terminate();
+  }
+
+  /** Ends every worker; a job waiting, or asking after this, is answered busy. */
+  async close(): Promise<void> {
+    this.closed = true;
+    for (const waiter of this.waiting.splice(0)) waiter.reject(this.busy());
+    const workers = [...this.all];
+    this.idle.length = 0;
+    await Promise.all(workers.map((w) => w.terminate()));
+  }
+
+  /**
+   * Terminates `w`, a worker held by the caller, and gives its place straight
+   * to a new one — not to the next waiting job, as `discard` does, which would
+   * leave the new worker one past `poolMax`.
+   */
+  private swap(w: Worker): Worker {
+    this.all.delete(w);
+    void w.terminate();
+    if (this.closed) throw this.busy();
+    const fresh = this.spawn();
+    fresh.ref();
+    return fresh;
+  }
+
+  private spawn(): Worker {
+    const w = this.spawnWorker();
+    this.all.add(w);
+    // A worker that dies — out of memory, or ending itself — leaves the pool.
+    w.once('exit', () => this.leave(w));
+    return w;
+  }
+
+  /** Takes `w` out of the pool, once, and hands its place to the next waiting job. */
+  private leave(w: Worker): void {
+    if (!this.all.delete(w)) return;
+    const at = this.idle.indexOf(w);
+    if (at >= 0) this.idle.splice(at, 1);
+    if (this.closed) return;
+    const next = this.waiting.shift();
+    if (next) next.resolve(this.spawn());
+  }
+}
+
+/**
+ * How one message to a worker ended: its reply; the timeout, with the worker
+ * still running (the caller decides whether to discard it); an error the
+ * worker raised and did not catch; or the worker's exit before it answered.
+ */
+export type Exchange<R> = { reply: R } | { timeout: true } | { error: Error } | { exited: number };
+
+/**
+ * Post `message` to `w` and wait at most `timeoutMs` for its one reply.
+ * `transfer` hands buffers over without copying them on this thread. Never
+ * rejects: every way the exchange can end is an {@link Exchange} the caller
+ * maps to its own answer, and every listener it adds is removed however it
+ * ends.
+ */
+export function exchange<R>(
+  w: Worker,
+  message: unknown,
+  timeoutMs: number,
+  transfer: readonly ArrayBuffer[] = [],
+): Promise<Exchange<R>> {
+  return new Promise((resolve) => {
+    const settle = (outcome: Exchange<R>) => {
+      clearTimeout(timer);
+      w.off('message', onMessage);
+      w.off('error', onError);
+      w.off('exit', onExit);
+      resolve(outcome);
+    };
+    const onMessage = (reply: R) => settle({ reply });
+    const onError = (error: Error) => settle({ error });
+    const onExit = (code: number) => settle({ exited: code });
+    const timer = setTimeout(() => settle({ timeout: true }), timeoutMs);
+    w.on('message', onMessage);
+    w.on('error', onError);
+    w.on('exit', onExit);
+    try {
+      w.postMessage(message, transfer as ArrayBuffer[]);
+    } catch (err) {
+      // A message that cannot be cloned is this exchange's error, not a throw.
+      settle({ error: err instanceof Error ? err : new Error(String(err)) });
+    }
+  });
+}
+
+/**
+ * The longest delay `setTimeout` honours. A longer one fires after 1 ms, so a
+ * budget past this would stop every job at once.
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
+
+/** A sizing option as given, refused at construction unless it is an integer from `min` to `max`. */
+export function sizingOption(owner: string, name: string, value: number, min: number, max = Number.MAX_SAFE_INTEGER): number {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new RangeError(`${owner}: ${name} must be an integer from ${min} to ${max}, got ${value}.`);
+  }
+  return value;
+}

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

@@ -5,7 +5,7 @@ const log = logger('workspace.routes');
 import path from 'node:path';
 import { IGNORE_FILENAME, isAbsence, type ITreeWalker } from '../../shared/fs.contract.js';
 import { printable } from '../../shared/printable.js';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IAdminAccessService } from '../admin/index.js';
 import express from 'express';
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import {
@@ -22,25 +22,22 @@ import {
   platformFolderRefusal,
   reservedRootDirNames,
 } from '@bevel-software/platform-shared';
-import { FolderTooLargeError, type ReadTreeFilter } from './workspace.service.js';
+import { FolderTooLargeError, type ReadTreeFilter, EntryExistsError, type WorkspaceService } from './workspace.service.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import { EntryExistsError, type WorkspaceService } from './workspace.service.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { canReadWorkspacePath, resolveReadableMap, toKbRelative } from '../access-model/kb-read-filter.js';
-import type { ICreatorAccess } from '../access-model/creator.js';
-import type { IChangeReadGate } from '../access-model/change-gate.js';
-import { isRolesYamlPath, assertRolesYamlParsable } from '../access-model/roles-yaml-guard.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthService } from '../auth/index.js';
+import type { IAccessControl } from '../access/index.js';
+import { canReadWorkspacePath, resolveReadableMap, toKbRelative, isRolesYamlPath, assertRolesYamlParsable } from '../access-model/index.js';
+import type { ICreatorAccess, IChangeReadGate } from '../access-model/index.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
 import { PathTraversalError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
-import { normalizeWorkspacePath } from '../kb-fs/repo-path.js';
+import { normalizeWorkspacePath } from '../kb-fs/index.js';
 import { hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { createGitInternalsRouteGuard } from './git-internals.middleware.js';
 import { removeEmptyDirs } from './empty-dirs.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 import type { SkillSaveCheck } from './workspace.tools.js';
 import { MAX_UPLOAD_BYTES } from './upload-limits.js';
 import { OCTET_STREAM, rawExtensionOf, rawMimeFor } from './file-readers/raw-mime.js';

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

@@ -15,7 +15,7 @@ import {
   type ExistingEntryKind,
 } from '@bevel-software/platform-shared';
 import { isAbsence, type IgnoreRules, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
-import { BevelIgnoreStack } from '../kb-fs/bevel-ignore.js';
+import { BevelIgnoreStack, assertRepoRootNameFree, normalizeWorkspacePath, assertValidBranchName, normalizeRepositoryAddress, sameRepository } from '../kb-fs/index.js';
 import {
   DestinationTakenError,
   inspectDestination,
@@ -23,9 +23,8 @@ import {
 } from '../../shared/rename-no-replace.js';
 import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
-import { assertRepoRootNameFree, normalizeWorkspacePath } from '../kb-fs/repo-path.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { isZipNoiseEntry, readZipEntry, zipEntryName, zipEntryNameRefusal, zipEntrySegments } from './zip-entry-rules.js';
 import {
@@ -42,8 +41,6 @@ import {
   WorkflowDomainError,
   isMissingRemoteBranchFailure,
 } from '../../shared/domain-errors.js';
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
-import { normalizeRepositoryAddress, sameRepository } from '../kb-fs/remote-url.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { setAsideClone, setAsideRepository, setAsideRootFor, setAsideStamp } from './set-aside-clone.js';
 import { workingCopyShape } from './kb-repository.js';
@@ -53,8 +50,8 @@ import {
   credentialHelperValue,
   cloneTrackingConfigArgs,
   SAFE_IMPLICIT_FETCH_ARGS,
-} from '../kb-fs/clone-config.js';
-import type { IDiffService } from '../diff/diff.interface.js';
+} from '../kb-fs/index.js';
+import type { IDiffService } from '../diff/index.js';
 
 /** One held path turn: the settled tail of the nested mutations launched inside it. */
 interface HeldTurn {

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

@@ -3,9 +3,8 @@ import { join } from 'node:path';
 import AdmZip from 'adm-zip';
 import type { Router, RequestHandler } from 'express';
 import type { LocalFilesystem } from '@mastra/core/workspace';
-import type { IToolRegistry, JsonSchema } from '../tool-registry/tool.contract.js';
-import { hasHttpStatus, ToolError, type ToolContext, type ToolHandler } from '../tool-helpers/tool.contract.js';
-import { BRANCH_INPUT, toolDef } from '../tool-helpers/tool-def.js';
+import type { IToolRegistry, JsonSchema } from '../tool-registry/index.js';
+import { hasHttpStatus, ToolError, type ToolContext, type ToolHandler, BRANCH_INPUT, toolDef, CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts } from '../tool-helpers/index.js';
 import {
   notifyAgentRead,
   assertAgentWriteAllowed,
@@ -13,9 +12,8 @@ import {
   type AgentAccessGate,
 } from './agent-access.gate.js';
 import type { IRoutineWritePolicy } from './routine-write-policy.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
-import { CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts } from '../tool-helpers/index.js';
-import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
+import type { ToolHandlerFactory } from '../tool-helpers/index.js';
+import { requireInternalSource, requireExternalSource } from '../tool-auth/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
@@ -27,19 +25,17 @@ import {
   isInsideRepo,
   normalizePathArgs,
   normalizeWorkspacePath,
-} from '../kb-fs/repo-path.js';
-import { GitGuardedFilesystem } from '../kb-fs/git-guarded-filesystem.js';
+} from '../kb-fs/index.js';
+import { GitGuardedFilesystem, MoveLockedError, MoveRacedError, type LockingFilesystem } from '../kb-fs/index.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
-import { isRolesYamlPath } from '../access-model/roles-yaml-guard.js';
+import { isRolesYamlPath, toKbRelative, resolveReadableMap, AccessDeniedError } from '../access-model/index.js';
 import type { ISessionSink } from './session-sink.js';
 import { isAbsence, type ITreeWalker } from '../../shared/fs.contract.js';
-import type { AccessDecisionSource, AccessTargetKind, IAccessControl } from '../access/access-control.interface.js';
-import { accessRoster, resolveAccessView } from '../access/access-view.js';
-import { accessMdPathForFolder, fileCarriesAccessRules, governingFolderOf } from '../access/access-mutation.service.js';
-import { toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
+import type { AccessDecisionSource, AccessTargetKind, IAccessControl } from '../access/index.js';
+import { accessRoster, resolveAccessView, accessMdPathForFolder, fileCarriesAccessRules, governingFolderOf } from '../access/index.js';
 import type { SpillStore } from './spill-store.js';
 import type { DocExtractService } from './file-readers/doc-extract.service.js';
-import { displayPath, type FileKind, type FileReaderRegistry, type ReadResult } from './file-readers/file-reader.js';
+import { displayPath, type FileKind, type FileReaderRegistry, type ReadOrigin, type ReadResult } from './file-readers/file-reader.js';
 import { fileTypeOf, needsContent } from './file-readers/content-mode.js';
 import { createFileReaderRegistry } from './file-readers/file-reader.registry.js';
 import { DocumentReader } from './file-readers/document-reader.js';
@@ -59,26 +55,25 @@ import {
   type ExistingEntryKind,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import { AccessDeniedError } from '../access-model/access-errors.js';
 import {
   AGENT_GUIDE_FILE,
   isAgentGuidePath,
   isManagedGuide,
   withPlatformGuideAppended,
   type AgentGuideReader,
-} from '../agent-guide/agent-guide.js';
+} from '../agent-guide/index.js';
 import { removeEmptyDirs } from './empty-dirs.js';
 import { endsTheSearch, type IPatternMatcher, type IPatternSearch } from './pattern-matcher.contract.js';
 import { FIRST_RUN_SECTION_ID, firstRunNote, knowledgeFolderIsNew, type FirstRunStarterSource } from './first-run.js';
 import { planMoveLinks } from './move-links.js';
-import { MoveLockedError, MoveRacedError, type LockingFilesystem } from '../kb-fs/locking-filesystem.js';
 import { rethrowAsWriteDenial } from './write-denial.js';
-import type { IChangeReadGate } from '../access-model/change-gate.js';
+import type { IChangeReadGate } from '../access-model/index.js';
 import { notFound, orDeclaredNotFound, orNotFound } from './not-found.js';
 import { logger } from '../../shared/logging.js';
 import { printable } from '../../shared/printable.js';
 import { DestinationTakenError, inspectDestination } from '../../shared/rename-no-replace.js';
-import { AgentUploadStore, type ClaimedUpload } from './agent-upload.store.js';
+import type { AgentUploadStore} from './agent-upload.store.js';
+import { type ClaimedUpload } from './agent-upload.store.js';
 import type { IAgentDownloadStore } from './agent-download.store.js';
 import { buildDownload } from './agent-download.builder.js';
 import { DOWNLOAD_MAX_FILES, ZIP_DOWNLOAD_MAX_BYTES } from './workspace.service.js';
@@ -311,6 +306,8 @@ const UNCACHED_DOCS_PER_GREP = 20;
 /** Per-grep-walk extraction state: the shared budget + how many documents it left unsearched. */
 interface DocGrepState {
   readers: FileReaderRegistry;
+  /** The workspace searched — where a document that fails to extract during the walk is reported. */
+  origin: ReadOrigin;
   uncachedBudget: number;
   skippedUncached: number;
 }
@@ -651,7 +648,7 @@ function modeOf(a: Record<string, unknown>): WriteMode {
 type FileGrepOutcome =
   /** Its text was searched; any matches are in `out`. */
   | 'searched'
-  /** No searchable text at all: an image, binary content, a corrupt document. */
+  /** No searchable text at all: an image, binary content, a corrupt document (remembered or fresh). */
   | 'no-text'
   /** A cold document the per-call extraction budget could not afford (counted in `docs`). */
   | 'budget-skipped';
@@ -680,19 +677,26 @@ async function grepOneFile(
 ): Promise<FileGrepOutcome> {
   const reader = docs.readers.readerFor(path);
   const bytes = asBytes(await fs.readFile(path));
-  let content = reader.greppableText ? await reader.greppableText(bytes, path) : null;
-  if (content === null && reader instanceof DocumentReader) {
-    // Cold document (extraction not yet cached): cached ones above are free,
-    // extracting draws on the per-walk budget (see UNCACHED_DOCS_PER_GREP) —
-    // beyond it the search skips the document and counts it.
-    if (docs.uncachedBudget <= 0) {
-      docs.skippedUncached++;
-      return 'budget-skipped';
+  let content: string | null;
+  if (reader instanceof DocumentReader) {
+    // What the cache remembers is free — an extraction is searched, a failure
+    // (a damaged file, or one that overran its budget within the hour) is
+    // skipped without extracting it again. A cold document draws on the
+    // per-walk budget (see UNCACHED_DOCS_PER_GREP) — beyond it the search
+    // skips the document and counts it.
+    let res = await reader.cachedRead(bytes, path);
+    if (res === undefined) {
+      if (docs.uncachedBudget <= 0) {
+        docs.skippedUncached++;
+        return 'budget-skipped';
+      }
+      docs.uncachedBudget--;
+      res = await reader.read(bytes, path, docs.origin);
     }
-    docs.uncachedBudget--;
-    const res = await reader.read(bytes, path);
-    // A non-text outcome is a corrupt document — nothing searchable.
+    // A non-text outcome is a document that could not be read — nothing searchable.
     content = res.kind === 'text' ? res.text : null;
+  } else {
+    content = reader.greppableText ? await reader.greppableText(bytes, path) : null;
   }
   if (content === null) return 'no-text';
   const lines = content.split('\n');
@@ -1878,7 +1882,7 @@ export function registerWorkspaceTools(
     // the access gate and the read hook above — a document read is still a
     // KB read. ONE registry dispatch picks the reader by extension.
     const bytes = await orNotFound(p, async () => asBytes(await fs.readFile(p)));
-    return { result: await readers.readerFor(p).read(bytes, p), guide: null };
+    return { result: await readers.readerFor(p).read(bytes, p, { workspaceId: workspaceIdForBranch(branch) }), guide: null };
   };
 
   /**
@@ -2228,6 +2232,7 @@ export function registerWorkspaceTools(
           description: 'Files only: where `mime` came from. `fallback` means no type was detected.',
         },
         textEditable: { type: 'boolean', description: 'Files only: whether write_file/write_files/edit_file accept this file as it is now.' },
+        unreadable: str('Documents only, and only when its text could not be extracted: the one-line notice read_file answers for it.'),
         mimeNote: str('Present when `mimeSource` is `fallback`: says the MIME type is a fallback, not a detected type.'),
         platformGuide: {
           type: 'boolean',
@@ -2382,7 +2387,16 @@ export function registerWorkspaceTools(
       const bytes = needsContent(reader)
         ? await orNotFound(p, async () => asBytes(await fs.readFile(p)))
         : undefined;
-      return { ...out, ...fileTypeOf(reader, p, bytes) };
+      // A document whose extraction failed answers that failure's notice here
+      // too, from what the cache remembers — never by extracting, so stat
+      // stays as cheap as it was. The notice quotes the parser, so only a
+      // caller who may read the file hears it.
+      const type = fileTypeOf(reader, p, bytes);
+      if (reader instanceof DocumentReader && verdicts.read) {
+        const remembered = await reader.cachedRead(await orNotFound(p, async () => asBytes(await fs.readFile(p))), p);
+        if (remembered?.kind === 'refusal') return { ...out, ...type, unreadable: remembered.message };
+      }
+      return { ...out, ...type };
     },
   });
 
@@ -2445,7 +2459,12 @@ export function registerWorkspaceTools(
         const gate = readGateFor(a.branch as string, ctx);
         const out: { path: string; line: number; text: string }[] = [];
         const max = typeof a.max_results === 'number' ? Math.min(a.max_results, 1000) : 200;
-        const docs: DocGrepState = { readers, uncachedBudget: UNCACHED_DOCS_PER_GREP, skippedUncached: 0 };
+        const docs: DocGrepState = {
+          readers,
+          origin: { workspaceId: workspaceIdForBranch(a.branch as string) },
+          uncachedBudget: UNCACHED_DOCS_PER_GREP,
+          skippedUncached: 0,
+        };
         // The empty root is the workspace itself — always a directory, and never
         // worth a stat.
         // A placeholder named on its own is searched as what it is to every

package/src/modules/workspace/write-denial.ts

@@ -1,10 +1,9 @@
 import { branchAuthorLocalpart, suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import { ToolError } from '../tool-helpers/tool.contract.js';
-import { AccessDeniedError } from '../access-model/access-errors.js';
-import type { IChangeReadGate } from '../access-model/change-gate.js';
-import { toKbRelative } from '../access-model/kb-read-filter.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import { ToolError } from '../tool-helpers/index.js';
+import { AccessDeniedError, toKbRelative } from '../access-model/index.js';
+import type { IChangeReadGate } from '../access-model/index.js';
+import type { IAccessControl } from '../access/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 
 /** One step of the proposal route, named by the tool the agent calls. */