@bevel-software/platform-core-backend 0.13.1 → 0.13.5

package/src/modules/access/__tests__/access-own-read-grant.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+import { registerAccessFrontmatterExtensions } from '../../access-model/access-grammar.js';
+
+const KB = 'knowledge-base';
+
+const ROLES_YAML = `roles:
+  Admin:
+    - razvan@bevel.software
+  Developer:
+    - coding-agent@bevel.software
+  Agent:
+    - coding-agent@bevel.software
+`;
+
+// Shaped like the real files: folded descriptions, literal blocks, nested
+// maps, comments — everything the access grammar's subset parser stops at.
+const PIPELINE = `---
+apiVersion: bevel.software/v1
+kind: Pipeline
+id: coding-delivery-process
+name: Coding Delivery
+description: >-
+  End-to-end delivery of one coding ticket: workspace preparation, coding, local
+  testing, a two-check review gate, staged rollout, and production verification.
+# Which tickets this runner works.
+queue:
+  trigger: dataStatus
+  projects:
+    - KnowledgeBase/Engineering/Knowledge/Bevel-Platform.md
+do:
+  - name: Coding
+    kind: agent
+    instructions: |
+      Implement the ticket in the workspace.
+      Commit locally; never push.
+owner: razvan.radulescu <razvan@bevel.software>
+read: coding-agent <coding-agent@bevel.software>
+write: Developer
+---
+`;
+
+const AGENT = `---
+apiVersion: bevel.software/v1
+kind: Agent
+id: delivery_coder
+name: delivery-coder
+description: >-
+  Writes and verifies the code for one delivery ticket.
+systemPrompt:
+  extend: |
+    You are executing exactly ONE step of a pipeline.
+env:
+  - { name: STAGING_URL, from: params, param: stagingUrl }
+owner: razvan.radulescu <razvan@bevel.software>
+read: coding-agent <coding-agent@bevel.software>
+write: Developer
+---
+
+# delivery-coder
+`;
+
+describe('a file-own read grant on a whole-document configuration file', () => {
+  let root: string;
+  let repo: string;
+  const ws = 'ws-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'own-read-'));
+    repo = path.join(root, ws, KB);
+    await fs.mkdir(path.join(repo, 'Pipelines'), { recursive: true });
+    await fs.mkdir(path.join(repo, 'Agents'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'roles.yaml'), ROLES_YAML);
+    await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\ndownload:\n  - Admin\nowner: []\n---\n');
+    await fs.writeFile(path.join(repo, 'Pipelines', 'access.md'), '---\nwrite: []\n---\n');
+    await fs.writeFile(path.join(repo, 'Pipelines', 'Coding-Delivery.pipeline'), PIPELINE);
+    await fs.writeFile(path.join(repo, 'Agents', 'access.md'), '---\nwrite: []\n---\n');
+    await fs.writeFile(path.join(repo, 'Agents', 'delivery-coder.agent'), AGENT);
+  });
+  afterEach(() => fs.rm(root, { recursive: true, force: true }));
+
+  const svc = () =>
+    new AccessControlService(
+      { getWorkspacePath: async () => path.join(root, ws) } as unknown as WorkspaceService,
+      KB,
+    );
+
+  it('the grantee reads the file (registered kinds)', async () => {
+    registerAccessFrontmatterExtensions(['.pipeline', '.agent']);
+    const s = svc();
+    expect(await s.canRead(ws, 'coding-agent@bevel.software', 'Pipelines/Coding-Delivery.pipeline')).toBe(true);
+    expect(await s.canRead(ws, 'coding-agent@bevel.software', 'Agents/delivery-coder.agent')).toBe(true);
+    expect(await s.canWrite(ws, 'coding-agent@bevel.software', 'Pipelines/Coding-Delivery.pipeline')).toBe(true);
+    // Batch path, which the explorer and the tool catalog use.
+    const batch = await s.canReadBatch(ws, 'coding-agent@bevel.software', [
+      'Pipelines/Coding-Delivery.pipeline',
+      'Agents/delivery-coder.agent',
+      'Pipelines/README.md',
+    ]);
+    expect([...batch.entries()]).toEqual([
+      ['Pipelines/Coding-Delivery.pipeline', true],
+      ['Agents/delivery-coder.agent', true],
+      ['Pipelines/README.md', false],
+    ]);
+  });
+
+  it('a stranger does not', async () => {
+    registerAccessFrontmatterExtensions(['.pipeline', '.agent']);
+    expect(await svc().canRead(ws, 'someone@else.io', 'Pipelines/Coding-Delivery.pipeline')).toBe(false);
+  });
+});

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -129,3 +129,101 @@ describe('the access-frontmatter extension set', () => {
     expect(entries!.write).toEqual([]);
   });
 });
