@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/shared/__tests__/git-internals.test.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { GIT_INTERNALS_MESSAGE, GitInternalsError } from '../domain-errors.js';
+import { assertNotGitInternals, hasGitInternalsSegment } from '../git-internals.js';
+
+describe('hasGitInternalsSegment', () => {
+  it.each([
+    '.git',
+    'knowledge-base/.git',
+    'knowledge-base/.git/',
+    'knowledge-base/.git/config',
+    '/knowledge-base/.git/HEAD',
+    'knowledge-base/notes/../.git/config',
+    './knowledge-base/./.git/config',
+    'knowledge-base\\.git\\config',
+    'knowledge-base/.GIT/config',
+    'knowledge-base/.Git/config',
+    'knowledge-base/%2egit/config',
+    'knowledge-base/%2Egit/config',
+    'knowledge-base%2F.git%2Fconfig',
+    'knowledge-base/%252egit/config',
+    'knowledge-base/.git./config',
+    'knowledge-base/.git /config',
+    'knowledge-base/sub/.git/config',
+    // Twelve layers of percent-encoding: no fixed number of decoding passes lets one through.
+    `knowledge-base/%${'25'.repeat(12)}2egit/config`,
+  ])('names the git folder: %s', (p) => {
+    expect(hasGitInternalsSegment(p)).toBe(true);
+  });
+
+  it.each([
+    'knowledge-base/.github/workflows/ci.yml',
+    'knowledge-base/.gitkeep',
+    'knowledge-base/.gitignore',
+    'knowledge-base/Knowledge/git.md',
+    'knowledge-base/my.git/file',
+    'knowledge-base/Notes/.git-notes.md',
+    '',
+  ])('leaves an ordinary path alone: %s', (p) => {
+    expect(hasGitInternalsSegment(p)).toBe(false);
+  });
+});
+
+describe('assertNotGitInternals — the resolved form', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'git-internals-'));
+    await fs.mkdir(path.join(root, 'knowledge-base', '.git'), { recursive: true });
+    await fs.writeFile(path.join(root, 'knowledge-base', '.git', 'config'), '[core]\n');
+    await fs.writeFile(path.join(root, 'knowledge-base', 'notes.md'), '# notes\n');
+    await fs.symlink('.git', path.join(root, 'knowledge-base', 'gitlink'));
+    await fs.symlink('.git/config', path.join(root, 'knowledge-base', 'cfglink'));
+    await fs.symlink('gitlink', path.join(root, 'knowledge-base', 'chained'));
+    // Dangling: nothing at the target yet, so a write through the link would create it inside `.git`.
+    await fs.symlink('.git/hooks/post-checkout', path.join(root, 'knowledge-base', 'dangling'));
+    await fs.symlink('dangling', path.join(root, 'knowledge-base', 'dangling-chained'));
+    await fs.symlink('.git/no-such-dir', path.join(root, 'knowledge-base', 'dangling-dir'));
+    await fs.symlink('loop-b', path.join(root, 'knowledge-base', 'loop-a'));
+    await fs.symlink('loop-a', path.join(root, 'knowledge-base', 'loop-b'));
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it.each(['knowledge-base/gitlink', 'knowledge-base/gitlink/config', 'knowledge-base/gitlink/new-file', 'knowledge-base/cfglink', 'knowledge-base/chained/HEAD'])(
+    'refuses a link that resolves into the git folder: %s',
+    async (p) => {
+      const err = await assertNotGitInternals(root, p).catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(GitInternalsError);
+      expect(err).toMatchObject({ status: 403, message: GIT_INTERNALS_MESSAGE });
+    },
+  );
+
+  it.each(['knowledge-base/dangling', 'knowledge-base/dangling-chained', 'knowledge-base/dangling-dir/new-file'])(
+    'refuses a dangling link whose target is inside the git folder: %s',
+    async (p) => {
+      await expect(assertNotGitInternals(root, p)).rejects.toBeInstanceOf(GitInternalsError);
+    },
+  );
+
+  it.each(['readlink', 'realpath of the link folder'])('a %s failure that is not absence is thrown, never guessed past', async (which) => {
+    const denied = Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+    if (which === 'readlink') {
+      vi.spyOn(fs, 'readlink').mockRejectedValue(denied);
+    } else {
+      const realpath = fs.realpath.bind(fs);
+      const kbDir = await realpath(path.join(root, 'knowledge-base'));
+      vi.spyOn(fs, 'realpath').mockImplementation((async (p: string) => {
+        if (p === path.join(root, 'knowledge-base') || p === kbDir) throw denied;
+        return realpath(p);
+      }) as typeof fs.realpath);
+    }
+    await expect(assertNotGitInternals(root, 'knowledge-base/dangling')).rejects.toMatchObject({ code: 'EACCES' });
+  });
+
+  it('a link loop is no refusal of its own, and does not hang', async () => {
+    await expect(assertNotGitInternals(root, 'knowledge-base/loop-a')).resolves.toBeUndefined();
+  });
+
+  it('passes an ordinary path, existing or not', async () => {
+    await expect(assertNotGitInternals(root, 'knowledge-base/notes.md')).resolves.toBeUndefined();
+    await expect(assertNotGitInternals(root, 'knowledge-base/new/deeper.md')).resolves.toBeUndefined();
+  });
+
+  it('judges only the part below the root, so a root under some .git folder still works', async () => {
+    const nested = path.join(root, 'knowledge-base', '.git', 'worktree-root');
+    await fs.mkdir(path.join(nested, 'docs'), { recursive: true });
+    await expect(assertNotGitInternals(nested, 'docs/a.md')).resolves.toBeUndefined();
+  });
+});

