@qvac/harness 0.8.9 → 0.8.11

package/dist-lib/lib/tools/exec/adapters/python/attachments.js

@@ -1,19 +1,19 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../../../errors.js';
 import { errorMessage } from '../../../../guards.js';
-import { hlog } from '../../../../log.js';
+import { log } from '../../../../log.js';
 import { checkOutputBytes, MAX_INPUT_TOTAL_BYTES, RUN_OUTPUT_BUDGET_BYTES } from './output-policy.js';
 const STAGE_TIMEOUT_MS = 60_000;
-const STAGE_TIMEOUT_MESSAGE = `staging attachments timed out after ${STAGE_TIMEOUT_MS}ms`;
 const OVER_BUDGET_ERROR = 'inputs exceed maximum total size';
 const NO_UPLOAD_ERROR = 'no uploaded image in this chat — attach an image or pass an attachmentId';
 const DOCUMENT_INPUT = /\.(pdf|docx?|xlsx?|xlsm|pptx?|csv|tsv|txt|md|markdown|rtf|odt|ods|odp|epub|jsonl?|xhtml|html?|xml|ya?ml|log|zip)$/i;
 const NO_DOCUMENT_ERROR = 'an id-less input stages an uploaded image, and this path names a document — pass its ' +
     'attachmentId, which the [Attached file "…"] line on the user\'s message carries';
-function bounded(work, ms, message) {
+function bounded(work, ms) {
     let timer;
     const bound = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error(message)), ms);
