@bevel-software/platform-core-backend 0.28.0 → 0.29.0

package/src/modules/workflow/file-lock.service.ts

@@ -23,6 +23,28 @@
  * never be keyed on a path no file verb would accept. See
  * `canonicalFileIdentity`.
  *
+ * Workspace identity works the same way. The lock routes pass the `:id`
+ * path param, which Express URL-decodes, so a slashed branch's workspace
+ * arrives as `alice/feature`; the deletion gate and the git status probe ask
+ * with the encoded `alice%2Ffeature`. Every method keys rows on
+ * `canonicalWorkspaceId`, so both spellings are one workspace and a held file
+ * is seen whichever spelling asks.
+ *
+ * Unlike raw path spellings (below), rows written under the decoded workspace id before this
+ * landed are still honoured until they go: every read, heartbeat and release
+ * also matches that spelling, and an acquire is refused while a live row
+ * under it holds the same file. Otherwise a lock held across the upgrade
+ * would be invisible for up to its TTL — to the deletion gate and to a second
+ * editor alike. Nothing new is ever written under it, so once the last such
+ * row has expired or been released the extra spelling matches nothing.
+ *
+ * This covers rows LEFT by the previous version, not rows it is still
+ * writing: a previous-version process never looks at a canonical row, so no
+ * check here could make the two contend while both run. They never do — one
+ * server process owns the workspaces directory (see `branchLifecycle` in the
+ * workflow service; this service's deletion gate is in-process for the same
+ * reason), and an upgrade stops the old process before the new one starts.
+ *
  * There is no transition handling for rows written under a raw spelling
  * before this landed: such a row is now unreachable by name and expires on
  * its own TTL. For one deploy an in-flight edit's lock can linger up to the
@@ -35,12 +57,13 @@
  * bounded by concurrent editors, not history, so lazy GC is fine.
  */
 
-import { and, eq, gt, lte } from 'drizzle-orm';
+import { and, eq, gt, inArray, lte } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { fileLocks } from '../database/schema.js';
 import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
+import { branchForWorkspaceId, canonicalWorkspaceId } from '../../shared/workspace-id.js';
 
 /**
  * Lock lifetime without a heartbeat. The client is expected to heartbeat
@@ -51,6 +74,17 @@ import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
  */
 const LOCK_TTL_MS = 60_000;
 
