Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): make exec read-only at the filesystem, delete the spelling lists (#4077)
tim-inkeep11ba8997261d
diff --git a/.changeset/exec-glob-operands.md b/.changeset/exec-glob-operands.mdnew file mode 100644index 000000000..725b47f79--- /dev/null+++ b/.changeset/exec-glob-operands.md@@ -0,0 +1,15 @@+---+"@inkeep/open-knowledge": patch+---++Agent `exec` expands globs, and names the files it actually read.++`cat specs/*.md` reported `No such file or directory` for every command that takes file operands, so an agent reading a folder by pattern was told the files were not there. Every command with file operands was affected, `grep -rn needle *.md` and `find docs/*` included. Only a pattern the command matches itself, such as `find -name '*.md'`, was ever safe.++`exec` rebuilds each command before running it, so it can hide `node_modules` and the other noise directories from recursive searches. Rebuilding quoted every argument, and a quoted `specs/*.md` is a request for one file with a star in its name.++Patterns are now matched against the project before the command runs, and the files they matched are passed through as ordinary arguments. A pattern that matches nothing is left as written, the way a shell leaves it. Quoted patterns such as `find . -name '*.md'` are never expanded and keep being matched literally.++Two things improve alongside it. The referenced-file list now names the documents a pattern actually matched rather than the pattern itself, so `cat specs/*.md` reports both specs instead of one document that does not exist; the same correction applies to `ls` given several files. An argument a command reads as a pattern is left for the command to match: `find . -name '*.md'` still searches the whole tree, and `grep -rn PRD-* .` searches for the pattern rather than for whichever filename happens to match it. Everything a command reads as a path is expanded, including `find docs/*`. A pattern matching more paths than the tool will accept is refused with a suggestion to narrow it, rather than expanding without limit, and the matching stops at that limit rather than walking the whole project first. Expansion skips the same directories recursive searches skip, so `cat */*.md` never names a file under `node_modules`.++`grep -o` and `find -o` work again. Neither writes anything: `-o` asks grep to print only the matching part, and joins two conditions in find. They were refused because the flag was blocked for every command at once, and only `sort` ever wrote with it.diff --git a/.changeset/exec-read-only-by-construction.md b/.changeset/exec-read-only-by-construction.mdnew file mode 100644index 000000000..03aabfffa--- /dev/null+++ b/.changeset/exec-read-only-by-construction.md@@ -0,0 +1,13 @@+---+"@inkeep/open-knowledge": patch+---++Agent `exec` is read-only at the filesystem, not by a list of flags.++0.68.6 closed `sort -oimportant.md` by widening the flag guard. Such a list only ever holds the spellings someone thought of, and a command that only reads was still one unthought-of spelling away from replacing a document with no attribution and no history to restore from.++The filesystem `exec` runs against is now read-only, so a write fails whatever the command spells and the lists are gone. What replaces them is a message: an agent that tries to write is told it tried to write, and which file when the engine names it, rather than being handed a filesystem error. `find -exec`, `-execdir`, `-ok` and `-okdir` are still refused by name, because those run a second command rather than writing.++Two error categories move. `<`, `<&`, `<<<`, `>&` and `|&` no longer report `write_blocked`; since none of them writes a document they report `shell_construct_blocked`, with a message that points at `cat <file>` rather than at `write` or `edit`. `find -exec` and its three siblings move the same way, for the same reason.++One suite checks it. It runs every write and delete attempt we know of through the real pipeline, asserts the project is byte-identical afterwards, and records which layer stopped each one: the parser, the read-only filesystem, or an option this engine does not implement. One of its tests bypasses the command parser entirely, so it is the filesystem being tested and not a list.diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex 697adcd46..5e6fa8d1a 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -25,7 +25,7 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th## Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)-- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`; caveats in `references/linking.md`). **Read `ran` on successful `lint`/`audit` results to see which enabled source families were selected. A family absent from `ran` was not checked, and `[]` means no checks were selected at all.**+- **Reads** — `exec` (primary; `cat`/`ls`/`grep`/… on a read-only filesystem, plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`; caveats in `references/linking.md`). **Read `ran` on successful `lint`/`audit` results to see which enabled source families were selected. A family absent from `ran` was not checked, and `[]` means no checks were selected at all.**- **Writes** — four native CRUD verbs, polymorphic over `document` / `folder` / `template` / `skill` / `asset` (pass EXACTLY ONE target, nested under its address key): `write` (create/overwrite; `write({ skill: {…} })` authors a skill as a REAL folder at the project's default skill home — live immediately for that folder's agent), `edit` (body find/replace/frontmatter merge-patch; no asset), `delete` (remove), `move` (move/rename, rewrites referrers; a skill also takes `scope`/`toScope` for Project↔Global — history resets, re-`install`). Output mirrors the input key; the preview envelope (`previewUrl`, `warning`) stays top-level. Plus `install` (WHERE a `skill` lives: `add`/`remove` locations additively — editor ids, `agents`, or custom roots; `mode` + `convert` re-form ONLY the locations named; `source` moves the real folder. The source folder IS the skill — no "uninstall everywhere"; a skill dies only via `delete`), `import` (acquire a skill-dir into `add`'s locations; scripts never run), `checkpoint` (named version), and `restore_version` (roll back). A folder's frontmatter is open-shape and self-only (does NOT cascade); templates are what new docs start with.- **Conflicts** — `conflicts` (`kind: list|content`), `resolve_conflict` (write a resolution + commit; destructive). See `references/conflict-resolution.md`.@@ -38,8 +38,8 @@ Tools NOT in OK MCP (your host's): `preview_start`, `preview_screenshot`, `WebFe**Route every in-scope markdown read and write through OK's MCP tools — never your host's native file tools.** Native `Edit` / `sed` / direct `Write` on in-scope markdown bypasses the CRDT and loses agent attribution in the shadow repo; native reads skip frontmatter, backlinks, shadow-repo activity, and project git history that OK returns for every matched file. When this workspace has OpenKnowledge MCP configured, do **not** use native file tools on markdown paths inside the content directory. The ban covers every common rationalization:- **Native `Read` / `Grep` / `Glob` on in-scope `.md` / `.mdx`** — the original case.-- **`Bash ls` / `Bash find` / `Bash cat` on dirs containing in-scope markdown** — use `exec("ls -A …")` / `exec("find … -name '*.md'")` / `exec("cat …")`. Native returns bare names; `exec` returns frontmatter, backlink counts, and recent activity. `-A` shows hidden entries (`.ok/`, `.okignore`) without the `.`/`..` noise.-- **Glob patterns that target markdown** (`**/*.md`, `specs/**`, `reports/**`, `docs/**`) — use `exec` with `find` or `exec("ls -A <dir>")`.+- **`Bash ls` / `Bash find` / `Bash cat` on dirs containing in-scope markdown** — use `exec("ls -A …")` / `exec("find … -name '*.md'")` / `exec("cat …")`. Native returns bare names; `exec` adds frontmatter, backlinks, and recent activity. `-A` shows hidden entries without `.`/`..`.+- **Glob patterns that target markdown** — `exec` expands file operands (`cat specs/*.md`); quoted patterns and a command's own pattern (`find -name`) stay literal.- **Dispatching the Explore / general-purpose subagent for markdown-heavy exploration** — subagents use native tools internally and bypass OK. Do markdown exploration yourself via `exec` / `search`. Subagents remain appropriate for **source-code** exploration.- **Native `Read` / `Grep` on in-scope markdown inside `.ok/`** — `.ok/` is in-scope; treat its `.md` / `.mdx` like any other KB file.- **`ls` / `cat` / `find` on skill folders to discover or read a skill** — skills are addressed by `name`+`scope`, not by path (a skill can live in any editor dir, the `.agents/skills/` hub, or a custom root, with copies elsewhere). Use the `skills` tool.diff --git a/packages/server/package.json b/packages/server/package.jsonindex fc7ecb6e3..952efd741 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -49,7 +49,7 @@"ignore": "^5.3.2","ipaddr.js": "^2.3.0","jsonc-parser": "^3.3.1",- "just-bash": "^2.14.3",+ "just-bash": "~2.14.3","mermaid": "^11.14.0","mrmime": "^2.0.1","pino": "^10.3.1",@@ -71,9 +71,10 @@"scripts": {"build": "tsdown && pnpm run build:skill-bundles","build:skill-bundles": "tsx scripts/build-skill-bundles.ts",- "typecheck": "tsc --noEmit",+ "typecheck": "pnpm run typecheck:bash && tsc","test": "vitest run",- "measure:generated-index-sweep": "node --import tsx --conditions=development measure-generated-index-sweep.ts"+ "measure:generated-index-sweep": "node --import tsx --conditions=development measure-generated-index-sweep.ts",+ "typecheck:bash": "tsc -p tsconfig.bash.json"},"devDependencies": {"@types/mdast": "^4.0.4",diff --git a/packages/server/src/bash/argv-model-agreement.test.ts b/packages/server/src/bash/argv-model-agreement.test.tsnew file mode 100644index 000000000..4dd8ece5d--- /dev/null+++ b/packages/server/src/bash/argv-model-agreement.test.ts@@ -0,0 +1,70 @@+import { describe, expect, test } from 'vitest';+import { pathArgs } from './extract-paths.ts';+import { deriveScanRoots } from './mtime-scan.ts';+import { classifyArgs, parseCommand, type Stage } from './parse-command.ts';++function stageOf(command: string): Stage {+ const parsed = parseCommand(command);+ if ('error' in parsed) throw new Error(`expected '${command}' to parse: ${parsed.error.message}`);+ return parsed.stages[0];+}++const COMMANDS = [+ 'grep -m 5 needle notes.md',+ 'grep -e needle notes.md',+ 'grep -rn needle .',+ 'grep --include=*.md needle .',+ 'grep -A 2 needle notes.md',+ 'sort -k 2 notes.md',+ 'sort -t , notes.md',+ 'uniq -f 2 notes.md',+ 'uniq -w 3 notes.md',+ 'cut -d , -f 1 notes.md',+ 'cut -d, -f1 notes.md',+ 'find . -name *.md',+ 'find . -newer ref.md',+ 'find docs -maxdepth 2',+ 'head -n 5 notes.md',+ 'tail -c 20 notes.md',+ 'wc -l notes.md',+ 'cat -n notes.md',+ 'ls -la docs',+];++describe('one argv model, read by every consumer', () => {+ test.each(COMMANDS)('%s — the sweep never watches less than the extractor reports', (command) => {+ const stage = stageOf(command);+ const watched = deriveScanRoots([stage]);+ for (const path of pathArgs(stage)) expect(watched).toContain(path);+ });++ test.each(COMMANDS)('%s — no consumer invents a token', (command) => {+ const stage = stageOf(command);+ const typed = command.split(/\s+/);+ for (const value of [...pathArgs(stage), ...deriveScanRoots([stage])]) {+ expect(typed, `${command} produced "${value}"`).toContain(value);+ }+ });++ test('the sweep watches an unknown attached value that the extractor does not', () => {+ const stage = stageOf('sort --weird=out.md notes.md');+ expect(pathArgs(stage)).toEqual(['notes.md']);+ expect(deriveScanRoots([stage])).toContain('out.md');+ });++ test('a bundled switch is never read as a value', () => {+ expect(classifyArgs(stageOf('ls -la docs')).filter((a) => a.role === 'attached-value')).toEqual(+ [],+ );+ expect(+ classifyArgs(stageOf('grep -rn needle .')).filter((a) => a.role === 'attached-value'),+ ).toEqual([]);+ });++ test('a glued value on a flag that takes one is read as a value', () => {+ const glued = classifyArgs(stageOf('cut -d, -f1 notes.md')).filter(+ (a) => a.role === 'attached-value',+ );+ expect(glued.map((a) => a.value)).toEqual([',', '1']);+ });+});diff --git a/packages/server/src/bash/expand-globs.ts b/packages/server/src/bash/expand-globs.tsnew file mode 100644index 000000000..8a6581599--- /dev/null+++ b/packages/server/src/bash/expand-globs.ts@@ -0,0 +1,98 @@+import { glob } from 'node:fs/promises';+import { basename, isAbsolute } from 'node:path';+import {+ checkStage,+ classifyArgs,+ type GlobStage,+ type ParseCommandError,+ type Stage,+ WIKI_EXCLUDE_DIRS,+} from './parse-command.ts';++const EXPANDABLE_PATTERN_RE = /^[^-][\w.\-/*?[\]!^]*$/;++export const GLOB_EXPANSION_CAP = 1000;++const EXCLUDED = new Set(WIKI_EXCLUDE_DIRS);++type ExpandResult = { stages: Stage[] } | { error: ParseCommandError };++function expandableArgIndices(stage: Stage): ReadonlySet<number> {+ return new Set(+ classifyArgs(stage)+ .filter((a) => a.role === 'path')+ .map((a) => a.index),+ );+}++function overCap(arg: string, cap: number): ExpandResult {+ return {+ error: {+ category: 'shell_construct_blocked',+ message: `The pattern '${arg}' matches more than ${cap} paths. Narrow it to a subdirectory, or use 'find' or 'grep -r' to search.`,+ },+ };+}++export async function expandGlobStages(+ stages: GlobStage[],+ cwd: string,+ cap: number = GLOB_EXPANSION_CAP,+): Promise<ExpandResult> {+ const expanded: Stage[] = [];+ for (const stage of stages) {+ const globs = stage.globArgIndices;+ if (globs.length === 0) {+ expanded.push({ command: stage.command, args: stage.args });+ continue;+ }+ const expandable = expandableArgIndices(stage);+ const args: string[] = [];+ for (const [index, arg] of stage.args.entries()) {+ if (+ !globs.includes(index) ||+ !expandable.has(index) ||+ !EXPANDABLE_PATTERN_RE.test(arg) ||+ arg.includes('..') ||+ isAbsolute(arg)+ ) {+ args.push(arg);+ continue;+ }+ const matches: string[] = [];+ try {+ for await (const match of glob(arg, {+ cwd,+ exclude: (entry: unknown) => EXCLUDED.has(basename(String(entry))),+ })) {+ const m = String(match);+ if (isAbsolute(m) || m.startsWith('..')) continue;+ matches.push(m);+ if (matches.length > cap) return overCap(arg, cap);+ }+ } catch (error) {+ const code = (error as { code?: string }).code;+ return {+ error: {+ category: 'shell_construct_blocked',+ message:+ code === undefined+ ? `Could not expand the pattern '${arg}': ${error instanceof Error ? error.message : String(error)}. Quote it to match it literally.`+ : `Could not expand the pattern '${arg}': the walk failed with ${code}.`,+ },+ };+ }+ if (matches.length === 0) {+ args.push(arg);+ continue;+ }+ matches.sort();+ args.push(...matches);+ }+ const next: Stage = { command: stage.command, args };+ const stageError = checkStage(next);+ if (stageError) return { error: stageError };+ expanded.push(next);+ }+ return { stages: expanded };+}diff --git a/packages/server/src/bash/extract-paths.test.ts b/packages/server/src/bash/extract-paths.test.tsindex 6c02b2afe..3a41b024d 100644--- a/packages/server/src/bash/extract-paths.test.ts+++ b/packages/server/src/bash/extract-paths.test.ts@@ -41,6 +41,18 @@ describe('extractReferencedPaths — ls', () => {expect(paths).toEqual(['top.md']);});+ test('several directories: each `dir:` header prefixes the entries under it', () => {+ const stdout = 'docs:\napi.md\nauth.md\n\nspecs:\none.md\n';+ const paths = extractReferencedPaths(stdout, [stage('ls', 'docs', 'specs')]);+ expect(paths).toEqual(['docs', 'docs/api.md', 'docs/auth.md', 'specs', 'specs/one.md']);+ });++ test('a file and a directory: the file is bare, the directory section is prefixed', () => {+ const stdout = 'README.md\n\nspecs:\none.md\n';+ const paths = extractReferencedPaths(stdout, [stage('ls', 'README.md', 'specs')]);+ expect(paths).toEqual(['README.md', 'specs', 'specs/one.md']);+ });+test('`ls .` treated as no parent', () => {const paths = extractReferencedPaths('top.md\n', [stage('ls', '.')]);expect(paths).toEqual(['top.md']);diff --git a/packages/server/src/bash/extract-paths.ts b/packages/server/src/bash/extract-paths.tsindex 968d4f8df..2c3418ef1 100644--- a/packages/server/src/bash/extract-paths.ts+++ b/packages/server/src/bash/extract-paths.ts@@ -1,4 +1,4 @@-import type { Stage } from './parse-command.ts';+import { classifyArgs, type Stage } from './parse-command.ts';const PRODUCER_COMMANDS: ReadonlySet<string> = new Set(['cat', 'ls', 'grep', 'find']);@@ -21,23 +21,35 @@ export function argsOf(stage: Stage): string[] {return stage.args.slice(1);}-export function nonFlagArgs(args: string[]): string[] {- return args.filter((a) => !a.startsWith('-'));+export function pathArgs(stage: Stage): string[] {+ return classifyArgs(stage)+ .filter((a) => a.role === 'path')+ .map((a) => a.value);}function extractFromCat(stage: Stage): string[] {- return nonFlagArgs(argsOf(stage)).filter(isWikiPath);+ return pathArgs(stage).filter(isWikiPath);}function extractFromLs(stdout: string, stage: Stage): string[] {- const pathArgs = nonFlagArgs(argsOf(stage));- const baseDir = pathArgs.length > 0 ? pathArgs[pathArgs.length - 1] : '';- const prefix = baseDir && baseDir !== '.' ? normalize(baseDir) : '';+ const operands = pathArgs(stage);+ const fileArgs = operands.filter(isWikiPath);+ if (operands.length > 0 && fileArgs.length === operands.length) {+ return fileArgs.map((p) => normalize(p));+ }+ const only = operands.length === 1 ? operands[0] : '';+ let prefix = only && only !== '.' ? normalize(only) : '';const out: string[] = [];if (prefix) out.push(prefix);for (const line of stdout.split('\n')) {const name = line.trim();if (!name) continue;+ if (name.endsWith(':')) {+ const dir = normalize(name.slice(0, -1));+ prefix = dir === '.' ? '' : dir;+ if (prefix) out.push(prefix);+ continue;+ }if (/\.[a-z0-9]+$/i.test(name) && !isWikiPath(name)) continue;const path = prefix ? `${prefix}/${name}` : name;out.push(path);@@ -68,11 +80,11 @@ function extractFromFind(stdout: string): string[] {}function extractFromHeadTail(stage: Stage): string[] {- return nonFlagArgs(argsOf(stage)).filter(isWikiPath);+ return pathArgs(stage).filter(isWikiPath);}function headTailActsAsProducer(stage: Stage): boolean {- return nonFlagArgs(argsOf(stage)).length > 0;+ return pathArgs(stage).length > 0;}function fallback(stdout: string): string[] {diff --git a/packages/server/src/bash/index.test.ts b/packages/server/src/bash/index.test.tsindex e6a8893fa..f0f639cfb 100644--- a/packages/server/src/bash/index.test.ts+++ b/packages/server/src/bash/index.test.ts@@ -2,7 +2,37 @@ import { mkdirSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { afterAll, beforeAll, describe, expect, it } from 'vitest';-import { createBashInstance, execBash, StdoutOverflowError, shellEscape } from './index.ts';+import {+ createBashInstance,+ erofsTarget,+ execBash,+ StdoutOverflowError,+ shellEscape,+} from './index.ts';++describe('erofsTarget', () => {+ it('names the file from the engine refusal', () => {+ expect(+ erofsTarget("write: EROFS: read-only file system, open '/home/user/project/a.md'"),+ ).toEqual({+ blocked: true,+ target: 'a.md',+ });+ });++ it('reports a refusal the engine did not attach a file to', () => {+ expect(erofsTarget("sort: EROFS: read-only file system, write '<path>'")).toEqual({+ blocked: true,+ target: null,+ });+ });++ it('is not fooled by a read failure whose path contains EROFS', () => {+ expect(erofsTarget("cat: ENOENT: no such file or directory, open 'missing-EROFS.md'")).toEqual({+ blocked: false,+ });+ });+});describe('shellEscape', () => {it('leaves safe characters alone', () => {@@ -22,7 +52,7 @@ describe('shellEscape', () => {});});-describe('just-bash + ReadWriteFs (per-call cwd)', () => {+describe('just-bash + OverlayFs (per-call cwd)', () => {let root: string;beforeAll(() => {@@ -37,7 +67,7 @@ describe('just-bash + ReadWriteFs (per-call cwd)', () => {rmSync(root, { recursive: true, force: true });});- describe('ReadWriteFs sandbox boundary', () => {+ describe('OverlayFs sandbox boundary', () => {it('rejects path traversal via `..`', async () => {const bash = createBashInstance(root);const result = await execBash(bash, 'cat ../outside.txt');diff --git a/packages/server/src/bash/index.ts b/packages/server/src/bash/index.tsindex 8321b1900..abc910733 100644--- a/packages/server/src/bash/index.ts+++ b/packages/server/src/bash/index.ts@@ -5,10 +5,28 @@ import { isAbsolute, resolve } from 'node:path';* root fails containment on Windows. Keep the range in package.json at or above* it.*/-import { Bash, ReadWriteFs } from 'just-bash';+import { Bash, OverlayFs } from 'just-bash';const MAX_STDOUT_BYTES = 16 * 1024 * 1024;+const PROJECT_MOUNT = '/home/user/project';++export type ErofsCheck = { blocked: false } | { blocked: true; target: string | null };++export function erofsTarget(source: unknown): ErofsCheck {+ const message = source instanceof Error ? source.message : String(source);+ if (!message.includes('EROFS: read-only file system')) return { blocked: false };+ for (const match of message.matchAll(/'([^']+)'/g)) {+ const raw = match[1];+ if (raw === '<path>') continue;+ const rel = raw.startsWith(`${PROJECT_MOUNT}/`) ? raw.slice(PROJECT_MOUNT.length + 1) : raw;+ const clean = rel.startsWith('./') ? rel.slice(2) : rel;+ if (clean !== '' && clean !== '.' && clean !== PROJECT_MOUNT)+ return { blocked: true, target: clean };+ }+ return { blocked: true, target: null };+}+export { shellEscape } from './shell-escape.ts';interface ExecBashResult {@@ -35,8 +53,13 @@ export function createBashInstance(cwd: string): Bash {throw new Error(`createBashInstance: cwd must be absolute (got: ${cwd})`);}return new Bash({- cwd: '/',- fs: new ReadWriteFs({ root: resolve(cwd), allowSymlinks: false }),+ cwd: PROJECT_MOUNT,+ fs: new OverlayFs({+ root: resolve(cwd),+ mountPoint: PROJECT_MOUNT,+ allowSymlinks: false,+ readOnly: true,+ }),});}diff --git a/packages/server/src/bash/mtime-scan.test.ts b/packages/server/src/bash/mtime-scan.test.tsindex 1500c6172..7a0c13e1e 100644--- a/packages/server/src/bash/mtime-scan.test.ts+++ b/packages/server/src/bash/mtime-scan.test.ts@@ -60,6 +60,47 @@ function stage(...args: string[]): Stage {}describe('deriveScanRoots', () => {+ test.each([+ 'find -newer ref.md',+ 'find -anewer ref.md',+ 'find -cnewer ref.md',+ 'find -mtime 7',+ 'find -mmin 5',+ 'find -atime 3',+ 'find -amin 3',+ 'find -ctime 3',+ 'find -cmin 3',+ 'find -perm 644',+ 'find -links 2',+ 'find -inum 12345',+ 'find -user root',+ 'find -group staff',+ 'find -size 1k',+ 'find -type f',+ 'find -maxdepth 2',+ 'find -mindepth 1',+ ])('%s walks the tree, so the sweep watches all of it', (command) => {+ const args = command.split(/\s+/);+ expect(deriveScanRoots([stage(...args)])).toEqual([SCAN_WHOLE_TREE]);+ });++ test.each([+ ['grep -f pats*.txt', [SCAN_WHOLE_TREE]],+ ['sort -T logs* data.txt', [SCAN_WHOLE_TREE]],+ ['find docs -newer other/*.md', ['docs', 'other']],+ ])('%s — a glob a flag supplies is still swept', (command, expected) => {+ const args = command.split(/\s+/);+ expect(deriveScanRoots([stage(...args)]).sort()).toEqual([...expected].sort());+ });++ test('a flag value never narrows the sweep away from the whole tree', () => {+ expect(deriveScanRoots([stage('grep', '-r', '-f', 'pats.txt')])).toEqual([SCAN_WHOLE_TREE]);+ expect(deriveScanRoots([stage('find', '.', '-newer', 'ref.md')]).sort()).toEqual([+ '.',+ 'ref.md',+ ]);+ });+test('cat file operands become roots', () => {expect(deriveScanRoots([stage('cat', 'a.md', 'sub/b.md')]).sort()).toEqual(['a.md',diff --git a/packages/server/src/bash/mtime-scan.ts b/packages/server/src/bash/mtime-scan.tsindex 35c791cec..76ba7ae0a 100644--- a/packages/server/src/bash/mtime-scan.ts+++ b/packages/server/src/bash/mtime-scan.ts@@ -2,8 +2,13 @@ import type { Dirent } from 'node:fs';import { readdir, stat } from 'node:fs/promises';import { relative, resolve } from 'node:path';import { OK_DIR } from '@inkeep/open-knowledge-core';-import { argsOf, nonFlagArgs } from './extract-paths.ts';-import { isRecursiveGrepFlag, type Stage } from './parse-command.ts';+import { argsOf } from './extract-paths.ts';+import {+ attachedValueMayNamePath,+ classifyArgs,+ isRecursiveGrepFlag,+ type Stage,+} from './parse-command.ts';export const SCAN_CAP = 1000;@@ -28,6 +33,7 @@ interface SnapshotResult {}const GLOB_RE = /[*?[]/;+const NUMERIC_RE = /^[+-]?\d+$/;function literalDirPrefix(token: string): string {const idx = token.search(GLOB_RE);@@ -57,53 +63,29 @@ export function deriveScanRoots(stages: Stage[]): string[] {const roots = new Set<string>();for (const stage of stages) {const args = argsOf(stage);- const positional = nonFlagArgs(args);- let candidates: string[];- switch (stage.command) {- case 'grep': {- let patternViaFlag = false;- const patternValues = new Set<string>();- for (let i = 0; i < args.length; i++) {- const a = args[i];- if (a === '-e' || a === '--regexp') {- patternViaFlag = true;- const value = args[i + 1];- if (value !== undefined) patternValues.add(value);- } else if (a.startsWith('--regexp=')) {- patternViaFlag = true;- }- }- const operands = positional.filter((p) => !patternValues.has(p));- candidates = patternViaFlag ? operands : operands.slice(1);- if (candidates.length === 0 && args.some(isRecursiveGrepFlag)) {- roots.add(SCAN_WHOLE_TREE);- }- break;+ const classified = classifyArgs(stage);+ const paths = classified.filter((a) => a.role === 'path');+ const operands = paths.filter((a) => a.flag === undefined).map((a) => a.value);++ const ambiguous = classified+ .filter(+ (a) =>+ a.role === 'attached-value' &&+ a.flag !== undefined &&+ carriesPathValue(a.flag) &&+ attachedValueMayNamePath(stage.command, a.flag),+ )+ .map((a) => a.value)+ .filter((v) => v.length > 0 && !NUMERIC_RE.test(v) && !GLOB_RE.test(v) && !isScanBase(v));++ if (operands.length === 0) {+ const bare = stage.command === 'ls' || stage.command === 'find';+ if (bare || (stage.command === 'grep' && args.some(isRecursiveGrepFlag))) {+ roots.add(SCAN_WHOLE_TREE);}- case 'find': {- const firstFlag = args.findIndex((a) => a.startsWith('-'));- const pathRoots = firstFlag === -1 ? args : args.slice(0, firstFlag);- const predicateValues =- firstFlag === -1- ? []- : args.slice(firstFlag).filter((a) => !a.startsWith('-') && !GLOB_RE.test(a));- candidates = [...pathRoots, ...predicateValues];- if (pathRoots.length === 0) roots.add(SCAN_WHOLE_TREE);- break;- }- case 'ls': {- candidates = positional;- if (positional.length === 0) roots.add(SCAN_WHOLE_TREE);- break;- }- default:- candidates = positional;}- const attached = args- .filter((a) => a.startsWith('-') && a.length > 2 && carriesPathValue(a))- .map((a) => (a.includes('=') ? a.slice(a.indexOf('=') + 1) : a.slice(2)))- .filter((v) => v.length > 0 && !GLOB_RE.test(v) && !isScanBase(v));- for (const c of [...candidates, ...attached]) {++ for (const c of [...paths.map((a) => a.value), ...ambiguous]) {roots.add(GLOB_RE.test(c) ? literalDirPrefix(c) : c);}}diff --git a/packages/server/src/bash/parse-command.test.ts b/packages/server/src/bash/parse-command.test.tsindex f4734d49e..076d93f1e 100644--- a/packages/server/src/bash/parse-command.test.ts+++ b/packages/server/src/bash/parse-command.test.ts@@ -1,4 +1,10 @@-import { describe, expect, test } from 'vitest';+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { afterAll, describe, expect, test } from 'vitest';+import { expandGlobStages, GLOB_EXPANSION_CAP } from './expand-globs.ts';+import { extractReferencedPaths } from './extract-paths.ts';+import { createBashInstance, execBash } from './index.ts';import { augmentStagesWithExcludes, parseCommand, serializeStages } from './parse-command.ts';function expectOk(@@ -74,11 +80,30 @@ describe('parseCommand — unknown_command', () => {describe('parseCommand — write_blocked (redirection and write flags)', () => {test('`>` redirection', () => expectError('grep foo > out.txt', 'write_blocked'));test('`>>` append', () => expectError('cat a >> b', 'write_blocked'));- test('`<` input redirection', () => expectError('cat < file', 'write_blocked'));- test('sort -o output flag', () => expectError('sort -o out file', 'write_blocked'));- test('sort --output=file', () => expectError('sort --output=out file', 'write_blocked'));- test('find -delete', () => expectError('find . -name "*.md" -delete', 'write_blocked'));- test('find -fprint', () => expectError('find . -fprint out.txt', 'write_blocked'));+ test('`<` input redirection', () => expectError('cat < file', 'shell_construct_blocked'));++ test.each([+ '||',+ '&&',+ ';;',+ '|&',+ '<(',+ '<<<',+ '>>',+ '>&',+ '<&',+ '&',+ ';',+ '(',+ ')',+ '<',+ '>',+ ])('%s is classified, not left to the generic operator message', (op) => {+ const result = parseCommand(`cat a.md ${op} b.md`);+ expect('error' in result).toBe(true);+ if (!('error' in result)) return;+ expect(result.error.message).not.toMatch(/^Operator /);+ });test('find -exec rejected (via ; op token)', () =>expectError('find . -exec rm {} ;', 'shell_construct_blocked'));test('find -execdir rejected (via ; op token)', () =>@@ -226,9 +251,217 @@ describe('augmentStagesWithExcludes — pass-through', () => {}});- test('pipeline: only recursive grep stage is augmented', () => {+ test('pipeline: only recursive grep stage is augmented', async () => {const stages = augmentStagesWithExcludes(parse('grep -rn oauth . | head -5'));expect(stages[0].args).toContain('--exclude-dir=node_modules');expect(stages[1].args).toEqual(['head', '-5']);});});++describe('glob operands', () => {+ const created: string[] = [];+ afterAll(() => {+ for (const dir of created) rmSync(dir, { recursive: true, force: true });+ });++ function corpus(files: string[], dirs: string[] = []): string {+ const root = mkdtempSync(join(tmpdir(), 'glob-operands-'));+ created.push(root);+ for (const dir of dirs) mkdirSync(join(root, dir));+ for (const file of files) writeFileSync(join(root, file), 'data\n');+ return root;+ }++ async function pipeline(root: string, cmd: string) {+ const parsed = parseCommand(cmd);+ if ('error' in parsed) throw new Error(`Expected '${cmd}' to parse`);+ const expanded = await expandGlobStages(parsed.stages, root);+ if ('error' in expanded) return { blocked: expanded.error.message };+ const stages = augmentStagesWithExcludes(expanded.stages);+ return { stages, command: serializeStages(stages) };+ }++ async function run(root: string, cmd: string) {+ const step = await pipeline(root, cmd);+ if (step.blocked !== undefined)+ throw new Error(`expected ${cmd} to parse, got: ${step.blocked}`);+ const result = await execBash(createBashInstance(root), step.command);+ return {+ ...step,+ stdout: result.stdout,+ paths: extractReferencedPaths(result.stdout, step.stages),+ };+ }++ test('a glob operand is expanded to real files before the engine runs', async () => {+ const root = corpus(['specs/one.md', 'specs/two.md', 'top.md'], ['specs']);+ expect((await pipeline(root, 'cat specs/*.md')).command).toBe('cat specs/one.md specs/two.md');+ });++ test('a pattern matching nothing stays literal, as a shell leaves it', async () => {+ const root = corpus(['top.md']);+ expect((await pipeline(root, 'cat nomatch/*.md')).command).toBe("cat 'nomatch/*.md'");+ });++ test('every argument still reaches the engine quoted', async () => {+ const root = corpus(['top.md']);+ expect((await pipeline(root, 'cat *.md')).command).toBe('cat top.md');+ expect((await pipeline(root, "grep 'two words' top.md")).command).toBe(+ "grep 'two words' top.md",+ );+ });++ test('a filename the glob produced is escaped, not handed over raw', async () => {+ const root = corpus(['my notes.md', 'plain.md']);+ expect((await pipeline(root, 'cat *.md')).command).toBe("cat 'my notes.md' plain.md");+ });++ test('a pattern matching more than the cap is refused with a way forward', async () => {+ const root = corpus(Array.from({ length: 12 }, (_, index) => `f${index}.md`));+ const parsed = parseCommand('cat *.md');+ if ('error' in parsed) throw new Error('expected parse');+ const expanded = await expandGlobStages(parsed.stages, root, 5);+ if (!('error' in expanded)) throw new Error('expected the cap to refuse 12 matches against 5');+ expect(expanded.error.message).toContain('more than 5 paths');+ expect(expanded.error.message).toMatch(/narrow/i);+ });++ test('at or under the cap the command is expanded normally', async () => {+ const root = corpus(Array.from({ length: 5 }, (_, index) => `f${index}.md`));+ const parsed = parseCommand('cat *.md');+ if ('error' in parsed) throw new Error('expected parse');+ const expanded = await expandGlobStages(parsed.stages, root, 5);+ if ('error' in expanded) throw new Error('expected 5 matches to pass a cap of 5');+ expect(expanded.stages[0].args).toHaveLength(6);+ });++ test('expansion never names what every other exec surface hides', async () => {+ const root = corpus(+ ['top.md', 'node_modules/dep/readme.md', 'dist/out.md'],+ ['node_modules', 'node_modules/dep', 'dist'],+ );+ const step = await pipeline(root, 'cat **/*.md');+ if (step.blocked !== undefined) throw new Error(step.blocked);+ expect(step.stages[0].args).toEqual(['cat', 'top.md']);+ });++ test('the shipped cap is what production uses', () => {+ expect(GLOB_EXPANSION_CAP).toBe(1000);+ });++ test('an absolute pattern is passed through literally, never expanded', async () => {+ const root = corpus(['top.md']);+ expect((await pipeline(root, 'cat /etc/*.conf')).command).toBe("cat '/etc/*.conf'");+ expect((await pipeline(root, 'cat /*.md')).command).toBe("cat '/*.md'");+ });++ test.each([+ ['grep -rn --include *.md needle .', "--include '*.md'"],+ ['grep -rn --include=*.md needle .', "'--include=*.md'"],+ ['grep --exclude-dir *.md needle .', "--exclude-dir '*.md'"],+ ['grep --exclude *.md needle .', "--exclude '*.md'"],+ ])('%s leaves the glob for grep to match', async (cmd, expected) => {+ const root = corpus(['PRD-1.md', 'notes.md']);+ expect((await pipeline(root, cmd)).command).toContain(expected);+ });++ test('a glob in a flag value slot is not expanded into file operands', async () => {+ const root = corpus(['a.md', 'b.md']);+ expect((await pipeline(root, 'uniq -f *')).command).toBe("uniq -f '*'");+ expect((await pipeline(root, 'sort -k * a.md')).command).toBe("sort -k '*' a.md");+ });++ test('a flag that supplies grep its patterns does not reserve a positional', async () => {+ const root = corpus(['PRD-1.md', 'notes.md', 'pats.txt']);+ expect((await pipeline(root, 'grep -f pats.txt *.md')).command).toBe(+ 'grep -f pats.txt PRD-1.md notes.md',+ );+ expect((await pipeline(root, 'grep --file=pats.txt *.md')).command).toBe(+ "grep '--file=pats.txt' PRD-1.md notes.md",+ );+ });++ test('find keeps its own pattern matching instead of expanding first', async () => {+ const root = corpus(['top.md', 'deep/nested.md'], ['deep']);+ expect((await pipeline(root, 'find . -name *.md')).command).toContain("-name '*.md'");+ });++ test('a quoted pattern is never expanded and is matched literally', async () => {+ const root = corpus(['specs/one.md'], ['specs']);+ expect((await pipeline(root, "find . -name '*.md'")).command).toContain("-name '*.md'");+ });++ test('the engine returns the globbed files', async () => {+ const root = corpus(['specs/one.md', 'specs/two.md'], ['specs']);+ expect((await run(root, 'cat specs/*.md')).stdout).toBe('data\ndata\n');+ });++ test('enrichment names the real files, not the pattern', async () => {+ const root = corpus(['specs/one.md', 'specs/two.md'], ['specs']);+ expect((await run(root, 'cat specs/*.md')).paths).toEqual(['specs/one.md', 'specs/two.md']);+ expect((await run(root, 'ls specs/*.md')).paths).toEqual(['specs/one.md', 'specs/two.md']);+ });++ test('brace expansion cannot smuggle a denied flag past the allowlist', async () => {+ const root = corpus(['k1.md', 'k2.md']);+ const before = readdirSync(root).sort();+ const result = await run(root, 'find {*,-delete}');+ expect(result.command).toContain("'{*,-delete}'");+ expect(readdirSync(root).sort()).toEqual(before);+ });+});++describe('find flags that run another command', () => {+ test.each([+ '-exec',+ '-execdir',+ '-ok',+ '-okdir',+ ])('find %s is refused by the parser, since it runs a command the allowlist never sees', (flag) =>+ expectError(`find . ${flag} rm {} +`, 'shell_construct_blocked'));+});++describe('a flag value is not a positional', () => {+ const dirs: string[] = [];+ afterAll(() => {+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });+ });++ function corpus(files: string[]): string {+ const root = mkdtempSync(join(tmpdir(), 'positional-'));+ dirs.push(root);+ for (const file of files) writeFileSync(join(root, file), 'data\n');+ return root;+ }++ async function serialize(root: string, cmd: string): Promise<string> {+ const parsed = parseCommand(cmd);+ if ('error' in parsed) throw new Error(`expected '${cmd}' to parse: ${parsed.error.message}`);+ const expanded = await expandGlobStages(parsed.stages, root);+ if ('error' in expanded) throw new Error(`expected '${cmd}' to expand`);+ return serializeStages(expanded.stages);+ }++ test.each([+ 'uniq -f 2 notes.md',+ 'uniq -s 1 notes.md',+ 'uniq -w 3 notes.md',+ 'uniq -c notes.md',+ 'sort -k 2 notes.md',+ 'sort -t , notes.md',+ ])('%s reads its flag value as a value, not an operand', (command) => {+ expect('error' in parseCommand(command)).toBe(false);+ });++ test("grep's pattern is the first positional, not the first non-flag token", async () => {+ const root = corpus(['PRD-1.md', 'notes.md']);+ expect(await serialize(root, 'grep -m 5 PRD-* .')).toContain("'PRD-*'");+ expect(await serialize(root, 'grep -A 2 PRD-* .')).toContain("'PRD-*'");+ expect(await serialize(root, 'grep PRD-* .')).toContain("'PRD-*'");+ });++ test('an explicit -e pattern leaves the positionals free to expand', async () => {+ const root = corpus(['PRD-1.md', 'notes.md']);+ expect(await serialize(root, 'grep -e PRD-1 *.md')).toBe('grep -e PRD-1 PRD-1.md notes.md');+ });+});diff --git a/packages/server/src/bash/parse-command.ts b/packages/server/src/bash/parse-command.tsindex 78e7fa1eb..3d39305a6 100644--- a/packages/server/src/bash/parse-command.ts+++ b/packages/server/src/bash/parse-command.ts@@ -10,7 +10,7 @@ export type ErrorCategory =| 'output_overflow'| 'security_invariant_violation';-interface ParseCommandError {+export interface ParseCommandError {category: ErrorCategory;message: string;}@@ -20,9 +20,13 @@ export interface Stage {args: string[];}-type ParseResult = { stages: Stage[] } | { error: ParseCommandError };+export interface GlobStage extends Stage {+ globArgIndices: readonly number[];+}++type ParseResult = { stages: GlobStage[] } | { error: ParseCommandError };-const WIKI_EXCLUDE_DIRS: readonly string[] = [+export const WIKI_EXCLUDE_DIRS: readonly string[] = ['node_modules','.git','dist',@@ -102,6 +106,174 @@ export function serializeStages(stages: Stage[]): string {return stages.map((s) => s.args.map(shellEscape).join(' ')).join(' | ');}+const FIND_PATTERN_FLAGS: ReadonlySet<string> = new Set([+ '-name',+ '-iname',+ '-path',+ '-ipath',+ '-regex',+ '-iregex',+ '-lname',+ '-ilname',+]);++const PATH_VALUE_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {+ find: new Set(['-newer', '-anewer', '-cnewer']),+ grep: new Set(['-f', '--file']),+ sort: new Set(['-o', '-T', '--output', '--temporary-directory']),+};++const VALUE_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {+ grep: new Set([+ '-m',+ '-A',+ '-B',+ '-C',+ '-e',+ '-f',+ '-d',+ '-D',+ '--regexp',+ '--file',+ '--max-count',+ '--after-context',+ '--before-context',+ '--context',+ '--include',+ '--exclude',+ '--exclude-dir',+ ]),+ uniq: new Set(['-f', '-s', '-w', '--skip-fields', '--skip-chars', '--check-chars']),+ sort: new Set(['-k', '-t', '-o', '-S', '-T', '--key', '--field-separator', '--output']),+ cut: new Set(['-d', '-f', '-b', '-c', '--delimiter', '--fields', '--bytes', '--characters']),+ head: new Set(['-n', '-c', '--lines', '--bytes']),+ tail: new Set(['-n', '-c', '--lines', '--bytes']),+ wc: new Set([]),+ find: new Set([+ ...FIND_PATTERN_FLAGS,+ '-newer',+ '-anewer',+ '-cnewer',+ '-type',+ '-maxdepth',+ '-mindepth',+ '-size',+ '-mtime',+ '-mmin',+ '-atime',+ '-amin',+ '-ctime',+ '-cmin',+ '-perm',+ '-links',+ '-inum',+ '-user',+ '-group',+ ]),+};++type ArgRole = 'command' | 'flag' | 'flag-value' | 'attached-value' | 'pattern' | 'path';++export interface ClassifiedArg {+ index: number;+ value: string;+ role: ArgRole;+ flag?: string;+}++function attachedValueOf(command: string, arg: string): { flag: string; value: string } | null {+ if (!arg.startsWith('-')) return null;+ const takesValue = VALUE_FLAGS[command] ?? new Set<string>();+ const eq = arg.indexOf('=');+ if (eq > 0) return { flag: arg.slice(0, eq), value: arg.slice(eq + 1) };+ if (arg.startsWith('--')) return null;+ for (let cut = arg.length - 1; cut >= 2; cut--) {+ const flag = arg.slice(0, cut);+ if (takesValue.has(flag)) return { flag, value: arg.slice(cut) };+ }+ return null;+}++export function attachedValueMayNamePath(command: string, flag: string): boolean {+ if (PATH_VALUE_FLAGS[command]?.has(flag) === true) return true;+ return VALUE_FLAGS[command]?.has(flag) !== true;+}++function suppliesPattern(command: string, flag: string): boolean {+ if (command === 'grep') return GREP_PATTERN_SUPPLIED_BY_FLAGS.has(flag);+ return false;+}++export function classifyArgs(stage: Stage): ClassifiedArg[] {+ const takesValue = VALUE_FLAGS[stage.command] ?? new Set<string>();+ const patternFlags =+ stage.command === 'find'+ ? FIND_PATTERN_FLAGS+ : stage.command === 'grep'+ ? GREP_GLOB_PROTECTED_FLAGS+ : new Set<string>();+ const out: ClassifiedArg[] = [{ index: 0, value: stage.args[0], role: 'command' }];+ let sawExplicitPattern = false;++ for (let i = 1; i < stage.args.length; i++) {+ const value = stage.args[i];+ if (value === '--') {+ out.push({ index: i, value, role: 'flag' });+ for (let j = i + 1; j < stage.args.length; j++) {+ out.push({ index: j, value: stage.args[j], role: 'path' });+ }+ break;+ }+ if (takesValue.has(value)) {+ out.push({ index: i, value, role: 'flag' });+ if (i + 1 < stage.args.length) {+ const isPattern = patternFlags.has(value);+ if (suppliesPattern(stage.command, value)) sawExplicitPattern = true;+ const namesPath = PATH_VALUE_FLAGS[stage.command]?.has(value) === true;+ out.push({+ index: i + 1,+ value: stage.args[i + 1],+ role: isPattern ? 'pattern' : namesPath ? 'path' : 'flag-value',+ flag: value,+ });+ i += 1;+ }+ continue;+ }+ const attached = attachedValueOf(stage.command, value);+ if (attached !== null) {+ if (suppliesPattern(stage.command, attached.flag)) sawExplicitPattern = true;+ out.push({ index: i, value: attached.value, role: 'attached-value', flag: attached.flag });+ continue;+ }+ if (value.startsWith('-') && value !== '-') {+ out.push({ index: i, value, role: 'flag' });+ continue;+ }+ out.push({ index: i, value, role: 'path' });+ }++ if (stage.command === 'grep' && !sawExplicitPattern) {+ const first = out.find((a) => a.role === 'path');+ if (first !== undefined) first.role = 'pattern';+ }+ return out;+}++const GREP_GLOB_PROTECTED_FLAGS: ReadonlySet<string> = new Set([+ '-e',+ '--regexp',+ '--include',+ '--exclude',+ '--exclude-dir',+]);+const GREP_PATTERN_SUPPLIED_BY_FLAGS: ReadonlySet<string> = new Set([+ '-e',+ '--regexp',+ '-f',+ '--file',+]);+const ALLOWLIST: ReadonlySet<string> = new Set(['cat','ls',@@ -117,7 +289,9 @@ const ALLOWLIST: ReadonlySet<string> = new Set([const ALLOWLIST_HINT = 'cat, ls, grep, find, head, tail, wc, sort, uniq, cut';-const WRITE_OPS: ReadonlySet<string> = new Set(['>', '>>', '<', '>&', '<&', '|&']);+const WRITE_OPS: ReadonlySet<string> = new Set(['>', '>>']);++const REDIRECT_OPS: ReadonlySet<string> = new Set(['<', '<&', '<<<', '>&', '|&']);const SHELL_CONSTRUCT_OPS: ReadonlySet<string> = new Set(['&',@@ -133,21 +307,7 @@ const SHELL_CONSTRUCT_OPS: ReadonlySet<string> = new Set(['<<-',]);-const UNIVERSAL_FLAG_DENY: ReadonlySet<string> = new Set(['-o', '--output-file', '--output']);-const UNIVERSAL_FLAG_PREFIX_DENY = ['--output-file=', '--output='];-const SORT_OUTPUT_FLAG_RE = /^-[a-zA-Z]*o/;--const FIND_FLAG_DENY: ReadonlySet<string> = new Set([- '-exec',- '-execdir',- '-delete',- '-fprint',- '-fprintf',- '-fprint0',- '-fls',- '-ok',- '-okdir',-]);+const FIND_EXEC_DENY: ReadonlySet<string> = new Set(['-exec', '-execdir', '-ok', '-okdir']);const SUSPICIOUS_STRING_RE = /[`]|\$\(|\$\{|\$'/;@@ -170,6 +330,12 @@ function opTokenError(token: ShellOpToken): ParseCommandError {message: `Write operation blocked: '${op}'. exec is read-only. For document changes, use the \`write\` or \`edit\` tool.`,};}+ if (REDIRECT_OPS.has(op)) {+ return {+ category: 'shell_construct_blocked',+ message: `Redirection '${op}' is not available — exec runs ONE command or a pipe (|), not a shell. To read a file, pass it as an argument (\`cat notes.md\`). To change a document, use the \`write\` or \`edit\` tool.`,+ };+ }if (SHELL_CONSTRUCT_OPS.has(op)) {return {category: 'shell_construct_blocked',@@ -182,8 +348,11 @@ function opTokenError(token: ShellOpToken): ParseCommandError {};}-function buildStageArgs(tokens: ShellToken[]): { args: string[] } | { error: ParseCommandError } {+function buildStageArgs(+ tokens: ShellToken[],+): { args: string[]; globIndices: number[] } | { error: ParseCommandError } {const args: string[] = [];+ const globIndices: number[] = [];for (const token of tokens) {if (typeof token === 'string') {if (SUSPICIOUS_STRING_RE.test(token)) {@@ -203,6 +372,7 @@ function buildStageArgs(tokens: ShellToken[]): { args: string[] } | { error: Par};}if (token.op === 'glob' && typeof token.pattern === 'string') {+ globIndices.push(args.length);args.push(token.pattern);continue;}@@ -216,10 +386,10 @@ function buildStageArgs(tokens: ShellToken[]): { args: string[] } | { error: Par}return { error: opTokenError(token) };}- return { args };+ return { args, globIndices };}-function checkStage(stage: Stage): ParseCommandError | null {+export function checkStage(stage: Stage): ParseCommandError | null {if (!ALLOWLIST.has(stage.command)) {return {category: 'unknown_command',@@ -227,20 +397,10 @@ function checkStage(stage: Stage): ParseCommandError | null {};}for (const arg of stage.args.slice(1)) {- if (- UNIVERSAL_FLAG_DENY.has(arg) ||- UNIVERSAL_FLAG_PREFIX_DENY.some((p) => arg.startsWith(p)) ||- (stage.command === 'sort' && SORT_OUTPUT_FLAG_RE.test(arg))- ) {- return {- category: 'write_blocked',- message: `Write operation blocked: '${arg}'. exec is read-only. For document changes, use the \`write\` or \`edit\` tool.`,- };- }- if (stage.command === 'find' && FIND_FLAG_DENY.has(arg)) {+ if (stage.command === 'find' && FIND_EXEC_DENY.has(arg)) {return {- category: 'write_blocked',- message: `find flag '${arg}' is blocked (executes commands or deletes files). Use exec for read-only discovery; chain with another allowlisted tool via '|' if you need to transform output.`,+ category: 'shell_construct_blocked',+ message: `find flag '${arg}' is blocked (it runs another command). Use exec for read-only discovery; chain with another allowlisted tool via '|' if you need to transform output.`,};}}@@ -279,7 +439,7 @@ export function parseCommand(commandStr: string): ParseResult {}stagesTokens.push(current);- const stages: Stage[] = [];+ const stages: GlobStage[] = [];for (const tokens of stagesTokens) {const result = buildStageArgs(tokens);if ('error' in result) return result;@@ -291,7 +451,11 @@ export function parseCommand(commandStr: string): ParseResult {},};}- const stage: Stage = { command: result.args[0], args: result.args };+ const stage: GlobStage = {+ command: result.args[0],+ args: result.args,+ globArgIndices: result.globIndices,+ };const stageError = checkStage(stage);if (stageError) return { error: stageError };stages.push(stage);diff --git a/packages/server/src/bash/read-only-contract.test.ts b/packages/server/src/bash/read-only-contract.test.tsindex e23cff0ed..73d5367d8 100644--- a/packages/server/src/bash/read-only-contract.test.ts+++ b/packages/server/src/bash/read-only-contract.test.ts@@ -2,7 +2,8 @@ import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSynimport { tmpdir } from 'node:os';import { join, relative } from 'node:path';import { afterAll, describe, expect, test } from 'vitest';-import { createBashInstance, execBash } from './index.ts';+import { expandGlobStages } from './expand-globs.ts';+import { createBashInstance, erofsTarget, execBash } from './index.ts';import { deriveScanRoots } from './mtime-scan.ts';import { augmentStagesWithExcludes, parseCommand, serializeStages } from './parse-command.ts';@@ -19,6 +20,7 @@ function build(): string {writeFileSync(join(root, 'other.md'), 'zzz\naaa\n');writeFileSync(join(root, 'specs/one.md'), 'ONE\n');writeFileSync(join(root, '-delete'), 'flag-shaped filename\n');+ writeFileSync(join(root, '-o'), 'flag-shaped filename\n');return root;}@@ -33,125 +35,135 @@ function snapshot(dir: string, root = dir): string[] {.sort();}-type Disposition = 'parse-blocked' | 'ran' | 'exec-threw';--interface Attempt {- command: string;- expect: Disposition;- category?: string;-}+type Disposition = 'parse-blocked' | 'fs-refused' | 'engine-rejected' | 'ran' | 'exec-threw';async function attempt(root: string,command: string,-): Promise<{ disposition: Disposition; category?: string }> {+): Promise<{ disposition: Disposition; category?: string; stderr?: string }> {const parsed = parseCommand(command);if ('error' in parsed) return { disposition: 'parse-blocked', category: parsed.error.category };+ const expanded = await expandGlobStages(parsed.stages, root);+ if ('error' in expanded)+ return { disposition: 'parse-blocked', category: expanded.error.category };try {- const effective = serializeStages(augmentStagesWithExcludes(parsed.stages));- await execBash(createBashInstance(root), effective);+ const effective = serializeStages(augmentStagesWithExcludes(expanded.stages));+ const result = await execBash(createBashInstance(root), effective);+ if (erofsTarget(result.stderr).blocked) return { disposition: 'fs-refused' };+ if (result.exitCode !== 0) return { disposition: 'engine-rejected', stderr: result.stderr };return { disposition: 'ran' };- } catch {- return { disposition: 'exec-threw' };+ } catch (error) {+ return { disposition: erofsTarget(error).blocked ? 'fs-refused' : 'exec-threw' };}}-const WRITE_ATTEMPTS: Attempt[] = [- { command: 'sort -o important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },- {- command: 'sort --output important.md other.md',- expect: 'parse-blocked',- category: 'write_blocked',- },- {- command: 'sort --output-file important.md other.md',- expect: 'parse-blocked',- category: 'write_blocked',- },- { command: 'sort -o=important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'sort -oimportant.md other.md', expect: 'parse-blocked', category: 'write_blocked' },- {- command: 'sort -r -o important.md other.md',- expect: 'parse-blocked',- category: 'write_blocked',- },- { command: 'sort -ro important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },- {- command: 'sort -nro important.md other.md',- expect: 'parse-blocked',- category: 'write_blocked',- },- { command: 'sort -uo important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },- {- command: 'sort -o important.md -r other.md',- expect: 'parse-blocked',- category: 'write_blocked',- },- { command: 'find . -delete', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -name *.md -delete', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -exec rm {} +', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -execdir rm {} +', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -ok rm {} +', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -okdir rm {} +', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -fprint important.md', expect: 'parse-blocked', category: 'write_blocked' },- {- command: 'find . -fprintf important.md %p',- expect: 'parse-blocked',- category: 'write_blocked',- },- { command: 'find . -fls important.md', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'find . -exec rm {} ;', expect: 'parse-blocked', category: 'shell_construct_blocked' },- {- command: 'find . -execdir rm {} ;',- expect: 'parse-blocked',- category: 'shell_construct_blocked',- },- { command: 'find . -ok rm {} ;', expect: 'parse-blocked', category: 'shell_construct_blocked' },- { command: 'cat other.md > important.md', expect: 'parse-blocked', category: 'write_blocked' },- { command: 'cat other.md >> important.md', expect: 'parse-blocked', category: 'write_blocked' },- {- command: 'cat other.md | tee important.md',- expect: 'parse-blocked',- category: 'unknown_command',- },- {- command: 'cut -f1 other.md -o important.md',- expect: 'parse-blocked',- category: 'write_blocked',- },- {- command: 'sort other.md `rm important.md`',- expect: 'parse-blocked',- category: 'shell_construct_blocked',- },- {- command: 'sort other.md $(rm important.md)',- expect: 'parse-blocked',- category: 'shell_construct_blocked',- },- { command: 'find {*,-delete}', expect: 'ran' },- { command: 'find {.,-delete}', expect: 'ran' },- { command: 'find *', expect: 'ran' },- { command: 'uniq other.md important.md', expect: 'ran' },+const PARSER_MUST_REFUSE: Array<[string, string]> = [+ ['find . -exec rm {} +', 'shell_construct_blocked'],+ ['find . -execdir rm {} +', 'shell_construct_blocked'],+ ['find . -ok rm {} +', 'shell_construct_blocked'],+ ['find . -okdir rm {} +', 'shell_construct_blocked'],+ ['find . -exec rm {} ;', 'shell_construct_blocked'],+ ['find . -execdir rm {} ;', 'shell_construct_blocked'],+ ['find . -ok rm {} ;', 'shell_construct_blocked'],+ ['cat other.md > important.md', 'write_blocked'],+ ['cat other.md >> important.md', 'write_blocked'],+ ['cat other.md > /tmp/escaped.md', 'write_blocked'],+ ['cat other.md | tee important.md', 'unknown_command'],+ ['sort other.md `rm important.md`', 'shell_construct_blocked'],+ ['sort other.md $(rm important.md)', 'shell_construct_blocked'],+];++const FILESYSTEM_MUST_REFUSE: string[] = [+ 'sort -o important.md other.md',+ 'sort --output important.md other.md',+ 'sort -o=important.md other.md',+ 'sort -oimportant.md other.md',+ 'sort -r -o important.md other.md',+ 'sort -o important.md -r other.md',+ 'sort -o /tmp/escaped.md other.md',+ 'sort -o ../escaped.md other.md',+ 'find . -delete',+ 'find . -name *.md -delete',+ 'find / -delete',+ 'find *',+];++const ENGINE_DOES_NOT_IMPLEMENT: string[] = [+ 'sort --output-file important.md other.md',+ 'sort -ro important.md other.md',+ 'sort -nro important.md other.md',+ 'sort -uo important.md other.md',+ 'find . -fprint important.md',+ 'find . -fprintf important.md %p',+ 'find . -fls important.md',+ 'cut -f1 other.md -o important.md',+ 'find {*,-delete}',+ 'find {.,-delete}',+ 'sort *',+];++const INERT_UNDER_THIS_ENGINE: string[] = [+ 'sort *.md',+ 'uniq *.md',+ 'uniq other.md important.md',+ 'uniq -- -delete important.md',];describe('exec is read-only — no allowlisted command may alter the tree', () => {+ test('the filesystem refuses a write the parser never sees', async () => {+ const root = build();+ const before = snapshot(root);+ const bash = createBashInstance(root);+ await expect(execBash(bash, 'cat other.md > important.md')).rejects.toThrow(/EROFS/);+ expect(snapshot(root)).toEqual(before);+ });++ test.each(PARSER_MUST_REFUSE)('%s is refused by the parser as %s', async (command, category) => {+ const root = build();+ const before = snapshot(root);+ expect(await attempt(root, command)).toEqual({ disposition: 'parse-blocked', category });+ expect(snapshot(root)).toEqual(before);+ });++ test.each(FILESYSTEM_MUST_REFUSE)('%s reaches the filesystem and it refuses', async (command) => {+ const root = build();+ const before = snapshot(root);+ expect(await attempt(root, command)).toEqual({ disposition: 'fs-refused' });+ expect(snapshot(root)).toEqual(before);+ });+test.each(- WRITE_ATTEMPTS,- )('$command is refused at the layer that owns it and changes nothing', async ({- command,- expect: expected,- category,- }) => {+ ENGINE_DOES_NOT_IMPLEMENT,+ )('%s dies on an option just-bash does not implement, which is not the mount', async (command) => {const root = build();const before = snapshot(root);const result = await attempt(root, command);- expect(result.disposition).toBe(expected);- if (category !== undefined) expect(result.category).toBe(category);+ expect(result.disposition).toBe('engine-rejected');+ expect(result.stderr).toMatch(+ /invalid option|unrecognized option|unknown predicate|No such file/,+ );+ expect(snapshot(root)).toEqual(before);+ });++ test.each(+ INERT_UNDER_THIS_ENGINE,+ )('%s runs to completion because this engine never writes for it', async (command) => {+ const root = build();+ const before = snapshot(root);+ expect(await attempt(root, command)).toEqual({ disposition: 'ran' });+ expect(snapshot(root)).toEqual(before);+ });++ test('expansion can hand sort a genuine -o, and the filesystem refuses it', async () => {+ const root = build();+ rmSync(join(root, '-delete'));+ rmSync(join(root, 'specs'), { recursive: true });+ const before = snapshot(root);+ expect(await attempt(root, 'sort *')).toEqual({ disposition: 'fs-refused' });expect(snapshot(root)).toEqual(before);});- test('the write guard and the mtime backstop read an attached value the same way', () => {+ test('the mtime backstop reads an attached value as a path', () => {const roots = deriveScanRoots([{ command: 'sort', args: ['sort', '-onotes', 'other.md'] }]);expect(roots).toContain('notes');});@@ -169,8 +181,10 @@ describe('exec is read-only — no allowlisted command may alter the tree', () =});});-describe('the write guard does not reach commands whose -o only reads', () => {+describe('a read-only -o parses for every command that has one', () => {test.each([+ 'grep -o needle other.md',+ 'find . -name a.md -o -name b.md','grep -oE PRD-[0-9]+ other.md','grep -on needle other.md','grep -orn needle .',diff --git a/packages/server/src/mcp/tools/exec.test.ts b/packages/server/src/mcp/tools/exec.test.tsindex 33eac19be..fd8f2940c 100644--- a/packages/server/src/mcp/tools/exec.test.ts+++ b/packages/server/src/mcp/tools/exec.test.ts@@ -1,4 +1,4 @@-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { resolve } from 'node:path';@@ -340,6 +340,22 @@ describe('exec — stdout provenance headers', () => {expect(files.some((f) => f.path === 'articles/auth.md')).toBe(true);});+ test('`cat X | head -n 2` — a separated flag value does not elect head as producer', async () => {+ const project = await bootstrap();+ const contentDir = resolve(project, 'articles');+ mkdirSync(contentDir, { recursive: true });+ writeFileSync(resolve(contentDir, 'auth.md'), 'line 1\nline 2\nline 3\n');++ const result = (await buildExecResult(+ { command: 'cat articles/auth.md | head -n 2' },+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },+ )) as ExecResult;++ const s = structured(result);+ expect(s.text).toContain('==> articles/auth.md <==\n');+ expect(fileEntries(s).some((f) => f.path === 'articles/auth.md')).toBe(true);+ });+test('`cat X | head -5` — cat header wins, head is a trimmer', async () => {const project = await bootstrap();const contentDir = resolve(project, 'articles');@@ -356,6 +372,30 @@ describe('exec — stdout provenance headers', () => {});});+describe('exec — a refused write reads as a refused write', () => {+ test.each([+ ['sort -oarticles/auth.md articles/auth.md', ''],+ ['sort -o articles/auth.md articles/auth.md', ''],+ ['find . -delete', 'articles/auth.md'],+ ])('%s is reported as write_blocked, naming the file', async (command, named) => {+ const project = await bootstrap();+ const contentDir = resolve(project, 'articles');+ mkdirSync(contentDir, { recursive: true });+ writeFileSync(resolve(contentDir, 'auth.md'), 'b\na\n');++ const result = (await buildExecResult(+ { command },+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },+ )) as ExecResult;++ const s = structured(result);+ expect(s.error?.category).toBe('write_blocked');+ expect(s.error?.message).toContain('exec is read-only');+ if (named !== '') expect(s.error?.message).toContain(named);+ expect(readFileSync(resolve(contentDir, 'auth.md'), 'utf8')).toBe('b\na\n');+ });+});+describe('exec — categorized errors', () => {test('unknown_command when first token not in allowlist', async () => {const project = await bootstrap();diff --git a/packages/server/src/mcp/tools/exec.ts b/packages/server/src/mcp/tools/exec.tsindex c222a7dab..8ceabdea4 100644--- a/packages/server/src/mcp/tools/exec.ts+++ b/packages/server/src/mcp/tools/exec.ts@@ -6,8 +6,14 @@ import {toEffectiveBase,} from '@inkeep/open-knowledge-core';import { z } from 'zod';-import { argsOf, extractReferencedPaths, nonFlagArgs } from '../../bash/extract-paths.ts';-import { createBashInstance, execBash, StdoutOverflowError } from '../../bash/index.ts';+import { expandGlobStages } from '../../bash/expand-globs.ts';+import { extractReferencedPaths, pathArgs } from '../../bash/extract-paths.ts';+import {+ createBashInstance,+ erofsTarget,+ execBash,+ StdoutOverflowError,+} from '../../bash/index.ts';import {deriveScanRoots,diffMtimes,@@ -31,6 +37,7 @@ import {fetchCommentCountsBatch,pathToDocName,} from '../../content/enrichment.ts';+import { getLogger } from '../../logger.ts';import { resolveWithinRoot } from './path-safety.ts';import { buildListResolver, docNameFromPath, type PreviewUrlSource } from './preview-url.ts';import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';@@ -41,6 +48,8 @@ import {textPlusStructured,} from './shared.ts';+const log = getLogger('mcp:exec');+const SOFT_CAP_LINES = 500;export const WIRE_BODY_COPIES = 2;export const RESULT_BODY_BUDGET_BYTES = 64 * 1024;@@ -57,11 +66,11 @@ export const DESCRIPTION = ['','`⚠ N unresolved comment(s)` = open human review requests — factor in before editing, and report them.','',- 'Allowlist: cat, ls, grep, find, head, tail, wc, sort, uniq, cut. One command or a pipe (|) per call — NOT a shell: `&&`, `;`, redirections, subshells, and writes are rejected. To do several things, make separate exec calls or pass multiple paths to one command (e.g. `ls -A a b c`, `cat a b c`).',+ 'Allowlist: cat, ls, grep, find, head, tail, wc, sort, uniq, cut. One command or a pipe (|) per call — NOT a shell: `&&`, `;`, subshells, writes, and ALL redirection are rejected, `<` too (read via `cat a.md`, not `< a.md`). For several things use separate exec calls or multiple paths (`cat a b c`).','',"cwd: the command runs in the explicit absolute `cwd` you pass, or in the MCP client's only advertised root when there is exactly one. If the client has zero or multiple roots, pass `cwd` explicitly. Paths inside the command resolve relative to that cwd; traversal above it is rejected.",'',- 'Stdout provenance headers (GNU-style): `ls <dir>/` prepends `<dir>/:`, single-file `cat`/`head`/`tail` prepends `==> <path> <==`, so the subject of the command is visible in raw output. Multi-file `cat a b` emits no header — the `enrichedPaths` array still lists every file. `head`/`tail` used as pipe trimmers (no file arg) defer to the upstream producer.',+ 'Stdout provenance headers (GNU-style): `ls <dir>/` prepends `<dir>/:`, single-file `cat`/`head`/`tail` prepends `==> <path> <==`. Multi-file `cat a b` emits no header — the `enrichedPaths` array still lists every file. `head`/`tail` used as pipe trimmers (no file arg) defer to the upstream producer.','','Examples:','- `exec({ command: "cat articles/auth.md" })` — file contents + full enrichment',@@ -312,17 +321,17 @@ function buildStdoutProvenance(stage = s;break;}- if ((cmd === 'head' || cmd === 'tail') && nonFlagArgs(argsOf(s)).length > 0) {+ if ((cmd === 'head' || cmd === 'tail') && pathArgs(s).length > 0) {stage = s;break;}}if (!stage) return '';- const pathArgs = nonFlagArgs(argsOf(stage));+ const operands = pathArgs(stage);if (stage.command === 'ls') {- const dirArg = pathArgs[pathArgs.length - 1];+ const dirArg = operands[operands.length - 1];if (!dirArg || dirArg === '.') return '';let n = dirArg.replace(/\/+/g, '/');if (n.startsWith('./')) n = n.slice(2);@@ -333,7 +342,7 @@ function buildStdoutProvenance(return `${key}/:\n`;}- const wikiFiles = pathArgs.filter((p) => /\.(md|mdx)$/.test(p) && fileByPath.has(rebase(p)));+ const wikiFiles = operands.filter((p) => /\.(md|mdx)$/.test(p) && fileByPath.has(rebase(p)));if (wikiFiles.length !== 1) return '';return `==> ${rebase(wikiFiles[0])} <==\n`;}@@ -394,6 +403,15 @@ function withPreviewUrls(});}+function writeBlockedResult(target: string | null) {+ if (target === null) log.warn({}, 'the engine refused a write without naming the file');+ const named = target === null ? 'a file' : `'${target}'`;+ return errorCategoryResult(+ 'write_blocked',+ `Write operation blocked: the command tried to write ${named}. exec is read-only. For document changes, use the \`write\` or \`edit\` tool.`,+ );+}+export async function buildExecResult(args: { command: string; cwd?: string },deps: ExecDeps,@@ -429,7 +447,11 @@ export async function buildExecResult(if ('error' in parsed) {return errorCategoryResult(parsed.error.category, parsed.error.message);}- const stages = augmentStagesWithExcludes(parsed.stages);+ const expanded = await expandGlobStages(parsed.stages, executionCwd);+ if ('error' in expanded) {+ return errorCategoryResult(expanded.error.category, expanded.error.message);+ }+ const stages = augmentStagesWithExcludes(expanded.stages);const effectiveCommand = serializeStages(stages);const scanRoots = [@@ -447,6 +469,10 @@ export async function buildExecResult(let stderr = '';try {const result = await execBash(bash, effectiveCommand);+ if (result.exitCode !== 0) {+ const refused = erofsTarget(result.stderr);+ if (refused.blocked) return writeBlockedResult(refused.target);+ }stdout = result.stdout;stderr = result.stderr;} catch (err) {@@ -456,6 +482,9 @@ export async function buildExecResult(`Output exceeded 16 MB buffer. Narrow the command (e.g., add a more specific grep pattern, use head, restrict the path).`,);}+ const refused = erofsTarget(err);+ if (refused.blocked) return writeBlockedResult(refused.target);+ log.warn({ err, command: args.command }, 'exec failed');return errorCategoryResult('shell_construct_blocked',`exec failed: ${err instanceof Error ? err.message : String(err)}`,@@ -465,9 +494,10 @@ export async function buildExecResult(const post = await snapshotMtimesForRoots(executionCwd, scanRoots);const mtimeDiff = diffMtimes(pre.snapshot, post.snapshot);if (mtimeDiff.changed.length > 0) {+ log.error({ command: args.command, changed: mtimeDiff.changed }, 'files changed during exec');return errorCategoryResult('security_invariant_violation',- `Security invariant violated: file(s) in the content directory were modified during a read-only exec call: ${mtimeDiff.changed.join(', ')}. This indicates a parser bug; the command has been logged.`,+ `Security invariant violated: file(s) in the content directory were modified during a read-only exec call: ${mtimeDiff.changed.join(', ')}. Either the read-only mount let a write through, or another writer (the live server, a human editor) touched these files at the same time. Logged.`,);}const sweepPartial = pre.truncated || post.truncated;diff --git a/packages/server/tsconfig.bash.json b/packages/server/tsconfig.bash.jsonnew file mode 100644index 000000000..e9d87deb6--- /dev/null+++ b/packages/server/tsconfig.bash.json@@ -0,0 +1,5 @@+{+ "extends": "./tsconfig.json",+ "include": ["src/bash/**/*.ts"],+ "exclude": ["node_modules", "dist"]+}diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 373410ca7..57ca13961 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1314,7 +1314,7 @@ importers:specifier: ^3.3.1version: 3.3.1just-bash:- specifier: ^2.14.3+ specifier: ~2.14.3version: 2.14.5mermaid:specifier: ~11.16.1