+
+describe('parseOwnAccessEntries — whole-document YAML the subset parser cannot read', () => {
+  // A `.tool` / `.pipeline` / `.agent` is one `---` fenced YAML document, and
+  // real ones use folded and literal scalars and nested maps. The subset
+  // parser stops at the first such line; the verbs must still be read.
+  const doc = [
+    '---',
+    'apiVersion: bevel.software/v1',
+    'kind: Agent',
+    'id: delivery_coder',
+    'description: >-',
+    '  Writes and verifies the code for one delivery ticket. Runs the agent steps',
+    '  of a coding pipeline.',
+    'systemPrompt:',
+    '  extend: |',
+    '    You are executing exactly ONE step of a pipeline.',
+    '    When your verdict is recorded, stop.',
+    'env:',
+    '  - { name: STAGING_URL, from: params, param: stagingUrl }',
+    'owner: razvan.radulescu <razvan@bevel.software>',
+    'read: coding-agent <coding-agent@bevel.software>',
+    'write: Developer',
+    '---',
+    '',
+    '# notes after the fence',
+    '',
+  ].join('\n');
+
+  it('reads the verbs out of a document with folded and literal scalars', () => {
+    const own = parseOwnAccessEntries(doc);
+    expect(own).not.toBeNull();
+    expect(own!.owner).toMatchObject([{ kind: 'user', email: 'razvan@bevel.software', deny: false }]);
+    expect(own!.read).toMatchObject([{ kind: 'user', email: 'coding-agent@bevel.software', deny: false }]);
+    expect(own!.write).toMatchObject([{ kind: 'role', role: 'developer', deny: false }]);
+  });
+
+  it('still answers null for a document that declares no verb, and for broken YAML', () => {
+    expect(parseOwnAccessEntries('---\ndescription: >-\n  folded\n  text\n---\n')).toBeNull();
+    // Broken for BOTH parsers: the folded scalar stops the subset one, the
+    // unclosed flow sequence the full one.
+    expect(parseOwnAccessEntries('---\ndescription: >-\n  folded\nread: [unclosed\n---\n')).toBeNull();
+  });
+
+  it('does not change what the subset parser already read', () => {
+    // A node's frontmatter: the historical path, byte for byte.
+    const node = '---\nnodeType: "[Project](../NodeTypes/Project.md)"\nid: project-x\nowner: Someone <s@x.io>\n---\n# Name\n';
+    expect(parseOwnAccessEntries(node)!.owner).toMatchObject([{ kind: 'user', email: 's@x.io' }]);
+  });
+});
+
+describe('parseOwnAccessEntries — quoted and flow-sequence verb values', () => {
+  // The subset parser SUCCEEDS on these and hands the brackets or quotes to
+  // the entry parser as text, so before the fallback they were dropped — or a
+  // quoted role kept its quotes as part of its name. They are real YAML and
+  // must resolve to the grants they spell.
+  it('reads a flow sequence', () => {
+    const own = parseOwnAccessEntries('---\nread: [coding-agent <coding-agent@bevel.software>, Developer]\n---\n');
+    expect(own!.read).toMatchObject([
+      { kind: 'user', email: 'coding-agent@bevel.software' },
+      { kind: 'role', role: 'developer' },
+    ]);
+  });
+
+  it('reads quoted scalars, inline and in a block list', () => {
+    expect(parseOwnAccessEntries('---\nread: "coding-agent <coding-agent@bevel.software>"\n---\n')!.read).toMatchObject([
+      { kind: 'user', email: 'coding-agent@bevel.software' },
+    ]);
+    expect(parseOwnAccessEntries("---\nwrite: 'Developer'\n---\n")!.write).toMatchObject([{ kind: 'role', role: 'developer' }]);
+    expect(parseOwnAccessEntries('---\nowner:\n  - "Someone <s@x.io>"\n---\n')!.owner).toMatchObject([
+      { kind: 'user', email: 's@x.io' },
+    ]);
+  });
+
+  it('keeps the plain entries beside a quoted one exactly as the subset parser read them', () => {
+    // One quoted value sends the whole document to the full parser, which
+    // TYPES scalars: `true` and `42` would come back as a boolean and a number
+    // and never reach the entry grammar. They must resolve exactly as they do
+    // on the subset path — as the (odd, but legal) role names they spell.
+    const viaFull = parseOwnAccessEntries(
+      ['---', 'read: "coding-agent <coding-agent@bevel.software>"', 'write: true', 'owner:', '  - 42', '  - 0x10', '  - 1e3', '---', ''].join('\n'),
+    );
+    const viaSubset = parseOwnAccessEntries(['---', 'write: true', 'owner:', '  - 42', '  - 0x10', '  - 1e3', '---', ''].join('\n'));
+    expect(viaFull!.write).toEqual(viaSubset!.write);
+    expect(viaFull!.owner).toEqual(viaSubset!.owner);
+    expect(viaFull!.write).toMatchObject([{ kind: 'role', role: 'true' }]);
+    // Source spelling, not the number it parses to: `0x10` stays `0x10`.
+    expect(viaFull!.owner.map((e) => (e as { role: string }).role)).toEqual(['42', '0x10', '1e3']);
+  });
+
+  it('leaves the plain forms on the subset path', () => {
+    // An empty flow collection and bare scalars are the subset parser\'s own
+    // grammar; nothing about them asks for the full parser.
+    expect(parseOwnAccessEntries('---\nread: []\nwrite: Developer\n---\n')).toMatchObject({
+      read: [],
+      write: [{ kind: 'role', role: 'developer' }],
+    });
+  });
+});

