akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/core/common.js

@@ -83,6 +83,75 @@ export function readTextFileWithLimit(filePath, maxBytes, label = "File") {
  *      don't fail on those mounts. Windows does not support opening a
  *      directory for fsync, so the directory-sync step is skipped there.
  */
+/**
+ * Strip JavaScript-style comments from a JSON string (JSONC support).
+ * Handles `//` line comments and `/* *​/` block comments while preserving
+ * comment-like sequences inside quoted strings.
+ */
+export function stripJsonComments(text) {
+    let result = "";
+    let i = 0;
+    let inString = false;
+    while (i < text.length) {
+        if (inString) {
+            if (text[i] === "\\") {
+                result += text[i] + (text[i + 1] ?? "");
+                i += 2;
+                continue;
+            }
+            if (text[i] === '"') {
+                inString = false;
+            }
+            result += text[i];
+            i++;
+            continue;
+        }
+        if (text[i] === '"') {
+            inString = true;
+            result += text[i];
+            i++;
+            continue;
+        }
+        if (text[i] === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (text[i] === "/" && text[i + 1] === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i += 2;
+            continue;
+        }
+        result += text[i];
+        i++;
+    }
+    return result;
+}
+/**
+ * The mode to rewrite an existing USER-owned file with.
+ *
+ * {@link writeFileAtomic} creates its temp file with an explicit mode and
+ * chmods it, so it needs one — and its 0600 default is right for akm's own
+ * state but wrong for a user's asset, where rewriting must never change
+ * permissions. Returns the file's current mode, or the umask-derived default
+ * `fs.writeFileSync` would have produced for a new file.
+ */
+export function existingFileMode(filePath) {
+    try {
+        return fs.statSync(filePath).mode & 0o777;
+    }
+    catch {
+        // Absent (a new asset) or unreadable: fall back to the default create mode.
+        try {
+            return 0o666 & ~process.umask();
+        }
+        catch {
+            return 0o644;
+        }
+    }
+}
 export function writeFileAtomic(target, content, mode) {
     const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
     const data = typeof content === "string" ? Buffer.from(content) : content;
@@ -226,7 +295,11 @@ function readStashDirFromConfig() {
     try {
         const configPath = getConfigPath();
         const text = readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
-        const raw = JSON.parse(text);
+        // The config loader accepts JSONC, so a commented config.json is valid and
+        // in use. Parsing it raw here threw, the catch swallowed it, and every
+        // caller silently fell back — operating on the wrong bundle or failing with
+        // STASH_DIR_NOT_FOUND despite a perfectly good config.
+        const raw = JSON.parse(stripJsonComments(text));
         if (typeof raw !== "object" || raw === null)
             return undefined;
         // 0.9.0 config-shape cutover (spec §10.1): the primary stash is the
@@ -292,13 +365,49 @@ export function hasErrnoCode(error, code) {
         return false;
     return error.code === code;
 }
+/**
+ * True when `value` is a RELATIVE path that cannot leave its base directory:
+ * no absolute form (POSIX `/`, Windows `\` or a `C:` drive prefix), no `~`
+ * home expansion, and no `..` segment under either separator.
+ *
+ * This is the SYNTACTIC half of containment — cheap, string-only, usable at
+ * authoring time before any directory exists. It is deliberately paired with
+ * (never a substitute for) {@link isWithin}, which resolves symlinks against a
+ * real base at use time. Workflow `exec` units run both: the parser and the
+ * frozen-plan decoder reject uncontained spellings, and the executor re-checks
+ * the resolved path before spawning.
+ */
+export function isContainedRelativePath(value) {
+    if (value === "" || value.startsWith("/") || value.startsWith("\\") || value.startsWith("~"))
+        return false;
+    if (/^[A-Za-z]:/.test(value))
+        return false;
+    return !value.split(/[/\\]+/).includes("..");
+}
 export function isWithin(candidate, root) {
-    const resolvedRoot = safeRealpath(root);
-    const resolvedCandidate = safeRealpath(candidate);
-    const normalizedRoot = normalizeFsPathForComparison(resolvedRoot);
-    const normalizedCandidate = normalizeFsPathForComparison(resolvedCandidate);
-    const rel = path.relative(normalizedRoot, normalizedCandidate);
-    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    return isContainedResolvedPath(safeRealpath(candidate), safeRealpath(root));
+}
+/**
+ * {@link isWithin} for callers that must not block the event loop (e.g. the
+ * workflow exec dispatch path, which runs once per fan-out unit). Same
+ * comparison, same normalization, same nearest-existing-ancestor fallback —
+ * only the realpath syscalls are awaited.
+ */
+export async function isWithinAsync(candidate, root) {
+    return isContainedResolvedPath(await safeRealpathAsync(candidate), await safeRealpathAsync(root));
+}
+/** The containment comparison shared by {@link isWithin} and {@link isWithinAsync}. */
+function isContainedResolvedPath(resolvedCandidate, resolvedRoot) {
+    const rel = path.relative(normalizeFsPathForComparison(resolvedRoot), normalizeFsPathForComparison(resolvedCandidate));
+    if (rel === "")
+        return true;
+    if (path.isAbsolute(rel))
+        return false;
+    // Compare the first SEGMENT, not a string prefix: `..data` and `...v2` are
+    // legal directory names, and only a leading `..` segment means the candidate
+    // climbed out of the root. Both separators, because `path.relative` answers
+    // in the host's spelling while callers may hold either.
+    return rel.split(/[/\\]+/)[0] !== "..";
 }
 /**
  * Resolve symlinks on `p`, walking up to the closest existing ancestor when
@@ -335,6 +444,30 @@ export function safeRealpath(p) {
         }
     }
 }
+/** {@link safeRealpath}'s async twin — awaited syscalls, identical walk-up. */
+export async function safeRealpathAsync(p) {
+    const resolved = path.resolve(p);
+    try {
+        return await fs.promises.realpath(resolved);
+    }
+    catch {
+        const suffix = [];
+        let current = resolved;
+        for (;;) {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return resolved;
+            suffix.unshift(path.basename(current));
+            current = parent;
+            try {
+                return path.join(await fs.promises.realpath(current), ...suffix);
+            }
+            catch {
+                // parent also doesn't exist; keep walking up
+            }
+        }
+    }
+}
 function normalizeFsPathForComparison(value) {
     return process.platform === "win32" ? value.toLowerCase() : value;
 }
@@ -718,14 +851,19 @@ export function stringArray(value) {
  * Return true if a process with the given PID is currently alive.
  * Uses `process.kill(pid, 0)` which does not deliver a signal but
  * throws ESRCH when the process does not exist.
+ *
+ * EPERM means the process EXISTS but belongs to another uid, so it must be
+ * reported alive. Treating it as dead let a lock held by a live process in a
+ * shared data dir (agent sandboxes, containers, service accounts — a
+ * configuration managed-db.ts explicitly supports) be reclaimed as stale.
  */
 export function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (err) {
+        return err?.code === "EPERM";
     }
 }
 /**

package/dist/core/concurrent.js

@@ -1,6 +1,32 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Serialize `fn` behind every task previously enqueued under `key`: an
+ * in-process keyed promise chain (Bun is single-threaded, so this is a
+ * sufficient — and free — admission control for per-key mutual exclusion).
+ *
+ * `chains` is the caller's own module-state map, so independent subsystems
+ * (the unit-writer's per-database write queue, the worktree module's per-repo
+ * git lock) never share chains. A failed task rejects its OWN caller but
+ * never wedges the chain, and a drained tail deletes its map entry so a
+ * long-lived process does not retain one settled promise per key it ever
+ * touched.
+ */
+export function serializeByKey(chains, key, fn) {
+    const tail = chains.get(key) ?? Promise.resolve();
+    const run = tail.then(() => fn());
+    // Keep the chain alive regardless of individual outcomes.
+    const settled = run.then(() => undefined, () => undefined);
+    chains.set(key, settled);
+    // If another task was enqueued in the meantime the map now holds ITS tail,
+    // and this check leaves it alone.
+    void settled.then(() => {
+        if (chains.get(key) === settled)
+            chains.delete(key);
+    });
+    return run;
+}
 /**
  * Maps over items concurrently with a pool size limit.
  * Uses Promise.allSettled semantics — one failure does not cancel others.
@@ -11,6 +37,12 @@
  * preempt those too). Unclaimed items stay `undefined` in the result,
  * indistinguishable from individual failures by design: callers already
  * treat `undefined` as "no result".
+ *
+ * A thrown `fn` is SWALLOWED (its slot stays `undefined`) — a caller that
+ * must report failure detail, or distinguish "threw" from "never claimed",
+ * catches inside `fn` and returns an explicit outcome value instead. This is
+ * the OPPOSITE of {@link serializeByKey} above, whose failures reject their
+ * own caller.
  */
 export async function concurrentMap(items, fn, concurrency = 1, opts) {
     const results = new Array(items.length).fill(undefined);

package/dist/core/config/config-io.js

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { sleepSync } from "../../runtime.js";
-import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit, writeFileAtomic } from "../common.js";
+import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit, stripJsonComments, writeFileAtomic } from "../common.js";
 import { ConfigError } from "../errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
 import { getCacheDir, getConfigDir } from "../paths.js";
@@ -233,48 +233,8 @@ export function withConfigLock(fn) {
     }
 }
 /**
- * Strip JavaScript-style comments from a JSON string (JSONC support).
- * Handles `//` line comments and `/* *​/` block comments while preserving
- * comment-like sequences inside quoted strings.
+ * Re-exported from core/common.ts, where it now lives so `resolveStashDir`
+ * can strip comments too without importing this module (common cannot depend
+ * on config-io — config-io already depends on common).
  */
-export function stripJsonComments(text) {
-    let result = "";
-    let i = 0;
-    let inString = false;
-    while (i < text.length) {
-        if (inString) {
-            if (text[i] === "\\") {
-                result += text[i] + (text[i + 1] ?? "");
-                i += 2;
-                continue;
-            }
-            if (text[i] === '"') {
-                inString = false;
-            }
-            result += text[i];
-            i++;
-            continue;
-        }
-        if (text[i] === '"') {
-            inString = true;
-            result += text[i];
-            i++;
-            continue;
-        }
-        if (text[i] === "/" && text[i + 1] === "/") {
-            while (i < text.length && text[i] !== "\n")
-                i++;
-            continue;
-        }
-        if (text[i] === "/" && text[i + 1] === "*") {
-            i += 2;
-            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
-                i++;
-            i += 2;
-            continue;
-        }
-        result += text[i];
-        i++;
-    }
-    return result;
-}
+export { stripJsonComments } from "../common.js";

package/dist/core/config/schema/engines.js

@@ -14,7 +14,18 @@ import { z } from "zod";
 // `typeof import("./config-schema")` — routing through config-types would mint
 // a config-schema ↔ config-types type cycle that collapses inference.
 import { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS } from "../../../integrations/harnesses/ids.js";
+import { WORKFLOW_MAX_TIMEOUT_MS } from "../../../workflows/resource-limits.js";
 import { chatCompletionsEndpoint, ENV_REFERENCE_PATTERN, ExtraParamsSchema, engineName, LlmCapabilitiesSchema, ModelAliasMapSchema, nonEmptyString, positiveInt, } from "./primitives.js";
+/**
+ * Engine-config timeouts share the workflow ceiling.
+ *
+ * 0.9.1 bounded workflow-authored timeouts (parser) and frozen invocations
+ * (decoder) at 2^31-1, but the third source — `engines.<name>.timeoutMs` — was
+ * validated only as a positive integer. A larger value passed config validation
+ * and then failed EVERY run of that engine with an unlocated "Invalid frozen
+ * workflow plan: invocation is invalid". Reject it where the value is written.
+ */
+const timeoutMsField = z.union([positiveInt.max(WORKFLOW_MAX_TIMEOUT_MS), z.null()]).optional();
 // ── Connection configs (LLM) ────────────────────────────────────────────────
 /**
  * OpenAI-compatible connection fields shared by named LLM engines and bounded
@@ -32,7 +43,7 @@ export const LlmConnectionConfigSchema = z
     apiKey: z.string().optional(),
     temperature: z.number().finite().optional(),
     maxTokens: positiveInt.optional(),
-    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
     capabilities: LlmCapabilitiesSchema.optional(),
     extraParams: ExtraParamsSchema.optional(),
@@ -56,7 +67,7 @@ const LlmEngineSchema = z
     apiKey: z.string().regex(ENV_REFERENCE_PATTERN, `apiKey must be $VAR or \${VAR}`).optional(),
     temperature: z.number().finite().optional(),
     maxTokens: positiveInt.optional(),
-    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
     supportsJsonSchema: z.boolean().optional(),
     extraParams: ExtraParamsSchema.optional(),
@@ -80,7 +91,7 @@ const AgentEngineSchema = z
     args: z.array(z.string()).optional(),
     workspace: nonEmptyString.optional(),
     model: nonEmptyString.optional(),
-    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    timeoutMs: timeoutMsField,
     modelAliases: ModelAliasMapSchema.optional(),
     llmEngine: engineName.optional(),
 })

package/dist/core/config/schema/workflow.js

@@ -19,10 +19,21 @@ import { engineName, positiveInt } from "./primitives.js";
  *     `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]` (64). Values above the ceiling
  *     are clamped, not rejected, so a config shared across machines with wildly
  *     different core counts never hard-fails validation.
+ *
+ * `defaultMapConcurrency` is the width a `map` step freezes when it declares no
+ * `concurrency:` of its own:
+ *   - UNSET  → `DEFAULT_MAP_CONCURRENCY` (4) from
+ *     `src/workflows/concurrency-policy.ts`.
+ *   - SET    → the explicit positive integer, CLAMPED to `[1, 64]`. Setting it
+ *     to `1` restores the pre-0.9.1 serial-by-default fan-out for every
+ *     workflow on this install. It is a floor for authoring only: it never
+ *     raises a step above `maxConcurrency`, the engine's concurrency, or the
+ *     host CPU cap, and it never overrides an authored `map.concurrency`.
  */
 export const WorkflowConfigSchema = z
     .object({
     maxConcurrency: positiveInt.optional(),
+    defaultMapConcurrency: positiveInt.optional(),
     /** Named LLM or agent engine frozen into every criteria-bearing gate. */
     judgeEngine: engineName.optional(),
 })

package/dist/core/errors.js

@@ -9,6 +9,7 @@ const CONFIG_HINTS = {
     STASH_DIR_NOT_FOUND: "Run `akm setup` to create and configure your bundle, or configure a defaultBundle path.",
     STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
+    DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
     LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
@@ -131,3 +132,27 @@ export function rethrowIfTestIsolationError(err) {
         throw err;
     }
 }
+/**
+ * Unreadable-data-dir guard helper — the #791 sibling of the test-isolation
+ * pair above, and it exists for the same reason.
+ *
+ * `DATA_DIR_UNREADABLE` says "this path is there and I am not allowed to read
+ * it". It is raised by `assertIndexPathReadable` and friends precisely so a
+ * permission fault stops being indistinguishable from "nothing indexed yet".
+ * That distinction is destroyed again the moment a best-effort `catch` around
+ * the open collapses it into the same `null`/`[]`/`0` the absent case returns —
+ * which is how `akm search` came to answer "No search index available. Run
+ * 'akm index'" at exit 0 for a populated index sitting right there on disk.
+ *
+ * Call `rethrowIfDataDirUnreadable(err)` from any catch block that returns a
+ * fallback value after touching a data-dir path. Absent stays absent; a fault
+ * the operator has to fix keeps travelling.
+ */
+export function isDataDirUnreadableError(err) {
+    return err instanceof ConfigError && err.code === "DATA_DIR_UNREADABLE";
+}
+export function rethrowIfDataDirUnreadable(err) {
+    if (isDataDirUnreadableError(err)) {
+        throw err;
+    }
+}

package/dist/core/events.js

@@ -4,6 +4,7 @@
 import { insertEvent, readStateEvents } from "../storage/repositories/events-repository.js";
 import { rethrowIfTestIsolationError } from "./errors.js";
 import { getStateDbPath, openStateDatabase, withStateDb } from "./state-db.js";
+import { borrowScopedStateDb } from "./state-db-scope.js";
 import { error } from "./warn.js";
 /**
  * Resolve the state.db path from context:
@@ -28,36 +29,41 @@ function resolveNow(ctx) {
  * function writes directly to that handle without opening or closing the DB.
  * This eliminates per-event open/migrate/close overhead for high-frequency
  * callers such as `akmImprove`.
+ *
+ * The same fast path is taken IMPLICITLY inside a `withStateDbScope` /
+ * `withWorkflowRunsConnection` scope (`core/state-db-scope.ts`): the ambient
+ * scoped handle for this event's resolved `dbPath` is borrowed, so a workflow
+ * step's `workflow_unit_started` / `workflow_unit_finished` pair rides the same
+ * connection its journal rows do instead of opening state.db twice per unit.
+ * The scope owns that handle's lifetime; `appendEvent` never closes a borrowed
+ * connection.
  */
 export function appendEvent(input, ctx) {
     const now = resolveNow(ctx);
     const ts = new Date(now()).toISOString();
-    // Fast path: caller provided a long-lived connection — use it directly.
-    if (ctx?.db) {
-        try {
-            insertEvent(ctx.db, {
-                eventType: input.eventType,
-                ts,
-                ref: input.ref,
-                metadata: input.metadata,
-            });
+    const row = { eventType: input.eventType, ts, ref: input.ref, metadata: input.metadata };
+    // One try covers EVERY path — including resolving the state.db path, which
+    // reads the environment and throws where no data dir can be derived — so the
+    // best-effort contract ("a write failure never propagates") holds no matter
+    // which handle this event lands on.
+    try {
+        // Fast path: an explicitly supplied long-lived connection. Resolution is
+        // skipped outright, which is what "`dbPath` is ignored when `db` is
+        // provided" has to mean for a caller that already holds an open handle.
+        if (ctx?.db) {
+            insertEvent(ctx.db, row);
+            return;
         }
-        catch (err) {
-            error(`akm: appendEvent failed: ${String(err)}`);
+        const dbPath = resolveDbPath(ctx);
+        // The ambient scoped handle for this path, when a scope is open — borrowed
+        // exactly like the explicit one, and never closed here.
+        const borrowed = borrowScopedStateDb(dbPath);
+        if (borrowed) {
+            insertEvent(borrowed, row);
+            return;
         }
-        return;
-    }
-    // Default path: open, insert, close.
-    const dbPath = resolveDbPath(ctx);
-    try {
-        withStateDb((db) => {
-            insertEvent(db, {
-                eventType: input.eventType,
-                ts,
-                ref: input.ref,
-                metadata: input.metadata,
-            });
-        }, { path: dbPath });
+        // Default path: open, insert, close.
+        withStateDb((db) => insertEvent(db, row), { path: dbPath });
     }
     catch (err) {
         // Never mask the bun-test isolation guard as a silent "events failed".

package/dist/core/extra-params.js

@@ -33,8 +33,16 @@ export function validateExtraParams(value) {
         return [{ path: [], message: "must be an object" }];
     }
     const issues = [];
+    // A self-referential YAML anchor (`extraParams: &a { nested: *a }`) resolves
+    // to a genuinely cyclic object — the yaml package's alias-count guard does not
+    // catch cycles — so an unguarded walk overflowed the stack with a RangeError
+    // that escaped task parsing. Track visited containers and stop at a revisit.
+    const seen = new WeakSet();
     const visit = (entry, path) => {
         if (Array.isArray(entry)) {
+            if (seen.has(entry))
+                return;
+            seen.add(entry);
             entry.forEach((child, index) => {
                 visit(child, [...path, index]);
             });
@@ -42,6 +50,9 @@ export function validateExtraParams(value) {
         }
         if (!entry || typeof entry !== "object")
             return;
+        if (seen.has(entry))
+            return;
+        seen.add(entry);
         for (const [key, child] of Object.entries(entry)) {
             const normalized = normalizeExtraParamKey(key);
             if (path.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {

package/dist/core/file-lock.js

@@ -139,7 +139,13 @@ export function probeLock(lockPath, opts) {
     try {
         snapshot = readLockSnapshot(lockPath);
     }
-    catch {
+    catch (error) {
+        // A permission error means the lock may be genuinely HELD by someone we
+        // cannot see. Reporting it as stale would invite a caller to steal a live
+        // lease (#791) — `unreadable` stays for the corrupt/undecodable case.
+        const code = error?.code;
+        if (code === "EACCES" || code === "EPERM")
+            return { state: "inaccessible", code };
         return { state: "stale", reason: "unreadable" };
     }
     if (!snapshot)

package/dist/core/fs-txn.js

@@ -81,7 +81,11 @@ export function txnFileHash(filePath) {
     return txnHash(fs.readFileSync(filePath));
 }
 export function fsyncTxnFile(filePath) {
-    const fd = fs.openSync(filePath, "r");
+    // Open for WRITE. Windows implements fsync as FlushFileBuffers, which
+    // requires write access on the handle — a read-only descriptor fails with
+    // EACCES/EPERM, so every proposal accept and reject failed on that platform.
+    // POSIX accepts "r+" here just as readily as "r".
+    const fd = fs.openSync(filePath, "r+");
     try {
         fs.fsyncSync(fd);
     }
@@ -91,7 +95,16 @@ export function fsyncTxnFile(filePath) {
 }
 export function fsyncTxnDir(dirPath) {
     try {
-        fsyncTxnFile(dirPath);
+        // Read-only, unlike {@link fsyncTxnFile}: a directory cannot be opened for
+        // write on POSIX (EISDIR), and on Windows this whole operation is
+        // unsupported anyway and falls into the catch.
+        const fd = fs.openSync(dirPath, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
     }
     catch {
         // Directory fsync is unavailable on some platforms.

package/dist/core/improve-result.js

@@ -40,6 +40,7 @@ const COMMON_FIELDS = [
     "cycleMetrics",
     "runId",
     "sync",
+    "writtenPaths",
     "terminated",
 ];
 const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
@@ -83,10 +84,14 @@ function validateCommon(value) {
         "extract",
         "coverageGaps",
         "deadUrls",
+        "writtenPaths",
     ]) {
         if (value[field] !== undefined && !Array.isArray(value[field]))
             fail(`${field} must be an array`);
     }
+    if (Array.isArray(value.writtenPaths) && value.writtenPaths.some((entry) => typeof entry !== "string")) {
+        fail("writtenPaths must be an array of strings");
+    }
     for (const field of [
         "cyclesRun",
         "evalCasesWritten",