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

package/src/modules/workspace/__tests__/agent-uploads.test.ts

@@ -18,6 +18,7 @@ import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { normalizeWorkspacePath } from '../../kb-fs/repo-path.js';
 import {
@@ -243,7 +244,7 @@ async function start(options: StartOptions = {}): Promise<string> {
     fakeAuth,
     toolHandler,
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
-    new DocExtractService(docCacheDir),
+    new DocExtractService(docCacheDir, new WorkerDocumentExtractor()),
     access,
     testKbContext({ kbDirName: KB_DIR }),
     { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
@@ -535,6 +536,83 @@ describe('the upload route', () => {
     expect(await readdir(uploadsDir)).toEqual([]);
   });
 
+  it('discards a token on request, with the bytes sent against it, the token in a header', async () => {
+    const base = await start();
+    const discard = (token: string) =>
+      fetch(`${base}/api/agent/uploads`, { method: 'DELETE', headers: { 'x-upload-token': token } });
+    const { token } = await request(base);
+    expect((await send(base, token, 'a.md', Buffer.from('a'))).status).toBe(200);
+    expect(await readdir(uploadsDir)).toHaveLength(1);
+    expect((await discard(token)).status).toBe(204);
+    expect(await readdir(uploadsDir)).toEqual([]);
+    // Spent: neither an apply nor a second discard can use it.
+    const applied = await call(base, 'apply_file_upload', { branch: DRAFT, token, destination: KB_DIR });
+    expect(applied.ok).toBe(false);
+    expect(batches).toEqual([]);
+    const again = await discard(token);
+    expect(again.status).toBe(404);
+    expect((await json<{ error: string }>(again)).error).toBe(UPLOAD_TOKEN_REFUSAL);
+    // A token nothing was sent against goes the same way, and its slot with it.
+    const { token: unsent } = await request(base);
+    expect((await discard(unsent)).status).toBe(204);
+    expect((await send(base, unsent, 'b.md', Buffer.from('b'))).status).toBe(404);
+  });
+
+  it('refuses to discard a token an apply is holding, and leaves its bytes', async () => {
+    const base = await start();
+    const { token } = await request(base);
+    await send(base, token, 'a.md', Buffer.from('a'));
+    uploads.claim(token, 'u');
+    const res = await fetch(`${base}/api/agent/uploads`, { method: 'DELETE', headers: { 'x-upload-token': token } });
+    expect(res.status).toBe(404);
+    expect(await readdir(uploadsDir)).toHaveLength(1);
+    uploads.release(token);
+  });
+
+  it('refuses to discard a token whose bytes are still arriving, and the upload finishes whole', async () => {
+    const base = await start();
+    const { token } = await request(base);
+    const head = Buffer.from('the first half, ');
+    const tail = Buffer.from('and the second half');
+    let finish!: () => void;
+    const body = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        controller.enqueue(new Uint8Array(head));
+        await new Promise<void>((resolve) => {
+          finish = resolve;
+        });
+        controller.enqueue(new Uint8Array(tail));
+        controller.close();
+      },
+    });
+    const arriving = fetch(`${base}/api/agent/uploads?filename=held.md`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/octet-stream', 'x-upload-token': token },
+      body,
+      // Node's fetch requires this for a streamed request body.
+      duplex: 'half',
+    } as RequestInit & { duplex: 'half' });
+    // Waited for, not assumed from a delay: the body has reached the store
+    // and its first bytes are staged, with the request still open.
+    const staged = Date.now() + 5_000;
+    while ((await readdir(uploadsDir).catch(() => [])).length === 0) {
+      expect(Date.now(), 'the upload never reached the store').toBeLessThan(staged);
+      await new Promise((r) => setTimeout(r, 10));
+    }
+
+    const res = await fetch(`${base}/api/agent/uploads`, { method: 'DELETE', headers: { 'x-upload-token': token } });
+    expect(res.status).toBe(404);
+    expect((await json<{ error: string }>(res)).error).toBe(UPLOAD_TOKEN_REFUSAL);
+    // The file being written is still there, and the token still good.
+    expect(await readdir(uploadsDir)).toHaveLength(1);
+
+    finish();
+    expect((await arriving).status).toBe(200);
+    const whole = Buffer.concat([head, tail]);
+    expect((await apply(base, { branch: DRAFT, token, destination: `${KB_DIR}/Held` })).count).toBe(1);
+    expect(sha(await readFile(join(tempDir, KB_DIR, 'Held/held.md')))).toBe(sha(whole));
+  });
+
   it('refuses a second upload against the same token', async () => {
     const base = await start();
     const { token } = await request(base);
@@ -1194,7 +1272,15 @@ describe('a token is good once, for one user, for a limited time', () => {
     const res = await call(base, 'apply_file_upload', { branch: DRAFT, token, destination: KB_DIR });
     expect(res.status).toBe(404);
     expect((await json<{ error: string }>(res)).error).toBe(UPLOAD_TOKEN_REFUSAL);
+    // The refusal drops the record and starts the delete without awaiting it,
+    // so a sweep run straight after no longer names the file and leaves it to
+    // that delete. Wait for the delete to land, under a deadline, instead of
+    // racing it: a readdir taken mid-`rm` failed CI on PR #457.
     await uploads.sweepNow();
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline && (await readdir(uploadsDir)).length > 0) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
     expect(await readdir(uploadsDir)).toEqual([]);
   });
 

package/src/modules/workspace/__tests__/escape-sequences.routes.test.ts

@@ -17,6 +17,7 @@ import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { createMcpRoutes } from '../../mcp/mcp.routes.js';
 import { McpService } from '../../mcp/mcp.service.js';
@@ -136,7 +137,7 @@ async function startPlatform(): Promise<Platform> {
     fakeAuth,
     createToolHandlerFactory(resolve),
     new SpillStore(join(tempDir, 'spills')),
-    new DocExtractService(join(tempDir, 'doc-extract')),
+    new DocExtractService(join(tempDir, 'doc-extract'), new WorkerDocumentExtractor()),
     allowAll,
     testKbContext({ kbDirName: KB_DIR }),
     { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },

package/src/modules/workspace/__tests__/file-stat-access.test.ts

@@ -16,6 +16,7 @@ import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { AccessControlService } from '../../access/access-control.service.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
@@ -86,7 +87,7 @@ beforeAll(async () => {
     },
     createToolHandlerFactory(resolve),
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
-    new DocExtractService(docCache),
+    new DocExtractService(docCache, new WorkerDocumentExtractor()),
     service,
     testKbContext({ kbDirName: KB }),
     { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },

package/src/modules/workspace/__tests__/git-internals.security.test.ts

@@ -28,6 +28,7 @@ import { registerWorkspaceTools } from '../workspace.tools.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
 import { createGitInternalsRouteGuard } from '../git-internals.middleware.js';
 import { hasGitInternalsSegment } from '../../../shared/git-internals.js';
@@ -282,7 +283,7 @@ describe('workspace tools refuse the git folder', () => {
       fakeAuth,
       createToolHandlerFactory(resolve),
       new SpillStore(join(root, 'spills')),
-      new DocExtractService(join(root, 'doc-cache')),
+      new DocExtractService(join(root, 'doc-cache'), new WorkerDocumentExtractor()),
       allowAll,
       testKbContext({ kbDirName: KB }),
       { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },

package/src/modules/workspace/__tests__/rest-tool-arguments.test.ts

@@ -17,6 +17,7 @@ import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { AccessControlService } from '../../access/access-control.service.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { BRANCH_REQUIRED_MESSAGE } from '../../../shared/domain-errors.js';
@@ -91,7 +92,7 @@ beforeAll(async () => {
     },
     createToolHandlerFactory(resolve),
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
-    new DocExtractService(docCache),
+    new DocExtractService(docCache, new WorkerDocumentExtractor()),
     access,
     testKbContext({ kbDirName: KB }),
     { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },

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

@@ -0,0 +1,118 @@
+import { EventEmitter } from 'node:events';
+import type { Worker } from 'node:worker_threads';
+import { describe, expect, it } from 'vitest';
+import { WorkerPool } from '../worker-pool.js';
+
+/** A stand-in worker: what the pool calls on one, and whether it was terminated. */
+class FakeWorker extends EventEmitter {
+  terminated = false;
+  ref(): void {}
+  unref(): void {}
+  terminate(): Promise<number> {
+    if (!this.terminated) {
+      this.terminated = true;
+      queueMicrotask(() => this.emit('exit', 1));
+    }
+    return Promise.resolve(1);
+  }
+}
+
+/** A pool of fake workers, and every worker it started that is still running. */
+function fakePool(poolMax: number, maxWaiting = 10) {
+  const spawned: FakeWorker[] = [];
+  const pool = new WorkerPool(
+    () => {
+      const w = new FakeWorker();
+      spawned.push(w);
+      return w as unknown as Worker;
+    },
+    { poolMax, maxWaiting },
+    () => new Error('busy'),
+  );
+  const running = () => spawned.filter((w) => !w.terminated).length;
+  return { pool, spawned, running };
+}
+
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+
+describe('WorkerPool.acquireFresh', () => {
+  it('swaps the worker freed by another job in its own place, with jobs queued behind it', async () => {
+    const { pool, running } = fakePool(1);
+    const held = await pool.acquire();
+    const fresh = pool.acquireFresh();
+    const queued = pool.acquire();
+    await tick();
+
+    // The holder's job ends with a worker that must not be reused; its place
+    // goes to the next waiting job, the fresh request.
+    pool.discard(held);
+    const freshWorker = await fresh;
+    expect(freshWorker).not.toBe(held);
+    expect(running()).toBe(1);
+
+    // The queued job waits for that worker, not for a second one.
+    let settled = false;
+    void queued.then(() => (settled = true));
+    await tick();
+    expect(settled).toBe(false);
+    expect(running()).toBe(1);
+
+    pool.release(freshWorker);
+    expect(await queued).toBe(freshWorker);
+    expect(running()).toBe(1);
+    await pool.close();
+  });
+
+  it('swaps a released worker for a new one without passing a second one to the queue', async () => {
+    const { pool, running } = fakePool(1);
+    const held = await pool.acquire();
+    const fresh = pool.acquireFresh();
+    const queued = pool.acquire();
+    await tick();
+
+    pool.release(held);
+    const freshWorker = await fresh;
+    expect(freshWorker).not.toBe(held);
+    expect((held as unknown as FakeWorker).terminated).toBe(true);
+    await tick();
+    expect(running()).toBe(1);
+
+    pool.release(freshWorker);
+    expect(await queued).toBe(freshWorker);
+    expect(running()).toBe(1);
+    await pool.close();
+  });
+
+  it('swaps an idle worker that has run a job when the pool is full', async () => {
+    const { pool, running } = fakePool(2);
+    const a = await pool.acquire();
+    const b = await pool.acquire();
+    pool.release(a);
+    const fresh = await pool.acquireFresh();
+    expect(fresh).not.toBe(a);
+    expect(fresh).not.toBe(b);
+    expect((a as unknown as FakeWorker).terminated).toBe(true);
+    await tick();
+    expect(running()).toBe(2);
+    await pool.close();
+  });
+
+  it('starts a new worker when the pool has room', async () => {
+    const { pool, spawned } = fakePool(2);
+    const a = await pool.acquire();
+    pool.release(a);
+    const fresh = await pool.acquireFresh();
+    expect(fresh).not.toBe(a);
+    expect(spawned).toHaveLength(2);
+    await pool.close();
+  });
+
+  it('answers busy after close, for a fresh request waiting in the queue too', async () => {
+    const { pool } = fakePool(1);
+    await pool.acquire();
+    const fresh = pool.acquireFresh();
+    await pool.close();
+    await expect(fresh).rejects.toThrow('busy');
+    await expect(pool.acquireFresh()).rejects.toThrow('busy');
+  });
+});

package/src/modules/workspace/__tests__/workspace-paths-inside-the-repo.test.ts

@@ -458,9 +458,10 @@ describe('no code path outside the normaliser resolves a workspace path', () =>
 
   it('every write route passes its path through the normaliser before anything else', async () => {
     const text = await fs.readFile(path.join(here, '..', 'workspace.routes.ts'), 'utf-8');
-    // One helper, and it is the normaliser's: a route that grew its own
+    // One helper, and it is the normaliser's — reached through kb-fs's public
+    // entry, as every module reaches another: a route that grew its own
     // strip-if-present reading of the prefix is what this forbids.
-    expect(text).toContain("import { normalizeWorkspacePath } from '../kb-fs/repo-path.js'");
+    expect(text).toMatch(/import \{[^}]*\bnormalizeWorkspacePath\b[^}]*\} from '\.\.\/kb-fs\/index\.js'/);
     expect(text.match(/normalizeWorkspacePath\(/g)).toHaveLength(1);
     // The old reading, spelled out so it cannot come back unnoticed.
     expect(text).not.toMatch(/startsWith\(`\$\{kbDirName\}\/`\)\s*\n?\s*\?/);

package/src/modules/workspace/__tests__/workspace.service.ensure-remotes-fetched.test.ts

@@ -106,4 +106,34 @@ describe('WorkspaceService.ensureRemotesFetched', () => {
 
     expect(fetches().length - beforeTheRace).toBe(1);
   });
+
+  // What an AUTHORIZING caller (`changeRequestDecisionGrant`) relies on: a
+  // warm cache must not stand in for a refresh that failed. `strict` alone
+  // answers from the window without fetching, so only `strict + force` turns
+  // an origin outage into a refusal instead of a check against older refs.
+  it('strict + force refuses when the refresh fails, even with a warm cache', async () => {
+    let failing = false;
+    runner = {
+      defaultTimeoutMs: 1000,
+      run: vi.fn(async (_cwd: string, args: string[]) => {
+        runs.push(args);
+        if (failing && args[0] === 'fetch') throw new Error('origin unreachable');
+        return { stdout: '', stderr: '' };
+      }),
+      // Read by the failure log, which redacts the token from the error.
+      credentials: { token: () => null },
+    } as unknown as IGitRunner;
+    const svc = service();
+    await svc.ensureRemotesFetched('main', { strict: true }); // warms the window
+    failing = true;
+
+    // Inside the window, strict alone does not even try the remote.
+    await expect(svc.ensureRemotesFetched('main', { strict: true })).resolves.toBeUndefined();
+    expect(fetches()).toHaveLength(1);
+
+    await expect(svc.ensureRemotesFetched('main', { strict: true, force: true })).rejects.toThrow(
+      /could not be refreshed/,
+    );
+    expect(fetches()).toHaveLength(2);
+  });
 });

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -10,6 +10,7 @@ import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { SpillStore } from '../spill-store.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
@@ -47,7 +48,7 @@ async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promis
     auth,
     createToolHandlerFactory(() => ({ userEmail: 'a@x.io' })) as never,
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
-    new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
+    new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), new WorkerDocumentExtractor()),
     {} as unknown as IAccessControl,
     kb,
     {

package/src/modules/workspace/__tests__/workspace.tools.branch-errors.test.ts

@@ -26,6 +26,7 @@ import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
 import { WorkerPatternMatcher } from '../bounded-matcher.js';
 import { WorkspaceService } from '../workspace.service.js';
@@ -189,7 +190,7 @@ describe('workspace tools — a branch that cannot be opened', () => {
         isMissing: (branch) => workspaces!.isBranchMissing(branch),
       }),
       new SpillStore(spillRoot),
-      new DocExtractService(docCacheDir),
+      new DocExtractService(docCacheDir, new WorkerDocumentExtractor()),
       allowAll,
       testKbContext({ kbDirName: KB_DIR }),
       {

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

@@ -25,6 +25,7 @@ import { WorkflowHooks, type AgentOperationContext } from '../../workflow/workfl
 import { SESSION_ID_DESCRIPTION, ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { OCTET_STREAM_FALLBACK_NOTE } from '../file-readers/content-mode.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { AccessControlService } from '../../access/access-control.service.js';
@@ -144,6 +145,11 @@ let raceHook: (() => Promise<void>) | null = null;
  * defaults, unless a test narrows the pool) and closed after each test.
  */
 let patternMatcher: WorkerPatternMatcher | undefined;
+/**
+ * The document extractor `start()` wires, closed after each test: its workers
+ * are made lazily, and `unref()` lets the process exit but keeps them alive.
+ */
+let docExtractor: WorkerDocumentExtractor | undefined;
 let matcherOptions: WorkerPatternMatcherOptions = {};
 
 async function start(
@@ -155,6 +161,9 @@ async function start(
   raceHook = null;
   await patternMatcher?.close();
   patternMatcher = new WorkerPatternMatcher(matcherOptions);
+  await docExtractor?.close();
+  const extractor = new WorkerDocumentExtractor();
+  docExtractor = extractor;
   hooks = new WorkflowHooks();
   notes = new ToolDescriptionNotes();
   callerSource = 'internal';
@@ -309,7 +318,7 @@ async function start(
   const app = express();
   app.use(express.json());
   const router = express.Router();
-  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, testKbContext({ kbDirName: KB_DIR }), {
+  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir, extractor), access, testKbContext({ kbDirName: KB_DIR }), {
     // The hooks and the notes a test registers against; with neither
     // registered (the default, and every Hexis-only deployment) the gate
     // refuses nothing and the descriptions say nothing extra.
@@ -354,6 +363,8 @@ afterEach(async () => {
   httpServer = undefined;
   await patternMatcher?.close();
   patternMatcher = undefined;
+  await docExtractor?.close();
+  docExtractor = undefined;
   if (tempDir) {
     await rm(tempDir, { recursive: true, force: true });
     tempDir = '';
@@ -2137,6 +2148,7 @@ describe('images', () => {
 describe('start_session', () => {
   // Minimal harness: own app + a fake ISessionSink that records createSession.
   let server: HttpServer | undefined;
+  let sessionExtractor: WorkerDocumentExtractor | undefined;
   let created: Array<{ userId: string; startedAt: Date }> = [];
 
   async function startSessionApp(
@@ -2189,9 +2201,12 @@ describe('start_session', () => {
     const app = express();
     app.use(express.json());
     const router = express.Router();
+    await sessionExtractor?.close();
+    const extractor = new WorkerDocumentExtractor();
+    sessionExtractor = extractor;
     registerWorkspaceTools(
       registry, router, auth, toolHandler,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), access, testKbContext({ kbDirName: KB_DIR }),
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor), access, testKbContext({ kbDirName: KB_DIR }),
       { recoveryBotEmail: RECOVERY_BOT, hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
       new RoutineWritePolicyService(),
       sink ?? fakeSessionSink,
@@ -2213,6 +2228,8 @@ describe('start_session', () => {
   afterEach(async () => {
     if (server) await new Promise<void>((r) => server!.close(() => r()));
     server = undefined;
+    await sessionExtractor?.close();
+    sessionExtractor = undefined;
   });
 
   it('returns the sink-minted id as sessionId', async () => {
@@ -2321,9 +2338,10 @@ describe('start_session', () => {
     const registry = new ToolRegistry();
     const router = express.Router();
     const noopAuth: express.RequestHandler = (_req, _res, next) => next();
+    const extractor = new WorkerDocumentExtractor();
     registerWorkspaceTools(
       registry, router, noopAuth, (() => () => {}) as never,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor), allowAll, testKbContext({ kbDirName: KB_DIR }),
       { recoveryBotEmail: RECOVERY_BOT, hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
       new RoutineWritePolicyService(),
       {} as never,
@@ -2341,6 +2359,7 @@ describe('start_session', () => {
     // And that the answer may carry a note to act on, so an agent reading
     // only the catalog knows the field is not noise.
     expect(description).toContain('`firstRun`');
+    await extractor.close();
   });
 
   /**
@@ -2484,9 +2503,16 @@ describe('start_session', () => {
  * schema layer, complementing the handler-level guard exercised above.
  */
 describe('branch is a required parameter in the tool contract', () => {
+  /** Every extractor a registry was built with, closed after each test. */
+  const extractors: WorkerDocumentExtractor[] = [];
+  afterEach(async () => {
+    await Promise.all(extractors.splice(0).map((e) => e.close()));
+  });
   /** Register the workspace tools into a fresh registry (no server needed). */
   function buildRegistry(): ToolRegistry {
     const registry = new ToolRegistry();
+    const extractor = new WorkerDocumentExtractor();
+    extractors.push(extractor);
     const router = express.Router();
     const noopAuth: express.RequestHandler = (_req, _res, next) => next();
     // The handler factory is only invoked to build routes; its output is never
@@ -2498,7 +2524,7 @@ describe('branch is a required parameter in the tool contract', () => {
       noopAuth,
       toolHandler,
       new SpillStore(join(tmpdir(), 'bevel-test-spills')),
-      new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
+      new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor),
       allowAll,
       testKbContext({ kbDirName: KB_DIR }),
       { recoveryBotEmail: RECOVERY_BOT, hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },

package/src/modules/workspace/agent-access.gate.ts

@@ -19,9 +19,9 @@
  * all branches and to reads).
  */
 
-import type { JsonSchema } from '../tool-registry/tool.contract.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
-import type { WorkflowHooks } from '../workflow/workflow-hooks.js';
+import type { JsonSchema } from '../tool-registry/index.js';
+import type { ToolContext } from '../tool-helpers/index.js';
+import type { WorkflowHooks } from '../workflow/index.js';
 
 /**
  * What the `sessionId` input says on its own, before any deployment note. The

package/src/modules/workspace/agent-download.builder.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import AdmZip from 'adm-zip';
-import { hasHttpStatus, ToolError } from '../tool-helpers/tool.contract.js';
+import { hasHttpStatus, ToolError } from '../tool-helpers/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { DownloadArtifact } from './agent-download.store.js';
 

package/src/modules/workspace/agent-upload.routes.ts

@@ -135,6 +135,25 @@ export function createAgentUploadRoutes(deps: AgentUploadRouteDeps): express.Rou
   router.post(AGENT_UPLOAD_ROUTE, handle);
   router.post(AGENT_UPLOAD_HEADER_ROUTE, handle);
 
+  // `DELETE /api/agent/uploads` with the token in `x-upload-token`: give the
+  // token up unapplied, and its bytes with it, now rather than at its expiry
+  // (see `AgentUploadStore.discard`). The app sends it when a page's
+  // `uploadFile` was refused, since nobody else holds that token to retry.
+  // Header form only: the token stays out of the address here too.
+  router.delete(AGENT_UPLOAD_HEADER_ROUTE, async (req, res) => {
+    try {
+      await uploads.discard(tokenOf(req));
+      res.status(204).end();
+    } catch (err) {
+      if (err instanceof UploadTokenError) {
+        res.status(err.status).json({ error: err.message });
+        return;
+      }
+      log.error('discarding an upload failed:', { err });
+      res.status(500).json({ error: 'Discarding the upload failed' });
+    }
+  });
+
   return router;
 }
 

package/src/modules/workspace/agent-upload.store.ts

@@ -417,6 +417,24 @@ export class AgentUploadStore {
     }
   }
 
+  /**
+   * Give `token` up unapplied: spend it and delete any bytes sent with it NOW,
+   * rather than when it expires. For a caller that will not retry — the app
+   * answering a page's `uploadFile`, which holds the token on the page's behalf
+   * and drops it when the upload or the apply is refused.
+   *
+   * Refused with the one refusal, like every unusable token, and also while
+   * the token is busy — bytes still arriving, or an apply holding it — so a
+   * discard never deletes a file somebody is writing or reading.
+   */
+  async discard(token: string): Promise<void> {
+    const record = this.find(token);
+    // `attaching` stays set once the bytes are in; only without `received` are they still arriving.
+    const arriving = record.attaching && record.received === undefined;
+    if (arriving || record.claimed) throw new UploadTokenError(UPLOAD_TOKEN_REFUSAL, 404);
+    await this.consume(token);
+  }
+
   /** Spend the token and delete its bytes. Idempotent. */
   async consume(token: string): Promise<void> {
     const key = hash(token);