+        timer = setTimeout(() => reject(new HarnessError('ATTACHMENT_STAGING_TIMED_OUT', [STAGE_TIMEOUT_MS])), ms);
     });
     return Promise.race([work, bound]).finally(() => {
         if (timer) {
@@ -54,14 +54,14 @@ async function probeUpload(fetchAttachment, input, { index, turnImages, signal,
     if (DOCUMENT_INPUT.test(input.path)) {
         return { error: NO_DOCUMENT_ERROR };
     }
-    const bytes = await bounded(uploadedBytes(fetchAttachment, index, { turnImages, signal }), deadline - Date.now(), STAGE_TIMEOUT_MESSAGE);
+    const bytes = await bounded(uploadedBytes(fetchAttachment, index, { turnImages, signal }), deadline - Date.now());
     if ('error' in bytes) {
         return bytes;
     }
     return { size: bytes.byteLength, bytes };
 }
 async function probeAttachment(fetchAttachment, id, { signal, deadline }) {
-    const head = await bounded(fetchAttachment({ attachmentId: id, meta: true, signal }), deadline - Date.now(), STAGE_TIMEOUT_MESSAGE);
+    const head = await bounded(fetchAttachment({ attachmentId: id, meta: true, signal }), deadline - Date.now());
     if (!head) {
         return { error: `attachment ${id} not found in this chat` };
     }
@@ -90,7 +90,7 @@ export async function stageInputs(fetchAttachment, inputs, opts = {}) {
             }
             total += probe.size;
             if (total > MAX_INPUT_TOTAL_BYTES) {
-                hlog('python: input attachments over budget; skipping blob download', {
+                log.warn('python: input attachments over budget; skipping blob download', {
                     total,
                     cap: MAX_INPUT_TOTAL_BYTES,
                     count: inputs.length
@@ -111,7 +111,7 @@ export async function stageInputs(fetchAttachment, inputs, opts = {}) {
     for (const { index, input } of pending) {
         const id = input.attachmentId;
         try {
-            const fetched = await bounded(fetchAttachment({ attachmentId: id, signal }), deadline - Date.now(), STAGE_TIMEOUT_MESSAGE);
+            const fetched = await bounded(fetchAttachment({ attachmentId: id, signal }), deadline - Date.now());
             if (!fetched || !hasBytes(fetched)) {
                 return { error: `attachment ${id} not found in this chat` };
             }

package/dist-lib/lib/tools/exec/adapters/python/guarded-fetch.js

@@ -1,6 +1,7 @@
 import { AbortController } from 'bare-abort-controller';
 import b4a from 'b4a';
 import { noRedirectFetch } from '#no-redirect-fetch';
+import { HarnessError } from '../../../../errors.js';
 import { lookupHost } from '../../../../dns-lookup.js';
 import { hostIsNamed } from './named-hosts.js';
 import { checkOutboundHost, resolveOutboundUrl } from '../../../url-guard.js';
@@ -182,18 +183,18 @@ export function createGuardedFetch(options = {}) {
         try {
             for (let hops = 0;; hops++) {
                 if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-                    throw new TypeError(`fetch refused: unsupported protocol ${url.protocol}`);
+                    throw new HarnessError('FETCH_REFUSED', [`unsupported protocol ${url.protocol}`]);
                 }
                 const literal = checkOutboundHost(url);
                 if (literal) {
-                    throw new TypeError(`fetch refused: ${literal}`);
+                    throw new HarnessError('FETCH_REFUSED', [`${literal}`]);
                 }
                 if (!(await mayConnect(url.hostname))) {
-                    throw new TypeError(`fetch refused: ${url.hostname} was not approved for this run`);
+                    throw new HarnessError('FETCH_REFUSED', [`${url.hostname} was not approved for this run`]);
                 }
                 const check = await resolveOutboundUrl(url, resolveHost, controller.signal);
                 if (check.blocked) {
-                    throw new TypeError(`fetch refused: ${check.blocked}`);
+                    throw new HarnessError('FETCH_REFUSED', [`${check.blocked}`]);
                 }
                 const response = await send(url, {
                     method,
@@ -213,10 +214,10 @@ export function createGuardedFetch(options = {}) {
                     });
                 }
                 if (init.redirect === 'error') {
-                    throw new TypeError('fetch refused: redirect not allowed');
+                    throw new HarnessError('FETCH_REFUSED', ['redirect not allowed']);
                 }
                 if (hops >= MAX_REDIRECTS) {
-                    throw new TypeError('fetch refused: too many redirects');
+                    throw new HarnessError('FETCH_REFUSED', ['too many redirects']);
                 }
                 const next = new URL(location, url);
                 if (next.protocol !== url.protocol || next.host !== url.host) {

package/dist-lib/lib/tools/exec/adapters/python/interrupt-timer.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'url';
 import { Worker } from 'worker_threads';
 import { errorMessage } from '../../../../guards.js';
-import { hlog } from '../../../../log.js';
+import { log } from '../../../../log.js';
 import { DISARMED, FIRED } from './deadline-state.js';
 export function startInterruptTimer(ms) {
     const state = new Int32Array(new SharedArrayBuffer(4));
@@ -9,7 +9,7 @@ export function startInterruptTimer(ms) {
     const workerData = { state: state.buffer, interrupt: interrupt.buffer, ms };
     const entry = fileURLToPath(import.meta.resolve('#pyodide-interrupt-deadline'));
     new Worker(entry, { workerData })
-        .on('error', (error) => hlog('python: interrupt deadline failed', { err: errorMessage(error) }))
+        .on('error', (error) => log.warn('python: interrupt deadline failed', { err: errorMessage(error) }))
         .unref();
     return {
         interrupt,

package/dist-lib/lib/tools/exec/adapters/python/memfs.js

@@ -1,5 +1,5 @@
 import { errorMessage } from '../../../../guards.js';
-import { hlog } from '../../../../log.js';
+import { log } from '../../../../log.js';
 import { MAX_OUTPUT_FILE_BYTES, MAX_OUTPUT_TOTAL_BYTES } from './output-policy.js';
 let runCounter = 0;
 function filePath(dir, name) {
@@ -69,7 +69,7 @@ export function removeScratch(fs, dir, previousCwd) {
         removeTree(fs, dir);
     }
     catch (error) {
-        hlog('python: scratch cleanup failed', {
+        log.warn('python: scratch cleanup failed', {
             dir,
             err: errorMessage(error)
         });

package/dist-lib/lib/tools/exec/adapters/python/pyodide.js

@@ -1,8 +1,9 @@
 import { AbortController } from 'bare-abort-controller';
 import ScopeLock from 'scope-lock';
+import { HarnessError } from '../../../../errors.js';
 import { errorMessage } from '../../../../guards.js';
 import { AbortedError, raceAbort } from '../../../../helpers/race-abort.js';
-import { hlog } from '../../../../log.js';
+import { log } from '../../../../log.js';
 import { MAX_OUTPUT_CHARS } from '../../runner.js';
 import { startInterruptTimer } from './interrupt-timer.js';
 import { pyodideLoadOptions } from './loader.js';
@@ -15,15 +16,15 @@ const cache = new Map();
 function getPyodide(load) {
     let loaded = cache.get(load);
     if (!loaded) {
-        hlog('python: booting interpreter');
+        log.info('python: booting interpreter');
         loaded = load()
             .then((py) => {
-            hlog('python: interpreter ready');
+            log.info('python: interpreter ready');
             return py;
         })
             .catch((error) => {
             cache.delete(load);
-            hlog('python: interpreter boot failed', {
+            log.error('python: interpreter boot failed', {
                 err: errorMessage(error)
             });
             throw error;
@@ -35,7 +36,6 @@ function getPyodide(load) {
 const runLock = new ScopeLock();
 async function runInProcess(load, spec, options) {
     const deadline = Date.now() + options.timeoutMs;
-    const timeoutMessage = `Command timed out after ${options.timeoutMs}ms`;
     let timedOut = false;
     const stop = new AbortController();
     const ask = options.askConnect;
@@ -63,10 +63,10 @@ async function runInProcess(load, spec, options) {
             }
             if (outcome.evict) {
                 cache.delete(load);
-                hlog('python: interpreter evicted; next run boots fresh');
+                log.warn('python: interpreter evicted; next run boots fresh');
             }
             if (timedOut) {
-                throw new Error(timeoutMessage);
+                throw new HarnessError('COMMAND_TIMED_OUT', [options.timeoutMs]);
             }
             return outcome.result;
         }
@@ -84,7 +84,7 @@ async function runInProcess(load, spec, options) {
     const timeout = new Promise((_, reject) => {
         timer = setTimeout(() => {
             timedOut = true;
-            reject(new Error(timeoutMessage));
+            reject(new HarnessError('COMMAND_TIMED_OUT', [options.timeoutMs]));
         }, options.timeoutMs);
     });
     try {

package/dist-lib/lib/tools/exec/adapters/python/run-session.js

@@ -1,6 +1,7 @@
+import { HarnessError } from '../../../../errors.js';
 import { errorMessage } from '../../../../guards.js';
 import { AbortedError } from '../../../../helpers/race-abort.js';
-import { hlog } from '../../../../log.js';
+import { log } from '../../../../log.js';
 import { TRUNCATED_OUTPUT_SUFFIX } from '../../runner.js';
 import { collectOutputs, openScratch, stageInputFiles } from './memfs.js';
 import { isGuardedFetch, setConnectPolicy } from './guarded-fetch.js';
@@ -105,7 +106,10 @@ async function runOnce(py, code, opts) {
     }
     return retry;
 }
-class InstallTimeoutError extends Error {
+class InstallTimeoutError extends HarnessError {
+    constructor(ms) {
+        super('PACKAGE_INSTALL_TIMED_OUT', [ms]);
+    }
 }
 function installSource(py, packages) {
     const plan = planVendoredInstall(packages);
@@ -113,7 +117,7 @@ function installSource(py, packages) {
         return `import micropip\nawait micropip.install(${JSON.stringify(packages)})`;
     }
     const specs = [...stageVendoredWheels(py.FS, plan), ...plan.packages];
-    hlog('python: installing from vendored wheels', { specs });
+    log.info('python: installing from vendored wheels', { specs });
     return `import micropip\nawait micropip.install(${JSON.stringify(specs)}, deps=False)`;
 }
 async function installPackages(py, packages, { timeoutMs, isCancelled }) {
@@ -124,7 +128,7 @@ async function installPackages(py, packages, { timeoutMs, isCancelled }) {
     const install = py.runPythonAsync(installSource(py, packages));
     let timer;
     const bound = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new InstallTimeoutError(`package install timed out after ${timeoutMs}ms`)), timeoutMs);
+        timer = setTimeout(() => reject(new InstallTimeoutError(timeoutMs)), timeoutMs);
     });
     try {
         await Promise.race([install, bound]);
@@ -158,7 +162,7 @@ export async function performRun(py, spec, opts = {}) {
         if (isCancelled()) {
             throw new AbortedError();
         }
-        hlog('python: installing packages', {
+        log.info('python: installing packages', {
             packages: [...spec.packages],
             timeoutMs: spec.installTimeoutMs
         });
@@ -167,7 +171,7 @@ export async function performRun(py, spec, opts = {}) {
                 timeoutMs: spec.installTimeoutMs,
                 isCancelled
             });
-            hlog('python: packages ready', { packages: [...spec.packages] });
+            log.info('python: packages ready', { packages: [...spec.packages] });
         }
         catch (error) {
             if (error instanceof AbortedError) {
@@ -176,7 +180,7 @@ export async function performRun(py, spec, opts = {}) {
             const message = errorMessage(error);
             const timedOut = error instanceof InstallTimeoutError;
             const evict = timedOut || isPyodideFatal(error);
-            hlog(timedOut ? 'python: package install timed out' : 'python: package install failed', {
+            log.warn(timedOut ? 'python: package install timed out' : 'python: package install failed', {
                 packages: [...spec.packages],
                 err: message,
                 evict

package/dist-lib/lib/tools/exec/adapters/python/wheels.js

@@ -3,7 +3,7 @@ import process from 'process';
 import { fileURLToPath } from 'url';
 import { z } from 'zod';
 import { errorMessage } from '../../../../guards.js';
-import { hlog } from '../../../../log.js';
+import { log } from '../../../../log.js';
 const ManifestSchema = z.object({
     pyodide: z.string(),
     packages: z.record(z.string(), z.object({
@@ -21,14 +21,14 @@ export function wheelsDir() {
 export function vendoredManifest(dir = wheelsDir()) {
     const file = `${dir}/manifest.json`;
     if (!fs.existsSync(file)) {
-        hlog('python: no vendored wheels', { dir });
+        log.info('python: no vendored wheels', { dir });
         return null;
     }
     try {
         return ManifestSchema.parse(JSON.parse(fs.readFileSync(file, 'utf8')));
     }
     catch (error) {
-        hlog('python: vendored wheel manifest unusable', {
+        log.warn('python: vendored wheel manifest unusable', {
             file,
             err: errorMessage(error)
         });
@@ -72,7 +72,7 @@ export function planVendoredInstall(specs, opts = {}) {
         }
         for (const wheel of entry.pypi) {
             if (!fs.existsSync(`${dir}/${wheel}`)) {
-                hlog('python: vendored wheel missing, installing from PyPI instead', { wheel });
+                log.warn('python: vendored wheel missing, installing from PyPI instead', { wheel });
                 return null;
             }
             wheels.add(`${dir}/${wheel}`);
@@ -112,6 +112,6 @@ export function seedPackageCache(cacheDir, dir = wheelsDir()) {
         seeded++;
     }
     if (seeded > 0) {
-        hlog('python: seeded package cache', { cacheDir, wheels: seeded });
+        log.debug('python: seeded package cache', { cacheDir, wheels: seeded });
     }
 }

package/dist-lib/lib/tools/exec/adapters/python/worker/active.js

@@ -1,4 +1,4 @@
-import { hlog } from '../../../../../log.js';
+import { log } from '../../../../../log.js';
 import { asWorkerMessage } from './protocol.js';
 const SHUTDOWN_GRACE_MS = 3_000;
 let active = null;
@@ -20,7 +20,7 @@ export async function readMessage(link) {
         if (message?.type !== 'log') {
             return message;
         }
-        hlog(`python worker: ${message.message}`);
+        log[message.level](`python worker: ${message.message}`);
     }
 }
 export async function drainAndReap(worker) {

package/dist-lib/lib/tools/exec/adapters/python/worker/client.js

@@ -1,8 +1,9 @@
 import { AbortController } from 'bare-abort-controller';
 import process from 'process';
 import { fileURLToPath } from 'url';
+import { HarnessError } from '../../../../../errors.js';
 import { AbortedError, raceAbort } from '../../../../../helpers/race-abort.js';
-import { harnessLogEnabled, hlog } from '../../../../../log.js';
+import { harnessLogLevel, log } from '../../../../../log.js';
 import { RESEND_MS, SIGINT } from '../deadline-state.js';
 import { fromWireResult } from './protocol.js';
 import { activeWorker, destroy, drainAndReap, forget, grace, readMessage } from './active.js';
@@ -21,18 +22,18 @@ async function awaitReady(link) {
         return;
     }
     if (message?.type === 'boot-error') {
-        throw new Error(`python worker: ${message.message}`);
+        throw new HarnessError('PYTHON_WORKER_FAILED', [message.message]);
     }
     throw new Error('python worker sent an unexpected first message');
 }
 function boot() {
-    hlog('python: booting worker thread');
+    log.info('python: booting worker thread');
     const sab = new SharedArrayBuffer(1);
-    const link = spawnPythonWorker(workerEntry(), { sab, log: harnessLogEnabled() });
+    const link = spawnPythonWorker(workerEntry(), { sab, log: harnessLogLevel() });
     const worker = {
         link,
         view: new Uint8Array(sab),
-        ready: awaitReady(link).then(() => hlog('python: worker ready')),
+        ready: awaitReady(link).then(() => log.info('python: worker ready')),
         nextId: 1
     };
     worker.ready.catch(() => {
@@ -55,7 +56,7 @@ async function resultFor(worker, id, askConnect) {
         return { result: fromWireResult(message.result), evict: message.evict };
     }
     if (message?.type === 'boot-error') {
-        throw new Error(`python worker: ${message.message}`);
+        throw new HarnessError('PYTHON_WORKER_FAILED', [message.message]);
     }
     throw new Error('python worker sent an unexpected message');
 }
@@ -70,7 +71,7 @@ async function interrupt(worker, outcome) {
             timer.expired
         ]);
         if (settled === 'grace') {
-            hlog('python: worker ignored interrupt; killing', { graceMs });
+            log.warn('python: worker ignored interrupt; killing', { graceMs });
             destroy(worker);
         }
         else {
@@ -134,7 +135,7 @@ export async function runPythonInWorker(spec, opts) {
         }
         if (first === 'timeout') {
             await cancel();
-            throw new Error(`Command timed out after ${opts.timeoutMs}ms`);
+            throw new HarnessError('COMMAND_TIMED_OUT', [opts.timeoutMs]);
         }
         if (first.evict) {
             await drainAndReap(worker);

package/dist-lib/lib/tools/exec/adapters/python/worker/protocol.d.ts

@@ -1,3 +1,4 @@
+import type { LineLevel } from '../../../../../log.ts';
 import type { PythonRunResult, RunSpec } from '../run-session.ts';
 export type HostMessage = {
     readonly type: 'run';
@@ -23,6 +24,7 @@ export interface WireResult {
 }
 export type WorkerMessage = {
     readonly type: 'log';
+    readonly level: LineLevel;
     readonly message: string;
 } | {
     readonly type: 'ready';

package/dist-lib/lib/tools/exec/adapters/python/worker/serve.js

@@ -1,12 +1,12 @@
 import { parentPort, workerData } from 'worker_threads';
 import { errorMessage, isRecord } from '../../../../../guards.js';
-import { setHarnessLog, setHarnessLogSink } from '../../../../../log.js';
+import { isLogLevel, setHarnessLogLevel, setHarnessLogSink } from '../../../../../log.js';
 import { performRun } from '../run-session.js';
 import { asHostMessage, toWireResult } from './protocol.js';
 function narrowThreadData(data) {
     if (isRecord(data) && 'sab' in data) {
         const sab = data.sab;
-        const log = 'log' in data && data.log === true;
+        const log = 'log' in data && isLogLevel(data.log) ? data.log : 'off';
         if (sab instanceof SharedArrayBuffer) {
             return { sab, log };
         }
@@ -73,8 +73,8 @@ async function serveRuns(port, py) {
 }
 export async function serve(load) {
     const { port, sab, log } = openPort();
-    setHarnessLog(log);
-    setHarnessLogSink((message) => port.write({ type: 'log', message }));
+    setHarnessLogLevel(log);
+    setHarnessLogSink((message, level) => port.write({ type: 'log', level, message }));
     try {
         const py = await load();
         py.setInterruptBuffer(new Uint8Array(sab));

package/dist-lib/lib/tools/exec/adapters/python/worker/spawn.d.ts

@@ -1,3 +1,4 @@
+import type { LogLevel } from '../../../../../log.ts';
 export interface WorkerLink {
     read(): Promise<unknown>;
     write(message: unknown): Promise<void>;
@@ -8,6 +9,6 @@ export interface WorkerLink {
 }
 export interface WorkerData {
     readonly sab: SharedArrayBuffer;
-    readonly log: boolean;
+    readonly log: LogLevel;
 }
 export declare function spawnPythonWorker(entry: string, data: WorkerData): WorkerLink;

package/dist-lib/lib/tools/exec/adapters/python/worker/spawn.js

@@ -1,4 +1,5 @@
 import { Worker } from 'worker_threads';
+import { HarnessError } from '../../../../../errors.js';
 export function spawnPythonWorker(entry, data) {
     const worker = new Worker(entry, {
         workerData: data,
@@ -26,7 +27,7 @@ export function spawnPythonWorker(entry, data) {
     };
     worker.on('message', push);
     worker.on('error', (error) => fail(error instanceof Error ? error : new Error(String(error))));
-    worker.on('exit', (code) => fail(new Error(`python worker exited with code ${code}`)));
+    worker.on('exit', (code) => fail(new HarnessError('PYTHON_WORKER_EXITED', [code])));
     worker.unref();
     return {
         read() {

package/dist-lib/lib/tools/exec/obsidian/note-name.js

@@ -1,6 +1,7 @@
+import { HarnessError } from '../../../errors.js';
 export function markdownFileName(name) {
     if (name.includes('/') || name.includes('\\') || name === '.' || name === '..') {
-        throw new Error('name= must be a note name, not a path.');
+        throw new HarnessError('OBSIDIAN_NOTE_NAME_IS_PATH');
     }
     return name.endsWith('.md') ? name : `${name}.md`;
 }

package/dist-lib/lib/tools/exec/obsidian/safe-path.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../../errors.js';
 function lstatOrNull(p) {
     try {
         return fs.lstatSync(p);
@@ -18,7 +19,7 @@ function rejectSymlinkComponents(root, target) {
             return;
         }
         if (stat.isSymbolicLink()) {
-            throw new Error(`Path "${target}" crosses a symlink inside the vault.`);
+            throw new HarnessError('OBSIDIAN_PATH_CROSSES_SYMLINK', [target]);
         }
     }
 }
@@ -26,7 +27,7 @@ export function ensureWithinRoot(root, rel) {
     const resolvedRoot = path.resolve(root);
     const target = path.resolve(resolvedRoot, rel);
     if (target !== resolvedRoot && !target.startsWith(resolvedRoot + path.sep)) {
-        throw new Error(`Path "${rel}" escapes the vault root.`);
+        throw new HarnessError('OBSIDIAN_PATH_ESCAPES_VAULT', [rel]);
     }
     rejectSymlinkComponents(resolvedRoot, target);
     return target;
@@ -36,7 +37,7 @@ export function isSymlink(p) {
 }
 export function writeNewFileText(filePath, content) {
     if (fs.existsSync(filePath)) {
-        throw new Error(`Destination already exists: ${filePath}`);
+        throw new HarnessError('OBSIDIAN_DESTINATION_EXISTS', [filePath]);
     }
     let fd;
     try {
@@ -44,7 +45,7 @@ export function writeNewFileText(filePath, content) {
     }
     catch (error) {
         if (fs.existsSync(filePath)) {
-            throw new Error(`Destination already exists: ${filePath}`);
+            throw new HarnessError('OBSIDIAN_DESTINATION_EXISTS', [filePath]);
         }
         throw error;
     }

package/dist-lib/lib/tools/exec/obsidian/vault-create.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../../errors.js';
 import { markdownFileName } from './note-name.js';
 import { ensureWithinRoot, getArg, getContentArg, writeNewFileText } from './vault-paths.js';
 function markdownPath(vaultPath, target) {
@@ -20,7 +21,7 @@ function createNamed(vaultPath, { name, folder, content }) {
     const fileName = markdownFileName(name);
     const filePath = ensureWithinRoot(vaultPath, path.join(folder, fileName));
     if (fs.existsSync(filePath)) {
-        throw new Error(`Note "${name}" already exists at ${folder || '/'}`);
+        throw new HarnessError('OBSIDIAN_NOTE_EXISTS', [name, folder || '/']);
     }
     writeNewFileText(filePath, content);
     return `Created: ${folder ? `${folder}/` : ''}${fileName}`;
@@ -42,7 +43,7 @@ export function handleCreate(vaultPath, args) {
     }
     const target = filePath ?? file;
     if (!target) {
-        throw new Error('Missing required argument: name=, file=, or path=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['name=, file=, or path=']);
     }
     return createAtPath(vaultPath, target, content || '');
 }

package/dist-lib/lib/tools/exec/obsidian/vault-fs.js

@@ -1,3 +1,4 @@
+import { HarnessError } from '../../../errors.js';
 import { handleCreate } from './vault-create.js';
 import { todayStamp } from './vault-paths.js';
 import { handleDailyRead, handleFiles, handleFolders, handleOutline, handleProperties, handleRead, handleSearch, handleTags, handleVault, handleVaults, handleWordcount } from './vault-read.js';
@@ -51,7 +52,6 @@ export function executeVaultFsAction(vaultPath, action, args) {
         case 'daily:path':
             return `Daily Notes/${todayStamp()}.md`;
         default:
-            throw new Error(`Action "${action}" is not supported in vault file mode. ` +
-                `This action requires the Obsidian CLI connected to the running app.`);
+            throw new HarnessError('OBSIDIAN_ACTION_UNSUPPORTED', [action]);
     }
 }

package/dist-lib/lib/tools/exec/obsidian/vault-paths.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../../errors.js';
 import { ensureWithinRoot, isSymlink, writeNewFileText } from './safe-path.js';
 export { ensureWithinRoot, writeNewFileText } from './safe-path.js';
 export const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
@@ -90,13 +91,13 @@ export function writeIfUnchanged(filePath, content, expectedMtimeMs) {
     }
     if (expectedMtimeMs === null) {
         if (current) {
-            throw new Error(`Note changed on disk during update (file appeared): ${path.basename(filePath)}`);
+            throw new HarnessError('OBSIDIAN_NOTE_CHANGED', ['file appeared', path.basename(filePath)]);
         }
         fs.writeFileSync(filePath, content);
         return;
     }
     if (!current || current.mtimeMs !== expectedMtimeMs) {
-        throw new Error(`Note changed on disk during update (re-read and retry): ${path.basename(filePath)}`);
+        throw new HarnessError('OBSIDIAN_NOTE_CHANGED', ['re-read and retry', path.basename(filePath)]);
     }
     fs.writeFileSync(filePath, content);
 }

package/dist-lib/lib/tools/exec/obsidian/vault-read.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../../errors.js';
 import { dailyCandidates, ensureWithinRoot, FRONTMATTER_RE, getArg, listFolders, listMarkdownFiles, parseFrontmatter, readFileText, resolveNotePath, todayStamp } from './vault-paths.js';
 export function handleVault(vaultPath) {
     return JSON.stringify({ name: path.basename(vaultPath), path: vaultPath });
@@ -17,7 +18,7 @@ export function handleVaults(vaultPath) {
 export function handleRead(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     return readFileText(notePath);
 }
@@ -43,7 +44,7 @@ function parseLimit(args) {
 export function handleSearch(vaultPath, args) {
     const query = getArg(args, 'query');
     if (!query) {
-        throw new Error('Missing required argument: query=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['query=']);
     }
     const limit = parseLimit(args);
     const lowerQuery = query.toLowerCase();
@@ -70,7 +71,7 @@ export function handleSearch(vaultPath, args) {
 export function handleProperties(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     return JSON.stringify(parseFrontmatter(readFileText(notePath)), null, 2);
 }
@@ -99,7 +100,7 @@ export function handleTags(vaultPath) {
 export function handleWordcount(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const body = readFileText(notePath).replace(FRONTMATTER_RE, '').trim();
     const words = body.split(/\s+/).filter(Boolean).length;
@@ -108,7 +109,7 @@ export function handleWordcount(vaultPath, args) {
 export function handleOutline(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const headings = readFileText(notePath)
         .split('\n')