package/src/shared/__tests__/http-errors.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { domainErrorBody } from '../http-errors.js';
+import {
+  PathTraversalError,
+  UnreadableArchiveError,
+  WorkflowDomainError,
+  WorkflowValidationError,
+} from '../domain-errors.js';
+
+/**
+ * The one response body for a domain refusal — and the property eight route
+ * surfaces used to get wrong in seven different places.
+ */
+describe('domainErrorBody', () => {
+  it('carries the message and the payload discriminators together', () => {
+    expect(domainErrorBody(new PathTraversalError())).toEqual({
+      error: 'Path traversal detected',
+      kind: 'path-traversal',
+    });
+    expect(domainErrorBody(new UnreadableArchiveError('bad central directory'))).toEqual({
+      error: 'Could not read zip file: bad central directory',
+      kind: 'unreadable-archive',
+    });
+  });
+
+  it('is just the message when the error carries no payload', () => {
+    expect(domainErrorBody(new WorkflowValidationError('Only .zip files can be extracted'))).toEqual({
+      error: 'Only .zip files can be extracted',
+    });
+  });
+
+  it("a payload key named `error` never replaces the message — the bug this exists to make unwritable", () => {
+    // Spread payload-last and the client renders "something else entirely"
+    // instead of the refusal. `payload` is a Record<string, unknown>, so this
+    // key is expressible and nothing but ordering prevents it.
+    const err = new WorkflowDomainError('The real refusal.', 409, {
+      error: 'something else entirely',
+      kind: 'contended',
+    });
+    expect(domainErrorBody(err)).toEqual({ error: 'The real refusal.', kind: 'contended' });
+  });
+});