+/**
+ * The workspace ids a lock row of canonical workspace `workspaceId` can sit
+ * under: the canonical one every write uses, then — for a slashed branch —
+ * the decoded one rows were written under before workspace ids were
+ * canonicalised. See the module comment.
+ */
+function workspaceSpellings(workspaceId: string): string[] {
+  const legacy = branchForWorkspaceId(workspaceId);
+  return legacy === workspaceId ? [workspaceId] : [workspaceId, legacy];
+}
+
 function rowToFileLock(row: typeof fileLocks.$inferSelect): FileLock {
   return {
     branch: row.branch,
@@ -125,13 +159,14 @@ export class FileLockService {
    * (or vice versa).
    */
   async acquire(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
     user: AuthUser,
     opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     if (this.closing.has(branch)) {
       throw new WorkflowValidationError(`"${branch}" is being deleted, so "${targetPath}" cannot be held for editing.`, {
         kind: 'branch-being-deleted',
@@ -190,6 +225,25 @@ export class FileLockService {
     // `heartbeat()` (which has its own same-user UPDATE), and the
     // editor's save flow detects "I already hold it" via `getLock` in
     // `workspace.routes.withLock` rather than re-acquiring.
+    // A live row under the pre-canonical spelling holds this file as surely
+    // as one under the canonical id; the upsert below cannot see it.
+    const legacy = workspaceSpellings(workspaceId).slice(1);
+    if (legacy.length > 0) {
+      const [held] = await this.db
+        .select()
+        .from(fileLocks)
+        .where(
+          and(
+            inArray(fileLocks.workspaceId, legacy),
+            eq(fileLocks.branch, branch),
+            eq(fileLocks.path, targetPath),
+            gt(fileLocks.expiresAt, now),
+          ),
+        )
+        .limit(1);
+      if (held) return { acquired: false, lock: rowToFileLock(held) };
+    }
+
     const mode = opts?.coordination ? 'coordination' : 'edit';
     const upsertResult = await this.db
       .insert(fileLocks)
@@ -255,12 +309,13 @@ export class FileLockService {
    * current holder.
    */
   async heartbeat(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
     user: AuthUser,
   ): Promise<FileLock> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
     // The expiry guard (`expiresAt > now`) matters because an expired
@@ -279,7 +334,7 @@ export class FileLockService {
       .set({ lastHeartbeatAt: now, expiresAt })
       .where(
         and(
-          eq(fileLocks.workspaceId, workspaceId),
+          inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)),
           eq(fileLocks.branch, branch),
           eq(fileLocks.path, targetPath),
           eq(fileLocks.holderUserId, user.id),
@@ -302,17 +357,18 @@ export class FileLockService {
    * over by someone else — that's not an error from the caller's POV).
    */
   async release(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
     user: AuthUser,
   ): Promise<void> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     await this.db
       .delete(fileLocks)
       .where(
         and(
-          eq(fileLocks.workspaceId, workspaceId),
+          inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)),
           eq(fileLocks.branch, branch),
           eq(fileLocks.path, targetPath),
           eq(fileLocks.holderUserId, user.id),
@@ -326,25 +382,30 @@ export class FileLockService {
    * are purged here lazily.
    */
   async get(
-    workspaceId: string,
+    rawWorkspaceId: string,
     branch: string,
     rawPath: string,
   ): Promise<FileLock | null> {
     const targetPath = canonicalFileIdentity(rawPath);
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     const rows = await this.db
       .select()
       .from(fileLocks)
       .where(
         and(
-          eq(fileLocks.workspaceId, workspaceId),
+          inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)),
           eq(fileLocks.branch, branch),
           eq(fileLocks.path, targetPath),
         ),
-      )
-      .limit(1);
-    if (rows.length === 0) return null;
-    const row = rows[0];
-    if (row.expiresAt.getTime() <= Date.now()) {
+      );
+    // At most one row per spelling; the canonical one first.
+    rows.sort((x, y) => Number(x.workspaceId !== workspaceId) - Number(y.workspaceId !== workspaceId));
+    let live: (typeof rows)[number] | null = null;
+    for (const row of rows) {
+      if (row.expiresAt.getTime() > Date.now()) {
+        live ??= row;
+        continue;
+      }
       // Lazy GC — drop the stale row so the next `acquire` doesn't have
       // to bypass it. Bind the delete to this exact row's `expiresAt` so
       // a concurrent acquire that wrote a fresh row in the gap between
@@ -356,15 +417,14 @@ export class FileLockService {
         .delete(fileLocks)
         .where(
           and(
-            eq(fileLocks.workspaceId, workspaceId),
+            eq(fileLocks.workspaceId, row.workspaceId),
             eq(fileLocks.branch, branch),
             eq(fileLocks.path, targetPath),
             eq(fileLocks.expiresAt, row.expiresAt),
           ),
         );
-      return null;
     }
-    return rowToFileLock(row);
+    return live ? rowToFileLock(live) : null;
   }
 
   /**
@@ -406,11 +466,12 @@ export class FileLockService {
    * the "missed lock-release commit" the loud warning is for. Expired rows
    * don't count (their holder is gone; they explain nothing).
    */
-  async hasAnyActive(workspaceId: string): Promise<boolean> {
+  async hasAnyActive(rawWorkspaceId: string): Promise<boolean> {
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
     const rows = await this.db
       .select({ path: fileLocks.path })
       .from(fileLocks)
-      .where(and(eq(fileLocks.workspaceId, workspaceId), gt(fileLocks.expiresAt, new Date())))
+      .where(and(inArray(fileLocks.workspaceId, workspaceSpellings(workspaceId)), gt(fileLocks.expiresAt, new Date())))
       .limit(1);
     return rows.length > 0;
   }

package/src/modules/workflow/git/__tests__/git.service.readFileAtRef.test.ts

@@ -100,3 +100,45 @@ describe('GitService.readFileAtRef', () => {
     ).rejects.toThrow();
   });
 });
+
+describe('GitService.commitAtRef', () => {
+  let root: string;
+  const workspaceId = 'ws-commit-at-ref-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-commit-at-ref-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  function makeSvc(workspaceDir: string) {
+    return new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      new WorkflowHooks(),
+      testKbContext({ kbDirName: PROCESS_MAP_DIR }),
+    );
+  }
+
+  it('answers the commit a ref names, and null for a ref that names none', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const svc = makeSvc(workspaceDir);
+    // Unborn HEAD: a repository with no commit yet names none.
+    expect(await svc.commitAtRef(workspaceId, 'HEAD')).toBeNull();
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles: {}\n');
+    await runGit(repo, ['add', 'roles.yaml']);
+    await runGit(repo, ['commit', '-m', 'add roles']);
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repo });
+    expect(await svc.commitAtRef(workspaceId, 'HEAD')).toBe(stdout.trim());
+    expect(await svc.commitAtRef(workspaceId, 'origin/does-not-exist')).toBeNull();
+  });
+
+  it('THROWS on a failure that is not "names no commit", such as no repository there', async () => {
+    // The workspace folder exists; the clone inside it does not. Git fails
+    // with "not a git repository", which must not read as an empty one.
+    const workspaceDir = path.join(root, workspaceId);
+    await fs.mkdir(path.join(workspaceDir, PROCESS_MAP_DIR), { recursive: true });
+    const svc = makeSvc(workspaceDir);
+    await expect(svc.commitAtRef(workspaceId, 'HEAD')).rejects.toThrow();
+  });
+});

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

@@ -4017,6 +4017,29 @@ export class GitService implements IGitService {
     return stdout.split('\0').filter((line) => line.length > 0);
   }
 
+  /**
+   * The commit `ref` names right now, or null when it names none (an unborn
+   * `HEAD`, a ref that does not exist). A caller that reads several things
+   * "at HEAD" pins the commit once with this and asks each read at that
+   * commit, so a commit landing between the reads cannot hand it one
+   * snapshot's files with another's rules.
+   *
+   * Null is ONLY "names no commit": `rev-parse --verify --quiet` says that
+   * with exit status 1 and nothing on stderr. Any other failure — no
+   * repository there, git itself failing, a deadline — is thrown, so a
+   * caller cannot read a broken clone as an empty one.
+   */
+  async commitAtRef(workspaceId: string, ref: string): Promise<string | null> {
+    const cwd = await this.repoDir(workspaceId);
+    try {
+      const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+      return stdout.trim() || null;
+    } catch (err) {
+      if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1 && !(err.stderr ?? '').trim()) return null;
+      throw err;
+    }
+  }
+
   /**
    * A clean `git status` for a path has two honest readings (already
    * committed; a queued re-apply of something that landed) and one dishonest

package/src/modules/workflow/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the workflow module offers the other modules: the addresses of its
+ * change requests, so a module that lands a proposal can hand back a link
+ * built by the one rule — rather than each spelling the route for itself.
+ * The services are wired by the composition root.
+ */
+export { CHANGE_REQUEST_URL_NOTE, changeRequestLink, changeRequestLinkBase } from './git/change-request-link.js';

package/src/modules/workflow/pending-commits.service.ts

@@ -41,6 +41,7 @@ const log = logger('pending-commits');
 import type { Database } from '../database/connection.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import { pendingCommits } from '../database/schema.js';
+import { canonicalWorkspaceId } from '../../shared/workspace-id.js';
 
 /**
  * Transient-failure budget per recovery cycle. After this many consecutive
@@ -80,29 +81,9 @@ export const N_RECOVERY = 3;
  */
 export const BACKOFF_MS = [1_000, 5_000, 30_000];
 
-/**
- * Canonicalize a workspace id so an enqueued row and the worker's claim always
- * key on the SAME string.
- *
- * The id reaches `enqueue` via a route `:id` path param, which Express
- * URL-decodes — so a slashed feature branch arrives as `alice/feature`. But the
- * worker claims per `WorkspaceService.knownWorkspaces()`, whose ids are
- * `encodeURIComponent(branch)` → `alice%2Ffeature`. Those strings differ, so
- * `WHERE workspace_id = …` never matched and the row was never drained —
- * silently stranding every human save on a feature branch (protected branches
- * have no `/`, so encoded == decoded and they were unaffected).
- *
- * `encodeURIComponent(decodeURIComponent(id))` is idempotent and collapses both
- * forms to the encoded id `knownWorkspaces()` uses. A malformed `%` sequence
- * (which `decodeURIComponent` would throw on) is left untouched.
- */
-export function canonicalWorkspaceId(id: string): string {
-  try {
-    return encodeURIComponent(decodeURIComponent(id));
-  } catch {
-    return id;
-  }
-}
+// Lives in `shared/workspace-id.ts`, beside the encoding it canonicalises to;
+// re-exported for this module's existing importers.
+export { canonicalWorkspaceId };
 
 export interface PendingCommit {
   id: string;

package/src/modules/workflow/workflow.routes.ts

@@ -40,6 +40,7 @@ import type { WorkflowEventBus } from './event-bus.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { assertValidRelativePath } from '../kb-fs/branch-name.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
+import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 
 function toHttpError(
@@ -501,6 +502,8 @@ export function createWorkflowRoutes(
   // answer for that same input, and `toHttpError` passes it through unchanged.
   // Nothing is canonicalised at this layer on purpose: a route-level fix would
   // leave any other caller of the service coordinating on its own identity.
+  // (The status read canonicalises once for its read gate only; the lookup
+  // still takes the caller's spelling.)
 
   router.post('/workspace/:id/workflow/locks', async (req, res) => {
     const user = await requireUser(req, res);
@@ -589,7 +592,8 @@ export function createWorkflowRoutes(
   });
 
   router.get('/workspace/:id/workflow/locks', async (req, res) => {
-    if (!(await requireUser(req, res))) return;
+    const user = await requireUser(req, res);
+    if (!user) return;
     const branch = typeof req.query.branch === 'string' ? req.query.branch : '';
     const targetPath = typeof req.query.path === 'string' ? req.query.path : '';
     if (!branch || !targetPath) {
@@ -597,6 +601,25 @@ export function createWorkflowRoutes(
       return;
     }
     try {
+      // A lock names who is editing the file, so a caller who may not read
+      // the file is refused before the lookup: the answer is the same whether
+      // or not it is held. The gate judges the canonical spelling, which is
+      // the one the lock is found under (`./kb//x.md` would otherwise slip
+      // past the KB-prefix test), and a refused spelling keeps the file
+      // verbs' status. A path without the KB prefix is not exempted as
+      // non-KB: the git layer also takes the repo-relative form (`GTM/x.md`
+      // for `knowledge-base/GTM/x.md`, see `requireReadPermission`), so it is
+      // judged as the repository file it would name.
+      const canonical = canonicalFileIdentity(targetPath);
+      const readable = await accessControl.canRead(
+        req.params.id,
+        user.email,
+        toKbRelative(canonical, kbDirName) ?? canonical,
+      );
+      if (!readable) {
+        res.status(403).json({ error: `You don't have permission to read "${targetPath}".` });
+        return;
+      }
       res.json({ lock: await workflow.getLock(req.params.id, branch, targetPath) });
     } catch (err) {
       const { status, body } = toHttpError(err);

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

@@ -542,7 +542,7 @@ export class WorkflowService implements IWorkflowService {
     // One line per deletion, whoever asked: the commit is what a restore
     // starts from, and for a deletion made in the app or by the cleanup this
     // line is the only trace there is.
-    // By id, never by address: log lines carry no email (the release's own promise).
+    // By id: log lines carry no email addresses.
     const actor = opts?.systemCleanup ? 'system' : user.id;
     log.info(`branch deleted by ${actor}: "${name}" at ${lastCommit ?? '(no commit)'}`);
     // Retire the deleted branch's own workspace clone, best-effort. A stale
@@ -629,6 +629,7 @@ export class WorkflowService implements IWorkflowService {
    */
   private async closeIfEmpty(
     number: number,
+    // `actor` is a user id or `system`, never an address: it goes into a log line.
     opts: { reason: string; actor: string; workspaceId?: string; fresh?: boolean },
   ): Promise<{ base: string } | null> {
     const summary = await this.prs.getPr(number);
@@ -3360,7 +3361,7 @@ export class WorkflowService implements IWorkflowService {
    * Returns true when THIS call closed it.
    */
   async closeEmptyChangeRequest(number: number, user: AuthUser): Promise<boolean> {
-    const closed = await this.closeIfEmpty(number, { reason: 'found empty', actor: user.email });
+    const closed = await this.closeIfEmpty(number, { reason: 'found empty', actor: user.id });
     if (!closed) return false;
     await this.retireMergedSourceBranch(number, closed.base, user);
     return true;

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

@@ -48,12 +48,18 @@ const allowAll = {
   canReadBatch: async (_w: string, _u: string, paths: string[]) =>
     new Map(paths.map((p) => [p, true])),
   // The verbs `file_stat` and the move/delete preflight ask about. Allowing
-  // everything, and answering "no rules at HEAD" for the batch write check,
-  // keeps these tests about what they test rather than about access.
+  // everything keeps these tests about what they test rather than about
+  // access.
   canWrite: async () => true,
+  canWriteBatch: async (_w: string, _u: string, paths: string[]) =>
+    new Map(paths.map((p) => [p, true])),
   canDownload: async () => true,
   canOwner: async () => true,
-  canWriteBatchAtRef: async () => null,
+  // The `canWrite` the read tools report is judged at the default branch's
+  // HEAD, so a write-scope caller here gets a COMPUTED `true` — never the
+  // fail-closed `false` of a missing method or an unresolvable ref.
+  canWriteBatchAtRef: async (_w: string, _r: string, _u: string, paths: string[]) =>
+    new Map(paths.map((p) => [p, true])),
   // The `after` half of a move's or copy's preview. Allowing everything here
   // keeps it the same answer as the four gates above; what the relocation of
   // a folder's `access.md` files actually does to it is exercised against
@@ -372,7 +378,7 @@ async function isDeadOrZombie(pid: number): Promise<boolean> {
 describe('workspace file primitives', () => {
   it('read_file returns the content', async () => {
     const base = await start();
-    expect(await (await post(`${base}/api/agent/tools/read_file`, { path: `${KB_DIR}/a.md` })).json()).toEqual({ path: `${KB_DIR}/a.md`, content: 'hello\nworld\n' });
+    expect(await (await post(`${base}/api/agent/tools/read_file`, { path: `${KB_DIR}/a.md` })).json()).toEqual({ path: `${KB_DIR}/a.md`, content: 'hello\nworld\n', canWrite: true });
   });
 
   it('write_file then read_file round-trips', async () => {
@@ -505,7 +511,7 @@ describe('workspace file primitives', () => {
   // that same text into an agent: a leading slash names the same path.
   it('every path input accepts a leading slash as the same workspace path', async () => {
     const base = await start();
-    expect(await (await post(`${base}/api/agent/tools/read_file`, { path: `/${KB_DIR}/a.md` })).json()).toEqual({ path: `${KB_DIR}/a.md`, content: 'hello\nworld\n' });
+    expect(await (await post(`${base}/api/agent/tools/read_file`, { path: `/${KB_DIR}/a.md` })).json()).toEqual({ path: `${KB_DIR}/a.md`, content: 'hello\nworld\n', canWrite: true });
     expect(await (await post(`${base}/api/agent/tools/file_stat`, { path: `/${KB_DIR}/a.md` })).json()).toMatchObject({ type: 'file' });
     await post(`${base}/api/agent/tools/write_file`, { path: `/${KB_DIR}/b.md`, content: 'fresh' });
     await post(`${base}/api/agent/tools/write_file`, { path: `/${KB_DIR}/c.md`, content: 'batch' });
@@ -1117,14 +1123,14 @@ describe('write modes and per-path outcomes', () => {
 describe("the agent guide at the guide's name", () => {
   const GUIDE = `${KB_DIR}/AGENTS.md`;
   const read = (base: string, p = GUIDE, extra: Record<string, unknown> = {}) =>
-    post(`${base}/api/agent/tools/read_file`, { path: p, ...extra }).then((r) => r.json() as Promise<{ path: string; content: string }>);
+    post(`${base}/api/agent/tools/read_file`, { path: p, ...extra }).then((r) => r.json() as Promise<{ path: string; content: string; canWrite?: boolean }>);
   const statOf = (base: string, p = GUIDE) =>
     post(`${base}/api/agent/tools/file_stat`, { path: p }).then((r) => r.json() as Promise<Record<string, unknown>>);
 
   it('answers with the guide when the knowledge base has no file of that name', async () => {
     guideText = 'THE PLATFORM GUIDE\n';
     const base = await start();
-    expect(await read(base)).toEqual({ path: GUIDE, content: 'THE PLATFORM GUIDE\n' });
+    expect(await read(base)).toEqual({ path: GUIDE, content: 'THE PLATFORM GUIDE\n', canWrite: false });
     // By the root-anchored and the prefix-less spellings too, like any path.
     expect((await read(base, `/${GUIDE}`)).content).toBe('THE PLATFORM GUIDE\n');
     expect((await read(base, 'AGENTS.md')).content).toBe('THE PLATFORM GUIDE\n');
@@ -1145,7 +1151,9 @@ describe("the agent guide at the guide's name", () => {
     guideText = 'THE PLATFORM GUIDE\n';
     const base = await start();
     await fs.writeFile(`${KB_DIR}/AGENTS.md`, '# Acme\n\nWrite tickets in the present tense.\n');
-    const { content } = await read(base);
+    const { content, canWrite } = await read(base);
+    // Its own file is a file like any other: the write verdict is the rules' answer for it.
+    expect(canWrite).toBe(true);
     expect(content.startsWith('# Acme\n\nWrite tickets in the present tense.\n\n---\n')).toBe(true);
     expect(content.endsWith('\n\nTHE PLATFORM GUIDE\n')).toBe(true);
     expect(content).toContain("The text above is this knowledge base's own conventions file.");
@@ -1155,7 +1163,7 @@ describe("the agent guide at the guide's name", () => {
     guideText = 'THE PLATFORM GUIDE\n';
     const base = await start();
     await fs.writeFile(`${KB_DIR}/AGENTS.md`, '# Knowledge base\n\n> **This file is managed by the platform.** Stale.\n');
-    expect((await read(base)).content).toBe('THE PLATFORM GUIDE\n');
+    expect(await read(base)).toEqual({ path: GUIDE, content: 'THE PLATFORM GUIDE\n', canWrite: false });
   });
 
   it("never tells a caller who may not read the knowledge base's own file that it exists", async () => {
@@ -1199,7 +1207,7 @@ describe("the agent guide at the guide's name", () => {
     };
     await fs.writeFile(`${KB_DIR}/AGENTS.md`, '# Acme\n');
     vanish = true;
-    expect(await read(base)).toEqual({ path: GUIDE, content: 'THE PLATFORM GUIDE\n' });
+    expect(await read(base)).toEqual({ path: GUIDE, content: 'THE PLATFORM GUIDE\n', canWrite: false });
     await fs.writeFile(`${KB_DIR}/AGENTS.md`, '# Acme\n');
     vanish = true;
     expect(await statOf(base)).toMatchObject({ platformGuide: true });
@@ -2211,7 +2219,7 @@ describe('images', () => {
     const body = (await (await post(`${base}/api/agent/tools/read_file`, { path: `${KB_DIR}/photo.jpg` })).json()) as ImageSentinel;
     expect(body.mimeType).toBe('image/jpeg');
     expect(body.data).toBe(bytes.toString('base64'));
-    expect(body.note).toBe(`[image: ${KB_DIR}/photo.jpg — image/jpeg, ${bytes.length} bytes]`);
+    expect(body.note).toBe(`[image: ${KB_DIR}/photo.jpg — image/jpeg, ${bytes.length} bytes] (canWrite: true)`);
   });
 
   it('read_file refuses an image over 3.5 MiB raw with the downscale message, not a sentinel', async () => {
@@ -2237,6 +2245,7 @@ describe('images', () => {
     expect(await (await post(`${base}/api/agent/tools/read_file`, { path: `${KB_DIR}/icon.svg` })).json()).toEqual({
       path: `${KB_DIR}/icon.svg`,
       content: svg,
+      canWrite: true,
     });
   });
 
@@ -2776,6 +2785,7 @@ describe('the tools place an unprefixed path inside the repository', () => {
     expect(await (await tool(base, 'read_file', { path: 'Notes.md' })).json()).toEqual({
       path: `${KB_DIR}/Notes.md`,
       content: 'hello\nworld\n',
+      canWrite: true,
     });
     expect(await (await tool(base, 'file_stat', { path: 'Notes.md' })).json()).toMatchObject({ type: 'file' });
     const edited = await tool(base, 'edit_file', { path: 'Notes.md', old_string: 'world', new_string: 'earth' });

package/src/modules/workspace/index.ts

@@ -0,0 +1,14 @@
+/**
+ * What the workspace module offers the other modules: how a file's bytes are
+ * read and told apart — the reader registry `read_file` dispatches on, and
+ * the raw content type a file is served with — so a module that serves a
+ * file answers exactly as a read of it would. The services are wired by the
+ * composition root.
+ */
+export {
+  FileReaderRegistry,
+  type FileKind,
+  type FileReader,
+  type ReadResult,
+} from './file-readers/file-reader.js';
+export { OCTET_STREAM, rawExtensionOf, rawMimeFor } from './file-readers/raw-mime.js';