package/src/modules/access-model/access-grammar.ts

@@ -11,6 +11,7 @@
  * `./group-files.js` import below is access-model's own file, not a breach.)
  */
 
+import { parse as parseFullYaml } from 'yaml';
 import type { GroupsIndex } from './group-files.js';
 
 // ---------------------------------------------------------------------------
@@ -799,6 +800,60 @@ export function parseAccessFile(
  * scope — applied after every directory `access.md` in the chain.
  */
 export type OwnEntries = Record<Verb, ParsedEntry[]>;
+/**
+ * The top-level mapping of a file's own frontmatter, for the verb keys.
+ *
+ * The subset parser is tried first: it is what every `access.md` and node
+ * frontmatter has always been read with, and its answer must not change. But
+ * a whole-document configuration file (`.tool`, and whatever an overlay
+ * registers) is real YAML — folded descriptions (`>-`), literal blocks (`|`),
+ * nested maps — and the subset parser stops at the first line it does not
+ * understand. Before this fallback that meant the file's `owner:` / `read:` /
+ * `write:` were silently dropped: a grant that was reviewed and merged did
+ * not exist, and the file was unreadable by the very principal it named.
+ * So on a subset failure the frontmatter is read by the full parser and only
+ * its top-level mapping is used — the verb keys are looked up exactly as
+ * before, everything else is ignored exactly as before.
+ */
+function ownEntriesRoot(frontmatter: string): unknown {
+  const subset = parseYamlSubset(frontmatter);
+  if (subset.ok && !verbValuesNeedFullYaml(subset.value)) return subset.value;
+  try {
+    // The FAILSAFE schema: every scalar stays the text it was written as —
+    // `true`, `42`, `0x10`, `2026-01-01` — which is all the subset parser has
+    // ever handed the entry grammar. The core schema would type them, and a
+    // role spelled `0x10` would come back as `16` the moment another verb on
+    // the same file used a quoted value.
+    const full = parseFullYaml(frontmatter, { schema: 'failsafe' });
+    // A document the full parser rejects but the subset parser accepted keeps
+    // the subset answer — whatever it read is what has always been read.
+    return full == null ? (subset.ok ? subset.value : null) : full;
+  } catch {
+    return subset.ok ? subset.value : null;
+  }
+}
+
+/**
+ * Whether a verb's value, as the subset parser read it, is really YAML syntax
+ * the subset parser does not understand and passed through as text: a flow
+ * sequence (`read: [A, B]`) or a quoted scalar (`read: "A <a@x>"`, `- 'Role'`).
+ * The subset parser SUCCEEDS on these — it just hands the brackets and quotes
+ * to the entry parser, which then drops the entry, or worse, keeps the quotes
+ * as part of a role name. Such a value means the full parser has to read the
+ * document.
+ */
+function verbValuesNeedFullYaml(root: unknown): boolean {
+  if (!root || typeof root !== 'object' || Array.isArray(root)) return false;
+  const looksLikeSyntax = (v: unknown): boolean =>
+    typeof v === 'string' && /^\s*(\[\s*\S|\{\s*\S|"|')/.test(v);
+  for (const [key, value] of Object.entries(root as Record<string, unknown>)) {
+    if (!KNOWN_VERBS_SET.has(key)) continue;
+    if (looksLikeSyntax(value)) return true;
+    if (Array.isArray(value) && value.some(looksLikeSyntax)) return true;
+  }
+  return false;
+}
+
 /**
  * Parse the access verbs a node file declares in its own YAML frontmatter.
  * Returns the per-verb entry lists, or null when the file has no frontmatter
@@ -812,9 +867,7 @@ export type OwnEntries = Record<Verb, ParsedEntry[]>;
 export function parseOwnAccessEntries(text: string): OwnEntries | null {
   const fm = extractFrontmatter(text);
   if (!fm.ok) return null;
-  const parsed = parseYamlSubset(fm.frontmatter);
-  if (!parsed.ok) return null;
-  const root = parsed.value;
+  const root = ownEntriesRoot(fm.frontmatter);
   if (root == null || typeof root !== 'object' || Array.isArray(root)) return null;
 
   const entries = emptyEntries();

package/src/modules/kb-fs/__tests__/clone-config.test.ts

@@ -11,11 +11,14 @@ describe('cloneTrackingConfigArgs', () => {
   // A slashed draft name is the everyday case (`<email-localpart>/<slug>`), and
   // the branch lands verbatim inside the config KEY — pin the exact tuples so a
   // future quoting/encoding change can't silently re-point tracking.
-  it('emits the three --replace-all tuples for a slashed branch', () => {
+  it('emits the tracking tuples for a slashed branch, and keeps gc in the foreground', () => {
     expect(cloneTrackingConfigArgs('feature/x')).toEqual([
       ['config', '--replace-all', 'remote.origin.fetch', ORIGIN_FETCH_REFSPEC],
       ['config', '--replace-all', 'branch.feature/x.remote', 'origin'],
       ['config', '--replace-all', 'branch.feature/x.merge', 'refs/heads/feature/x'],
+      // A detached `gc --auto` outlives the command this process waits on and
+      // is never reaped; stamped here so existing clones get it on next pull.
+      ['config', '--replace-all', 'gc.autoDetach', 'false'],
     ]);
   });
 });

package/src/modules/kb-fs/clone-config.ts

@@ -68,12 +68,23 @@ export const SAFE_IMPLICIT_FETCH_ARGS: readonly string[] = [
  * Returns the arguments rather than running them so each caller can use its own
  * git runner (the git service's mutex-aware wrapper, `git -C` from the
  * workspace service) — no process is spawned here.
+ *
+ * `gc.autoDetach=false` rides along because it is stamped in the same two
+ * places — on adopt, and before every pull — which is how clones already on
+ * disk pick it up. After a fetch or a commit git may decide to run
+ * `gc --auto`, and by default it forks that into the BACKGROUND, detached from
+ * the git command this process is waiting on. The detached gc reparents to
+ * PID 1 and, when it exits, stays a zombie unless PID 1 reaps it — a node
+ * server does not. One shared host was found carrying 1,500 zombie `git`
+ * processes under a single platform container. With auto-detach off the gc
+ * runs inside the command that triggered it, and that command's exit reaps it.
  */
 export function cloneTrackingConfigArgs(branch: string): string[][] {
   return [
     ['config', '--replace-all', 'remote.origin.fetch', ORIGIN_FETCH_REFSPEC],
     ['config', '--replace-all', `branch.${branch}.remote`, 'origin'],
     ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`],
+    ['config', '--replace-all', 'gc.autoDetach', 'false'],
   ];
 }
 

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

@@ -1,6 +1,6 @@
 import type { Server as HttpServer } from 'node:http';
 import { execFile } from 'node:child_process';
-import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
@@ -147,6 +147,25 @@ afterEach(async () => {
   }
 });
 
+/**
+ * True once `pid` has been killed: either it is gone, or it is a zombie
+ * waiting on a reaper (Linux: `State:\tZ` in /proc). `kill(pid, 0)` alone
+ * cannot tell a zombie from a live process.
+ */
+async function isDeadOrZombie(pid: number): Promise<boolean> {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return true;
+  }
+  try {
+    const status = await readFile(`/proc/${pid}/status`, 'utf8');
+    return /^State:\s*Z/m.test(status);
+  } catch {
+    return false; // no /proc (macOS): alive as far as the signal says
+  }
+}
+
 describe('workspace file primitives', () => {
   it('read_file returns the content', async () => {
     const base = await start();
@@ -191,6 +210,40 @@ describe('workspace file primitives', () => {
     expect(res.exitCode).toBe(0);
   });
 
+  // The command runs under `sh -c`; a timeout used to SIGKILL that shell and
+  // leave what it had started running on as an orphan. The whole process
+  // group goes now. POSIX only: Windows has no process groups to kill.
+  it.skipIf(process.platform === 'win32')('execute_command kills what the command started, not just its shell, on timeout', async () => {
+    const base = await start();
+    // Print the grandchild's pid, then block on it so the timeout fires. The
+    // timeout is the schema's minimum — inside the tool's declared contract,
+    // and long enough that a slow spawn still prints the pid before it fires.
+    const res = (await (
+      await post(`${base}/api/agent/tools/execute_command`, {
+        branch: 'main',
+        command: 'sleep 30 & echo $!; wait',
+        timeout_ms: 1000,
+      })
+    ).json()) as { stdout: string; exitCode: number };
+    expect(res.exitCode).toBe(-1);
+    const grandchild = Number(res.stdout.trim());
+    expect(grandchild).toBeGreaterThan(0);
+    // Dead means killed, not reaped: a SIGKILLed process keeps its pid — and
+    // answers `kill(pid, 0)` as alive — until whoever inherited it reaps it,
+    // and on a host with no reaper (the very thing this guards) that is
+    // never. So where /proc exists, a zombie (`State: Z`) counts as dead; a
+    // vanished pid counts everywhere. Poll to a deadline rather than trust
+    // one fixed pause. Without the fix the grandchild is still sleeping at
+    // the deadline, so what fails is the deadline — never an early check.
+    const deadline = Date.now() + 3_000;
+    let dead = false;
+    while (!dead && Date.now() < deadline) {
+      dead = await isDeadOrZombie(grandchild);
+      if (!dead) await new Promise((r) => setTimeout(r, 50));
+    }
+    expect(dead).toBe(true);
+  });
+
   it('execute_command 400s when no branch is given AND no focused branch (external caller)', async () => {
     const base = await start();
     // No `branch` arg and no `ctx.focusedBranch` (an external caller carries no

package/src/modules/workspace/file-readers/extract-pdf.ts

@@ -64,12 +64,24 @@ export async function extractPdf(bytes: Buffer): Promise<ExtractResult> {
       message: `could not be extracted as a PDF (the file is ${bytes.length} bytes — over the ${MAX_DOC_PART_BYTES}-byte (50 MB) extraction limit)`,
     };
   }
-  let doc: Awaited<ReturnType<typeof openPdf>>;
+  // The loading TASK is what gets destroyed at the end, not the document:
+  // pdf.js 6 dropped `PDFDocumentProxy.destroy()`, and destroying the task
+  // frees the document (and its pages) with it — the shape the viewer uses.
+  let task: Awaited<ReturnType<typeof openPdf>>;
   try {
-    doc = await openPdf(bytes);
+    task = await openPdf(bytes);
   } catch (err) {
     return { ok: false, message: `could not be parsed as a PDF (${(err as Error).message})` };
   }
+  let doc: Awaited<typeof task.promise>;
+  try {
+    doc = await task.promise;
+  } catch (err) {
+    // A task exists even when the document never will (malformed, truncated):
+    // destroy it, or its worker-side state outlives every failed extraction.
+    await task.destroy().catch(() => undefined);
+    return { ok: false, message: `could not be parsed as a PDF (${(err as Error).message})` };
+  }
   try {
     if (doc.numPages > MAX_PDF_PAGES) {
       return {
@@ -151,7 +163,7 @@ export async function extractPdf(bytes: Buffer): Promise<ExtractResult> {
   } catch (err) {
     return { ok: false, message: `could not extract the PDF's text (${(err as Error).message})` };
   } finally {
-    await doc.destroy();
+    await task.destroy();
   }
 }
 
@@ -167,6 +179,8 @@ async function openPdf(bytes: Buffer) {
     throw err;
   });
   const { getDocument } = await pdfjsPromise;
+  // Returns the loading task; the caller awaits `.promise` for the document
+  // and destroys the task when done (see `extractPdf`).
   return getDocument({
     // Copy into a fresh Uint8Array: pdf.js TRANSFERS the buffer it is given
     // (detaching it), and the caller's Buffer must stay usable for hashing.
@@ -174,5 +188,5 @@ async function openPdf(bytes: Buffer) {
     // Server side: no font rendering — text content is all we consume.
     disableFontFace: true,
     useSystemFonts: true,
-  }).promise;
+  });
 }

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

@@ -1069,14 +1069,32 @@ export function registerWorkspaceTools(
           }
         : process.env;
       return new Promise((resolve) => {
-        const child = spawn(a.command as string, { cwd, shell: true, env });
+        // Own process group on POSIX, so a timeout or abort kills the WHOLE
+        // tree. `shell: true` puts an `sh` between us and the command; killing
+        // only that shell left whatever it had started running on — orphaned,
+        // unreaped, still holding the workspace and its memory. A self-hosted
+        // deployment leaked ~4,500 tasks that way before nothing could fork.
+        const detached = process.platform !== 'win32';
+        const child = spawn(a.command as string, { cwd, shell: true, env, detached });
         let stdout = '';
         let stderr = '';
-        const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
-        // If the caller disconnects (request aborted), kill the child instead of
+        const killTree = () => {
+          try {
+            if (detached && child.pid) process.kill(-child.pid, 'SIGKILL');
+            else child.kill('SIGKILL');
+          } catch {
+            try {
+              child.kill('SIGKILL');
+            } catch {
+              // Already gone.
+            }
+          }
+        };
+        const timer = setTimeout(killTree, timeoutMs);
+        // If the caller disconnects (request aborted), kill the tree instead of
         // letting it run to the timeout; the resulting `close`/`error` settles
         // the promise through `finish`.
-        const onAbort = () => child.kill('SIGKILL');
+        const onAbort = killTree;
         ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
         const finish = (value: unknown) => {
           clearTimeout(timer);