package/src/shared/__tests__/logging.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { createConsoleLogger, logger, setLogger } from '../logging.js';
+import type { ILogger, LogFields } from '../logger.contract.js';
+
+/** A logger that records what reached it, bindings included. */
+function capturing() {
+  const lines: Array<{ level: string; message: string; fields?: LogFields; bindings: LogFields }> = [];
+  const make = (bindings: LogFields): ILogger => ({
+    debug: (message, fields) => void lines.push({ level: 'debug', message, fields, bindings }),
+    info: (message, fields) => void lines.push({ level: 'info', message, fields, bindings }),
+    warn: (message, fields) => void lines.push({ level: 'warn', message, fields, bindings }),
+    error: (message, fields) => void lines.push({ level: 'error', message, fields, bindings }),
+    child: (more) => make({ ...bindings, ...more }),
+  });
+  return { lines, logger: make({}) };
+}
+
+let restore: ILogger | null = null;
+afterEach(() => {
+  if (restore) setLogger(restore);
+  restore = null;
+  vi.restoreAllMocks();
+});
+
+describe('logger()', () => {
+  it('routes through whatever is installed at the time of the call, not at the time of the lookup', () => {
+    const log = logger('queue'); // obtained "at module load", before any root ran
+    const cap = capturing();
+    restore = setLogger(cap.logger);
+
+    log.warn('behind', { rows: 3 });
+
+    expect(cap.lines).toEqual([{ level: 'warn', message: 'behind', fields: { rows: 3 }, bindings: { module: 'queue' } }]);
+  });
+
+  it('a child carries its bindings on top of the module tag', () => {
+    const cap = capturing();
+    restore = setLogger(cap.logger);
+
+    logger('workflow').child({ workspaceId: 'ws-1' }).info('pushed');
+
+    expect(cap.lines[0]?.bindings).toEqual({ module: 'workflow', workspaceId: 'ws-1' });
+  });
+});
+
+describe('createConsoleLogger', () => {
+  it('writes the shape the backend has always written: [module] message', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    createConsoleLogger().child({ module: 'sync' }).warn('branch is behind');
+    expect(warn).toHaveBeenCalledWith('[sync] branch is behind');
+  });
+
+  it('keeps the tag on the line too: a module name is escaped like any binding', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    createConsoleLogger({ module: 'sync\n[forged] admin signed in' }).warn('behind');
+    expect(warn).toHaveBeenCalledWith('[sync\\n[forged] admin signed in] behind');
+  });
+
+  it('passes a lone error bare, so the console prints its stack', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const err = new Error('boom');
+    createConsoleLogger({ module: 'mcp' }).error('session failed', { err });
+    // Bare — the second argument IS an error, not an object holding one —
+    // though a terminal-safe copy of it (see the escaping case below).
+    expect(error).toHaveBeenCalledTimes(1);
+    const [message, logged] = error.mock.calls[0] as [string, unknown];
+    expect(message).toBe('[mcp] session failed');
+    expect(logged).toBeInstanceOf(Error);
+    expect((logged as Error).message).toBe('boom');
+    expect((logged as Error).stack).toBe(err.stack);
+  });
+
+  /**
+   * An error's MESSAGE is very often not the process's own text — git's
+   * stderr, a path, a branch name — so it is made one line like any string
+   * field; the frames are ours and keep their lines. The original is not
+   * touched: it is often rethrown after it was logged.
+   */
+  it('escapes the text an error carries, keeps its frames, and never mutates the original', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const err = new Error('git said: fatal\n[forged] admin signed in\u009b31m');
+    (err as Error & { code?: string }).code = 'E\nFORGED';
+    createConsoleLogger({ module: 'sync' }).error('pull failed', { err });
+    const logged = error.mock.calls[0]?.[1] as Error & { code?: string };
+    expect(logged).toBeInstanceOf(Error);
+    expect(logged).not.toBe(err);
+    expect(logged.message).toBe('git said: fatal\\n[forged] admin signed in\\u009b31m');
+    expect(logged.code).toBe('E\\nFORGED');
+    // The header of the stack is the message and is escaped with it; the
+    // frames below it are still lines of their own.
+    expect(logged.stack?.startsWith('Error: git said: fatal\\n[forged] admin signed in\\u009b31m\n    at ')).toBe(true);
+    expect(err.message).toBe('git said: fatal\n[forged] admin signed in\u009b31m');
+    expect(err.stack?.includes('\n[forged]')).toBe(true);
+  });
+
+  /**
+   * The frames are looked for after the stack's header — the error's own
+   * `toString()` — not from the top: a message that carries a line shaped
+   * like a frame must not move the boundary up and pass the rest of itself
+   * through raw.
+   */
+  it('escapes a message that mimics a stack frame, whole', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const err = new Error('first\n    at fake (forged.js:1:1)\n[forged] admin signed in');
+    createConsoleLogger({ module: 'sync' }).error('failed', { err });
+    const logged = error.mock.calls[0]?.[1] as Error;
+    expect(logged.message).toBe('first\\n    at fake (forged.js:1:1)\\n[forged] admin signed in');
+    const header = logged.stack?.slice(0, logged.stack.indexOf('\n'));
+    expect(header).toBe('Error: first\\n    at fake (forged.js:1:1)\\n[forged] admin signed in');
+    // The frames that follow are the real ones; the forged one never became a line.
+    expect(logged.stack?.slice(header!.length).startsWith('\n    at ')).toBe(true);
+    expect(logged.stack?.includes('\n    at fake')).toBe(false);
+  });
+
+  it('escapes a string cause and the failures of an AggregateError, which the copy would otherwise drop', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const withStringCause = new Error('outer', { cause: 'git said\n[forged]' });
+    const aggregate = new AggregateError([new Error('one\nA'), 'two\nB'], 'several');
+    createConsoleLogger({ module: 'sync' }).error('failed', { err: withStringCause });
+    createConsoleLogger({ module: 'sync' }).error('failed', { err: aggregate });
+    const first = error.mock.calls[0]?.[1] as Error & { cause?: unknown };
+    const second = error.mock.calls[1]?.[1] as AggregateError;
+    expect(first.cause).toBe('git said\\n[forged]');
+    expect(second).toBeInstanceOf(AggregateError);
+    expect((second.errors[0] as Error).message).toBe('one\\nA');
+    expect(second.errors[1]).toBe('two\\nB');
+    // One failure listed twice is not a loop: both copies keep their text.
+    const shared = new Error('same\nS');
+    createConsoleLogger({ module: 'sync' }).error('failed', { err: new AggregateError([shared, shared], 'twice') });
+    const third = error.mock.calls[2]?.[1] as AggregateError;
+    expect(third.errors.map((e) => (e as Error).message)).toEqual(['same\\nS', 'same\\nS']);
+    // An ordinary error's own enumerable `errors` field stays visible.
+    const plain = Object.assign(new Error('plain'), { errors: ['x\ny'] });
+    createConsoleLogger({ module: 'sync' }).error('failed', { err: plain });
+    const fourth = error.mock.calls[3]?.[1] as Error & { errors: string[] };
+    expect(Object.keys(fourth)).toContain('errors');
+    expect(fourth.errors).toEqual(['x\\ny']);
+  });
+
+  it('cuts a cause chain that loops back on itself', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const a = new Error('a\nA');
+    const b = new Error('b\nB', { cause: a });
+    (a as Error & { cause?: unknown }).cause = b;
+    createConsoleLogger({ module: 'sync' }).error('failed', { err: a });
+    const logged = error.mock.calls[0]?.[1] as Error & { cause?: Error & { cause?: unknown } };
+    expect(logged.message).toBe('a\\nA');
+    expect(logged.cause?.message).toBe('b\\nB');
+    expect(logged.cause?.cause).toBe('[circular]');
+  });
+
+  it('passes several fields as one inspectable object, other bindings included', () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    createConsoleLogger({ module: 'cr', workspaceId: 'ws-1' }).info('merged', { number: 7 });
+    expect(log).toHaveBeenCalledWith('[cr] merged', { workspaceId: 'ws-1', number: 7 });
+  });
+
+  /**
+   * The property: whatever a message or a string field carries, the sink
+   * writes one line. A newline is the forged-line case, U+009B the one-byte
+   * escape that steers a terminal; both arrive routinely in text the process
+   * did not write (a request's branch name, git's stderr).
+   */
+  it('keeps every event on one line, whatever the text carried', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    createConsoleLogger({ module: 'sync' }).warn('branch "x\n[forged] admin signed in\u009b31m" is behind', {
+      detail: 'line one\r\nline two',
+      rows: 2,
+    });
+    expect(warn).toHaveBeenCalledWith('[sync] branch "x\\n[forged] admin signed in\\u009b31m" is behind', {
+      detail: 'line one\\r\\nline two',
+      rows: 2,
+    });
+  });
+
+  it('maps levels onto the console method a reader expects', () => {
+    const debug = vi.spyOn(console, 'debug').mockImplementation(() => undefined);
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const sink = createConsoleLogger({ module: 'x' });
+    sink.debug('d');
+    sink.info('i');
+    expect(debug).toHaveBeenCalledWith('[x] d');
+    expect(log).toHaveBeenCalledWith('[x] i');
+  });
+});

package/src/shared/__tests__/path-containment.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import path from 'node:path';
+import { assertWithinDirectory } from '../path-containment.js';
+import { PathTraversalError } from '../domain-errors.js';
+
+/**
+ * The one lexical containment check: what it admits, what it refuses, and
+ * — the property the route layers depend on — that its refusal is a TYPE
+ * carrying its own status, not a message anyone has to recognise.
+ */
+describe('assertWithinDirectory', () => {
+  const root = path.resolve('/srv/workspaces/main');
+  const ok = (p: string) => expect(() => assertWithinDirectory(p, root)).not.toThrow();
+  const refused = (p: string) => expect(() => assertWithinDirectory(p, root)).toThrow(PathTraversalError);
+
+  it('admits the directory itself and anything under it, however spelled', () => {
+    ok(root);
+    ok(path.join(root, 'knowledge-base', 'notes.md'));
+    // An UNRESOLVED spelling that lands inside. Concatenated, not joined:
+    // `path.join` would collapse the `..` before the guard ever saw it, and
+    // resolving the caller's spelling is the guard's own job.
+    ok(`${root}${path.sep}a${path.sep}..${path.sep}b.md`);
+    ok(`${root}${path.sep}`);
+  });
+
+  it('refuses a climb out, a sibling, and the parent', () => {
+    // Unresolved again: this is the spelling an attacker actually sends.
+    refused(`${root}${path.sep}..${path.sep}other${path.sep}secrets.md`);
+    refused(`${root}${path.sep}a${path.sep}..${path.sep}..${path.sep}escape.md`);
+    refused(path.dirname(root));
+    // A sibling whose name merely STARTS with the root's — the prefix trap a
+    // `startsWith(root)` check without the separator falls into.
+    refused(`${root}-backup`);
+    refused(`${root}-backup${path.sep}notes.md`);
+  });
+
+  it('admits descendants of the filesystem root, which already ends in a separator', () => {
+    // `root + sep` would be `//` (or `C:\\`), which no descendant starts
+    // with — so a doubled separator refuses every path under it.
+    const fsRoot = path.parse(path.resolve('/')).root;
+    expect(() => assertWithinDirectory(path.join(fsRoot, 'etc', 'passwd'), fsRoot)).not.toThrow();
+    expect(() => assertWithinDirectory(fsRoot, fsRoot)).not.toThrow();
+  });
+
+  it('refuses an absolute path somewhere else entirely', () => {
+    refused(path.resolve('/etc/passwd'));
+    refused(path.resolve('/srv/workspaces/other/notes.md'));
+  });
+
+  it('refuses with a 403 domain error the routes read the status off, not a message they must match', () => {
+    let thrown: unknown;
+    try {
+      assertWithinDirectory(path.join(root, '..', 'escape'), root);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(PathTraversalError);
+    expect(thrown).toMatchObject({ status: 403, payload: { kind: 'path-traversal' } });
+  });
+});

package/src/shared/__tests__/path-order.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { comparePathComponents } from '../path-order.js';
+
+describe('comparePathComponents', () => {
+  it('orders component by component, the way a sorted directory walk visits paths', () => {
+    // A whole-string compare would weigh "-" against "/" and put a-b/x first.
+    expect(comparePathComponents('a/b/x', 'a-b/x')).toBeLessThan(0);
+    expect(comparePathComponents('Plugins/GTM', 'Plugins/GTM/skills')).toBeLessThan(0);
+    expect(comparePathComponents('Plugins/GTM', 'Plugins/GTM')).toBe(0);
+  });
+
+  it('never calls two distinct paths equal: a collation tie falls through to code-unit order', () => {
+    // Precomposed é and its decomposed spelling collate as equal; two folders
+    // so named must still have ONE first, or discovery and principal synthesis
+    // could each claim a different one for the same slug.
+    const composed = 'Plugins/café';
+    const decomposed = 'Plugins/café';
+    // (Whether the host's collation equates them is the host's business —
+    // the property under test holds either way: distinct paths never tie.)
+    const order = comparePathComponents(composed, decomposed);
+    expect(order).not.toBe(0);
+    expect(comparePathComponents(decomposed, composed)).toBe(-order);
+  });
+});

package/src/shared/__tests__/pending-proposals.readAt.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, test } from 'vitest';
+import { readAt } from '../pending-proposals.js';
+import { setLogger } from '../logging.js';
+import type { ILogger } from '../logger.contract.js';
+import type { WorkspaceService } from '../../modules/workspace/workspace.service.js';
+
+/**
+ * `readAt` is the one place a proposal's file is fetched, and every value it
+ * handles is attacker-shaped: the path and the branch come off a change request
+ * somebody else opened, and the failure reason comes off git.
+ */
+
+/** A logger that only records, so a test can read back the line that was written. */
+function capturing(): { lines: string[]; impl: ILogger } {
+  const lines: string[] = [];
+  const impl: ILogger = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: (message: string) => void lines.push(message),
+    error: () => undefined,
+    child: () => impl,
+  };
+  return { lines, impl };
+}
+
+function serviceThatThrows(err: unknown): Pick<WorkspaceService, 'readFileAtRef'> {
+  return {
+    readFileAtRef: async () => {
+      throw err;
+    },
+  } as unknown as Pick<WorkspaceService, 'readFileAtRef'>;
+}
+
+let restore: ILogger | null = null;
+afterEach(() => {
+  if (restore) setLogger(restore);
+  restore = null;
+});
+
+describe('readAt', () => {
+  /**
+   * `readFileAtRef` already answers null for genuine absence, so a null from it
+   * is "not on that branch" and says nothing to the operator.
+   */
+  test('returns null without a word when the file is simply not on the branch', async () => {
+    const { lines, impl } = capturing();
+    restore = setLogger(impl);
+    const service = { readFileAtRef: async () => null } as unknown as Pick<
+      WorkspaceService,
+      'readFileAtRef'
+    >;
+
+    expect(await readAt(service, 'ws', 'agent/weather', 'Plugins/Ops/weather.tool')).toBeNull();
+    expect(lines).toEqual([]);
+  });
+
+  /**
+   * An infra failure still degrades to null — the module's contract is "never
+   * throws" — but it must not degrade SILENTLY, or a git timeout reads to the
+   * operator exactly like the proposer having withdrawn the file.
+   */
+  test('warns before degrading to null when the read actually fails', async () => {
+    const { lines, impl } = capturing();
+    restore = setLogger(impl);
+
+    expect(
+      await readAt(serviceThatThrows(new Error('fetch timed out')), 'ws', 'agent/weather', 'Plugins/Ops/weather.tool'),
+    ).toBeNull();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain('Plugins/Ops/weather.tool');
+    expect(lines[0]).toContain('fetch timed out');
+  });
+
+  /**
+   * The path, the branch and the reason are all author-controlled. A raw
+   * newline in any of them forges a log line; an escape sequence steers the
+   * operator's terminal. Nothing untrusted reaches the sink unescaped.
+   */
+  test('escapes control characters in the path, the branch and the reason', async () => {
+    const { lines, impl } = capturing();
+    restore = setLogger(impl);
+
+    await readAt(
+      serviceThatThrows(new Error('boom\n[pending-proposals] all clear')),
+      'ws',
+      'agent/\u001b[31mweather',
+      'Plugins/Ops/we\nather.tool',
+    );
+
+    const [line] = lines;
+    expect(line).toBeDefined();
+    // Not one raw newline or escape byte survives into the sink. Spelled as
+    // `includes` rather than a character class, because a control character
+    // inside a regex literal is itself the thing the linter forbids.
+    for (const raw of ['\n', '\r', String.fromCharCode(0x1b)]) {
+      expect(line).not.toContain(raw);
+    }
+    // …and the text is still there to read, just quoted.
+    expect(line).toContain('\\n');
+    expect(line).toContain('\\u001b');
+  });
+});

package/src/shared/__tests__/printable.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { printable, sanitizedPath, terminalSafeJson } from '../printable.js';
+
+/**
+ * The two renderings of caller-supplied text, and the one promise they share:
+ * whatever a caller put in a name, the text it becomes occupies ONE line.
+ */
+describe('printable', () => {
+  it('quotes and escapes the controls a log line could be forged with', () => {
+    expect(printable('python-httpx/0.28.1')).toBe('"python-httpx/0.28.1"');
+    expect(printable('evil\n[forged]')).toBe('"evil\\n[forged]"');
+    // C1 (U+009B is a one-byte CSI) and the JS line separators, which
+    // JSON.stringify leaves raw.
+    expect(printable('a\u009bb')).toBe('"a\\u009bb"');
+    expect(printable('a\u2028b\u2029c')).toBe('"a\\u2028b\\u2029c"');
+  });
+});
+
+describe('sanitizedPath', () => {
+  it('leaves an ordinary path exactly as it was', () => {
+    expect(sanitizedPath('knowledge-base/Knowledge/Note.md')).toBe('knowledge-base/Knowledge/Note.md');
+  });
+
+  it('escapes CR and LF, so a name cannot forge a second line of a refusal', () => {
+    expect(sanitizedPath('a\nb.md')).toBe('a\\nb.md');
+    expect(sanitizedPath('a\r\nb.md')).toBe('a\\r\\nb.md');
+  });
+
+  it('escapes the other mandatory breaks — vertical tab, form feed, NEL — as `printable` spells them', () => {
+    expect(sanitizedPath('a\vb\fc\u0085d.md')).toBe('a\\u000bb\\fc\\u0085d.md');
+    // The same characters through `printable` (JSON underneath), minus its quotes.
+    expect(printable('a\vb\fc\u0085d\be.md')).toBe(`"${sanitizedPath('a\vb\fc\u0085d\be.md')}"`);
+  });
+
+  it('terminalSafeJson escapes only what JSON.stringify left raw, keeping the document\'s own lines', () => {
+    const json = JSON.stringify({ detail: 'said\n\u009b31mred
' }, null, 2);
+    expect(terminalSafeJson(json)).toBe('{\n  "detail": "said\\n\\u009b31mred\\u2028"\n}');
+    expect(JSON.parse(terminalSafeJson(json))).toEqual(JSON.parse(json));
+  });
+
+  it('escapes every other C0/C1 control too, so a name cannot steer a terminal', () => {
+    // U+009B is the one-byte CSI: on its own it starts an ANSI sequence.
+    expect(sanitizedPath('a\u009b31mb.md')).toBe('a\\u009b31mb.md');
+    expect(sanitizedPath('a\u0000b\u001bc\u007fd.md')).toBe('a\\u0000b\\u001bc\\u007fd.md');
+    expect(sanitizedPath('tab\there.md')).toBe('tab\\there.md');
+  });
+
+  // U+2028/U+2029 render as line breaks in editors, terminals and JSON
+  // consumers, and `JSON.stringify` passes them through raw — so a path
+  // carrying one survives being carried, in the `path` field of a not-found
+  // body and in the log line beside it, and breaks the line at the far end.
+  it('escapes the Unicode line separators too, which JSON.stringify does not', () => {
+    expect(sanitizedPath('a\u2028b.md')).toBe('a\\u2028b.md');
+    expect(sanitizedPath('a\u2029b.md')).toBe('a\\u2029b.md');
+    const forged = 'note.md\u2028error: everything is fine';
+    expect(sanitizedPath(forged)).not.toContain('\u2028');
+    expect(JSON.stringify(sanitizedPath(forged))).not.toContain('\u2028');
+  });
+
+  it('is idempotent: sanitizing an already-sanitized path changes nothing', () => {
+    const once = sanitizedPath('a\nb\u2028c.md');
+    expect(sanitizedPath(once)).toBe(once);
+  });
+});