akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

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

@@ -9,8 +9,8 @@ import { VALID_HARNESS_IDS } from "../../integrations/harnesses/index.js";
 /**
  * Canonical list of valid agent harness / platform ids. Re-exported from the
  * unified harness registry (#562) so the Zod `AgentPlatformSchema` enum, the
- * `AgentProfileConfigV2` platform union, `parseAgentProfilesMapV2`'s membership
- * check, and setup's `DetectedHarness` union all derive from one place and
- * cannot drift. Add a harness in `src/integrations/harnesses/index.ts`.
+ * `AgentProfileConfig` platform union, and setup's `DetectedHarness` union all
+ * derive from one place and cannot drift. Add a harness in
+ * `src/integrations/harnesses/index.ts`.
  */
 export { VALID_HARNESS_IDS };

package/dist/core/config/config.js

@@ -13,20 +13,9 @@ import { warn } from "../warn.js";
 // Canonical harness-id source of truth (#565) — runtime value re-export.
 export { VALID_HARNESS_IDS } from "./config-types.js";
 // ── Feedback failure-mode constants (F-3 / #384) ────────────────────────────
-/**
- * Curated taxonomy of failure modes for negative feedback.
- *
- * Structured failure modes enable aggregation across feedback events so the
- * distill pipeline can detect that "5 assets failed for the same reason" and
- * act on it — free-text strings about the same issue are not aggregatable.
- */
-export const FEEDBACK_FAILURE_MODES = [
-    "incorrect", // Factually wrong or logically flawed content
-    "outdated", // Correct at some point but now stale
-    "dangerous", // Could cause harm if followed (security, safety)
-    "incomplete", // Missing key steps, context, or caveats
-    "redundant", // Duplicates another asset without adding value
-];
+// Canonical taxonomy lives in the schema/validator layer; re-exported here so
+// existing `../core/config/config` import sites keep working.
+export { FEEDBACK_FAILURE_MODES } from "./config-schema.js";
 /**
  * Default value for {@link IndexPassConfig.graphExtractionBatchSize}. Chosen
  * empirically: 4 amortises the per-call HTTP overhead 4× while keeping the
@@ -205,6 +194,25 @@ export function getDefaultLlmConfig(config) {
         return undefined;
     return config.profiles?.llm?.[defaultName];
 }
+/**
+ * Resolve the per-process config section for an improve process,
+ * centralizing the deeply-nested lookup
+ * `profile?.processes?.<name>` that was previously copy-pasted across the
+ * improve command family (20+ call sites).
+ *
+ * When an `activeProfile` is supplied (the profile resolved for the current
+ * `akm improve --profile <name>` run), its per-process override wins; otherwise
+ * — and as a fallback when the active profile does not define the section — the
+ * lookup falls back to the `"default"` improve profile from the on-disk config.
+ * Callers that have not yet threaded the active profile pass only `config` and
+ * get the historical default-profile behavior unchanged.
+ */
+export function getImproveProcessConfig(config, processName, activeProfile) {
+    const fromActiveProfile = activeProfile?.processes?.[processName];
+    if (fromActiveProfile !== undefined)
+        return fromActiveProfile;
+    return config.profiles?.improve?.default?.processes?.[processName];
+}
 /**
  * Run `migrateConfigShape` on the raw text and — unless `AKM_NO_AUTO_MIGRATE=1`
  * is set — persist the migrated result. Returns the (possibly migrated) text
@@ -221,7 +229,18 @@ function maybeAutoMigrateConfigFile(configPath, text) {
     catch {
         return text; // Malformed JSON — let parseAndValidate surface the error.
     }
-    if (compareConfigVersion(obj.configVersion, CURRENT_CONFIG_VERSION) === 1) {
+    // Downgrade protection. Skip migration when the on-disk config is NEWER than
+    // this binary (=== 1), OR when it carries a configVersion we cannot order
+    // against ours (compareConfigVersion returns undefined for an unparseable
+    // value — e.g. one written by a newer/foreign akm). Migrating such a config
+    // could strip fields a newer binary added, a cross-version data-loss path.
+    //
+    // A MISSING configVersion (absent → undefined) is a legacy pre-versioning
+    // config that MUST still migrate, so the unparseable-skip is gated on the
+    // field being PRESENT (`onDiskVersion !== undefined`).
+    const onDiskVersion = obj.configVersion;
+    const versionOrder = compareConfigVersion(onDiskVersion, CURRENT_CONFIG_VERSION);
+    if (versionOrder === 1 || (onDiskVersion !== undefined && versionOrder === undefined)) {
         return text;
     }
     const { changed, result } = migrateConfigShape(obj);
@@ -249,8 +268,8 @@ function maybeAutoMigrateConfigFile(configPath, text) {
             "  to preview a dry-run diff:            akm config migrate --dry-run --print-diff",
             "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
         ].join("\n");
-        process.stderr.write(`${banner}\n`);
-        process.stdout.write(`${banner}\n`);
+        process.stderr?.write?.(`${banner}\n`);
+        process.stdout?.write?.(`${banner}\n`);
     }
     catch (err) {
         // #461: never return migrated bytes when disk write fails — that triggers
@@ -267,15 +286,32 @@ export function loadConfig() {
     warnIfProjectConfigPresent(process.cwd());
     return loadUserConfig();
 }
+let saveConfigOverride;
+/** TEST-ONLY. Swap the implementation of `saveConfig`; pass undefined to restore. */
+export function _setSaveConfigForTests(fake) {
+    saveConfigOverride = fake;
+}
 export function saveConfig(config) {
+    if (saveConfigOverride) {
+        saveConfigOverride(config);
+        return;
+    }
+    saveConfigReal(config);
+}
+function saveConfigReal(config) {
     cachedConfig = undefined;
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
     const sanitized = sanitizeConfigForWrite(config);
-    // Final validation gate before bytes hit disk. Catches schema violations
-    // (unknown keys in registries[] / sources[] / profiles.*; out-of-range
-    // numbers; etc. — closes #462) before we corrupt the user's config.
+    // Final validation gate before bytes hit disk. Runs the FULL schema —
+    // including the cross-field superRefine guards (removed `feedbackDistillation`
+    // process key, `defaultWriteTarget` resolution, writable npm/website sources)
+    // and all type/enum/range checks — so an `akm config set` (leaf OR object
+    // form) cannot persist a guard-violating or mistyped value. NOTE: unknown
+    // keys are intentionally NOT rejected here — object schemas are `.passthrough()`
+    // so cross-version skew round-trips (see config-schema.ts header); the lenient
+    // tolerance is by design, not an oversight.
     const parseResult = AkmConfigSchema.safeParse(sanitized);
     if (!parseResult.success) {
         const lines = parseResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
@@ -398,7 +434,11 @@ export function resolveSecret(value) {
  * filtering out the reserved feature-section keys so callers don't mistake
  * `metadataEnhance` / `stalenessDetection` for a pass.
  */
-/** Reserved well-known keys on IndexConfig that are NOT per-pass entries. */
+/**
+ * Reserved well-known keys on IndexConfig that are NOT per-pass entries.
+ * `stalenessDetection` is retired (10-Q3) but stays reserved so a leftover
+ * config section is never misread as a pass entry.
+ */
 const INDEX_RESERVED_KEYS = new Set(["metadataEnhance", "stalenessDetection"]);
 export function getIndexPassConfig(config, passName) {
     if (!config)
@@ -450,7 +490,12 @@ function applyRuntimeEnvApiKeys(config) {
     }
     // LLM profile keys: AKM_LLM_API_KEY for the default profile, then
     // AKM_PROFILE_<UPPER>_API_KEY for any profile (per-profile wins).
-    const defaultProfile = next.defaults?.llm;
+    // Resolve the default profile the SAME way the rest of the config layer does
+    // (resolveDefaultLlmProfileName), so the implicit `profiles.llm.default`
+    // fallback is honored. Keying off the raw `defaults.llm` field alone silently
+    // dropped AKM_LLM_API_KEY for configs that rely on the implicit default —
+    // the same no-op-run class as the 2026-05-23 incident.
+    const defaultProfile = resolveDefaultLlmProfileName(next);
     if (next.profiles?.llm) {
         const updated = { ...next.profiles.llm };
         let changed = false;

package/dist/core/deep-merge.js

@@ -0,0 +1,38 @@
+// 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/.
+/**
+ * Generic recursive object merge, extracted from the setup wizard (it is not
+ * setup-specific). Plain objects merge key-by-key; arrays and scalars replace
+ * wholesale. Used to apply a partial `--file` config over the existing config
+ * without dropping sibling subkeys.
+ */
+/** True for non-null, non-array plain objects. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Recursively merge `incoming` into `base`: plain objects merge key-by-key,
+ * while arrays and scalars replace wholesale. A partial input therefore only
+ * updates the keys it carries and never drops sibling subkeys (e.g. a file
+ * containing `{ output: { format: "text" } }` leaves `output.detail` intact).
+ *
+ * `base` is treated as immutable — a fresh object graph is returned.
+ */
+export function deepMergeConfig(base, incoming) {
+    if (!isPlainObject(incoming))
+        return incoming;
+    const baseObj = isPlainObject(base) ? base : {};
+    const out = { ...baseObj };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (value === undefined)
+            continue;
+        if (isPlainObject(value) && isPlainObject(baseObj[key])) {
+            out[key] = deepMergeConfig(baseObj[key], value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}

package/dist/core/errors.js

@@ -14,6 +14,7 @@ const CONFIG_HINTS = {
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_STASH_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.",
     SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_STASH_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The stash directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
+    UNKNOWN_IMPROVE_PROFILE: "Pass one of the listed profile names to `--profile`, or define it under `profiles.improve` in your config. Names are case-sensitive.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {

package/dist/core/eval/rank-metrics.js

@@ -0,0 +1,113 @@
+// 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/.
+export const DEFAULT_CURATE_WEIGHTS = {
+    ndcg: 0.5,
+    recall: 0.2,
+    mrr: 0.1,
+    noBannedAboveRequired: 0.2,
+};
+/** nDCG@k with binary relevance: gain 1 for relevant refs, 0 otherwise. */
+export function ndcgAtK(returned, relevant, k) {
+    const top = returned.slice(0, k);
+    let dcg = 0;
+    for (let i = 0; i < top.length; i++) {
+        if (relevant.has(top[i]))
+            dcg += 1 / Math.log2(i + 2);
+    }
+    const idealCount = Math.min(k, relevant.size);
+    let idcg = 0;
+    for (let i = 0; i < idealCount; i++)
+        idcg += 1 / Math.log2(i + 2);
+    return idcg === 0 ? 1 : dcg / idcg;
+}
+export function recallAtK(returned, relevant, k) {
+    if (relevant.size === 0)
+        return 1;
+    const top = new Set(returned.slice(0, k));
+    let hit = 0;
+    for (const r of relevant)
+        if (top.has(r))
+            hit += 1;
+    return hit / relevant.size;
+}
+export function mrr(returned, relevant) {
+    for (let i = 0; i < returned.length; i++) {
+        if (relevant.has(returned[i]))
+            return 1 / (i + 1);
+    }
+    return 0;
+}
+/**
+ * Leapfrog gate. A banned ref "leapfrogs" when it appears ABOVE at least one
+ * present relevant ref. Returns the fraction of present banned refs that do
+ * NOT leapfrog (1.0 when no banned ref is present, or none leapfrog), plus the
+ * raw violation count.
+ */
+export function noBannedAboveRequired(returned, relevant, banned) {
+    const rankOf = new Map();
+    returned.forEach((ref, i) => {
+        if (!rankOf.has(ref))
+            rankOf.set(ref, i);
+    });
+    const relevantRanks = returned.map((ref, i) => (relevant.has(ref) ? i : -1)).filter((i) => i >= 0);
+    if (relevantRanks.length === 0) {
+        // No relevant ref present to be leapfrogged — gate is vacuously satisfied.
+        return { score: 1, leapfrogCount: 0 };
+    }
+    const worstRelevantRank = Math.max(...relevantRanks);
+    const bannedPresent = returned.filter((ref) => banned.has(ref));
+    if (bannedPresent.length === 0)
+        return { score: 1, leapfrogCount: 0 };
+    let leapfrog = 0;
+    for (const b of bannedPresent) {
+        const rb = rankOf.get(b);
+        if (rb !== undefined && rb < worstRelevantRank)
+            leapfrog += 1;
+    }
+    return { score: 1 - leapfrog / bannedPresent.length, leapfrogCount: leapfrog };
+}
+/** Score a single curate result (ordered refs) against its judgment. */
+export function scoreCurateCase(returned, judgment, weights = DEFAULT_CURATE_WEIGHTS) {
+    const k = judgment.limit;
+    const relevant = new Set(judgment.relevant);
+    const banned = new Set(judgment.banned);
+    const ndcg = ndcgAtK(returned, relevant, k);
+    const recall = recallAtK(returned, relevant, k);
+    const rr = mrr(returned, relevant);
+    const gate = noBannedAboveRequired(returned, relevant, banned);
+    const score = ndcg * weights.ndcg + recall * weights.recall + rr * weights.mrr + gate.score * weights.noBannedAboveRequired;
+    return {
+        ndcg,
+        recall,
+        mrr: rr,
+        noBannedAboveRequired: gate.score,
+        bannedLeapfrogCount: gate.leapfrogCount,
+        score,
+    };
+}
+/** Aggregate per-case metrics into a suite summary. */
+export function summarizeCurateMetrics(metrics) {
+    const n = metrics.length;
+    if (n === 0) {
+        return {
+            caseCount: 0,
+            meanScore: 0,
+            meanNdcg: 0,
+            meanRecall: 0,
+            meanMrr: 0,
+            meanNoBannedAboveRequired: 1,
+            totalBannedLeapfrog: 0,
+        };
+    }
+    const sum = (sel) => metrics.reduce((a, m) => a + sel(m), 0);
+    return {
+        caseCount: n,
+        meanScore: sum((m) => m.score) / n,
+        meanNdcg: sum((m) => m.ndcg) / n,
+        meanRecall: sum((m) => m.recall) / n,
+        meanMrr: sum((m) => m.mrr) / n,
+        meanNoBannedAboveRequired: sum((m) => m.noBannedAboveRequired) / n,
+        totalBannedLeapfrog: sum((m) => m.bannedLeapfrogCount),
+    };
+}

package/dist/core/events.js

@@ -25,9 +25,10 @@
  * - `ts` is ISO-8601 (UTC, millisecond precision).
  */
 import path from "node:path";
+import { insertEvent, readStateEvents } from "../storage/repositories/events-repository.js";
 import { rethrowIfTestIsolationError } from "./errors.js";
 import { getDataDir } from "./paths.js";
-import { insertEvent, openStateDatabase, readStateEvents } from "./state-db.js";
+import { openStateDatabase, withStateDb } from "./state-db.js";
 import { error } from "./warn.js";
 /**
  * Legacy events.jsonl path — used only by the migration script
@@ -82,18 +83,14 @@ export function appendEvent(input, ctx) {
     // Default path: open, insert, close.
     const dbPath = resolveDbPath(ctx);
     try {
-        const db = openStateDatabase(dbPath);
-        try {
+        withStateDb((db) => {
             insertEvent(db, {
                 eventType: input.eventType,
                 ts,
                 ref: input.ref,
                 metadata: input.metadata,
             });
-        }
-        finally {
-            db.close();
-        }
+        }, { path: dbPath });
     }
     catch (err) {
         // Never mask the bun-test isolation guard as a silent "events failed".

package/dist/core/improve-types.js

@@ -11,16 +11,18 @@ import { assertNever } from "./assert.js";
  *
  * Buckets:
  * - `accepted` — a write/content-authoring action succeeded.
- * - `rejected` — the action was deliberately not applied (cooldown, skip,
- *   distill-skip, or a content-policy guard rejection). NOTE: as of the
- *   round-2 health pass `reflect-guard-rejected` is bucketed here. Previously
- *   the `state-db.ts` switch omitted it entirely (no case, no default), so a
- *   guard rejection silently vanished from accepted/rejected/error totals — a
- *   data-integrity miscount. It is a deliberate non-application of the action,
- *   so it belongs with the other "rejected" outcomes.
+ * - `skipped` — the ref was GATED OUT before any content was produced: a
+ *   cooldown, a signal-delta/eligibility skip, or a distill pool-delta skip.
+ *   These are NOT rejections of produced content — they are the run declining
+ *   to act on a ref it had no new reason to touch, and they scale with the
+ *   whole indexed-ref pool (~13k/run), so folding them into `rejected` made the
+ *   "accept rate" meaningless (deep-tuning analysis 2026-06-29, finding #1).
+ * - `rejected` — the run PRODUCED a change and a content-policy guard then
+ *   rejected it (`reflect-guard-rejected`). This is the genuine value-rejection
+ *   signal; it is small and meaningful, no longer drowned by gated skips.
  * - `error` — the action failed (LLM/runtime error).
  * - `noop` — bookkeeping that is neither a write nor a rejection (memory-prune);
- *   intentionally counted in none of the three numeric buckets.
+ *   intentionally counted in none of the numeric buckets.
  *
  * The `default: assertNever(mode)` arm makes any future union variant a
  * compile-time error here, forcing an explicit bucket choice.
@@ -35,6 +37,7 @@ export function classifyImproveAction(mode) {
         case "reflect-cooldown":
         case "reflect-skipped":
         case "distill-skipped":
+            return "skipped";
         case "reflect-guard-rejected":
             return "rejected";
         case "reflect-failed":
@@ -46,3 +49,39 @@ export function classifyImproveAction(mode) {
             return assertNever(mode);
     }
 }
+/** Upper bound on retained sample refs PER reason in {@link DistillSkippedAggregate}. */
+export const DISTILL_SKIPPED_SAMPLE_CAP_PER_REASON = 3;
+/**
+ * Partition an action list into the rows to persist and the `distill-skipped`
+ * aggregate. Pure — no I/O. Called once at improve-result assembly time so the
+ * serialized envelope never carries per-ref distill-skipped rows.
+ *
+ * Non-`distill-skipped` actions are returned verbatim and in order. When there
+ * are zero distill-skipped actions the aggregate is omitted (the envelope stays
+ * byte-identical to a run that skipped nothing).
+ */
+export function foldDistillSkipped(actions) {
+    const kept = [];
+    const byReason = {};
+    const samples = [];
+    const sampleCountByReason = {};
+    let total = 0;
+    for (const action of actions) {
+        if (action.mode !== "distill-skipped") {
+            kept.push(action);
+            continue;
+        }
+        total += 1;
+        const r = action.result;
+        const reason = typeof r?.reason === "string" && r.reason.trim() ? r.reason : "unknown";
+        byReason[reason] = (byReason[reason] ?? 0) + 1;
+        const seen = sampleCountByReason[reason] ?? 0;
+        if (seen < DISTILL_SKIPPED_SAMPLE_CAP_PER_REASON) {
+            sampleCountByReason[reason] = seen + 1;
+            samples.push({ ref: action.ref, reason });
+        }
+    }
+    if (total === 0)
+        return { actions: kept };
+    return { actions: kept, aggregate: { total, byReason, samples } };
+}

package/dist/core/logs-db.js

@@ -16,8 +16,10 @@
  * Log lines are high-volume, append-only, and freely purgeable; state.db rows
  * (events, proposals, task_history) are durable records. Separating them keeps
  * state.db small and lets log retention be aggressive without touching durable
- * state. Cross-db queries (e.g. "failed task_history row → its log lines") use
- * SQLite ATTACH — see {@link attachStateDatabase}.
+ * state. Callers that need to correlate a task_history row with its log lines do
+ * an application-side join on the {@link buildTaskRunId} key (e.g. `health` via
+ * {@link getLoggedRunIds}) — no SQLite ATTACH, so the split survives a future
+ * provider change.
  *
  * ## run_id
  *
@@ -35,12 +37,10 @@
  *
  * @module logs-db
  */
-import fs from "node:fs";
 import path from "node:path";
-import { openDatabase } from "../storage/database.js";
 import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { openManagedDatabase } from "../storage/managed-db.js";
 import { getDataDir } from "./paths.js";
-import { getStateDbPath } from "./state-db.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/logs.db` — alongside state.db so cooperating
@@ -70,16 +70,13 @@ export function getLogsDbPath() {
  */
 export function openLogsDatabase(dbPath) {
     const resolvedPath = dbPath ?? getLogsDbPath();
-    const dir = path.dirname(resolvedPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    const db = openDatabase(resolvedPath);
-    // PRAGMAs must run before any DDL or DML.
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 30000");
-    runMigrations(db);
-    return db;
+    // foreignKeys:false preserves this opener's historical behaviour — logs.db
+    // has never enforced foreign keys.
+    return openManagedDatabase({
+        path: resolvedPath,
+        pragmas: { dataDir: path.dirname(resolvedPath), foreignKeys: false },
+        init: runMigrations,
+    });
 }
 // ── Migrations ───────────────────────────────────────────────────────────────
 /**
@@ -145,8 +142,8 @@ export function runMigrations(db) {
  * Encode a task run's identity — the unique `(task_id, started_at)` pair from
  * state.db `task_history` — as a single run_id string.
  *
- * The format MUST stay in sync with the SQL expression
- * `task_id || '@' || started_at` used by {@link queryFailedRunLogLines}.
+ * The format MUST stay in sync with the application-side join key that callers
+ * build from a `task_history` row's `task_id` and `started_at`.
  */
 export function buildTaskRunId(taskId, startedAtIso) {
     return `${taskId}@${startedAtIso}`;
@@ -229,64 +226,6 @@ export function getLoggedRunIds(db, runIds) {
     }
     return out;
 }
-// ── Cross-db: ATTACH state.db ────────────────────────────────────────────────
-/**
- * ATTACH state.db to an open logs.db handle under the schema name `state`,
- * enabling cross-db joins like task_history × task_logs.
- *
- * The state.db file must already exist (callers always open state.db first in
- * practice); attaching a non-existent path would silently create an empty,
- * unmigrated database file, so this throws instead.
- */
-export function attachStateDatabase(db, stateDbPath) {
-    const resolved = stateDbPath ?? getStateDbPath();
-    if (!fs.existsSync(resolved)) {
-        throw new Error(`Cannot ATTACH state.db: file does not exist at ${resolved}`);
-    }
-    // prepare().run() rather than db.run(): both drivers support parameterised
-    // ATTACH through a prepared statement, and no other call site uses db.run().
-    db.prepare("ATTACH DATABASE ? AS state").run(resolved);
-}
-/**
- * Convenience: open logs.db with state.db attached as `state`. The returned
- * handle supports cross-db queries such as {@link queryFailedRunLogLines}.
- * Close it like any other handle (DETACH is implicit on close).
- */
-export function openLogsDatabaseWithState(logsDbPath, stateDbPath) {
-    const db = openLogsDatabase(logsDbPath);
-    try {
-        attachStateDatabase(db, stateDbPath);
-    }
-    catch (err) {
-        db.close();
-        throw err;
-    }
-    return db;
-}
-/**
- * Cross-db join: every log line belonging to a FAILED task_history run whose
- * `started_at` is `>= since` (all failed runs when omitted). Requires a handle
- * opened via {@link openLogsDatabaseWithState}.
- *
- * The join key is the run_id encoding documented on {@link buildTaskRunId}:
- * `task_logs.run_id = task_history.task_id || '@' || task_history.started_at`.
- */
-export function queryFailedRunLogLines(db, options = {}) {
-    const conditions = ["th.status = 'failed'"];
-    const params = [];
-    if (options.since) {
-        conditions.push("th.started_at >= ?");
-        params.push(options.since);
-    }
-    const limit = options.limit !== undefined && options.limit >= 0 ? ` LIMIT ${Math.floor(options.limit)}` : "";
-    return db
-        .prepare(`SELECT th.task_id, l.run_id, th.started_at, th.status, l.ts, l.stream, l.level, l.line
-       FROM state.task_history th
-       JOIN task_logs l ON l.run_id = th.task_id || '@' || th.started_at
-       WHERE ${conditions.join(" AND ")}
-       ORDER BY th.started_at DESC, l.id ASC${limit}`)
-        .all(...params);
-}
 // ── Retention ────────────────────────────────────────────────────────────────
 /**
  * Delete task_logs rows older than `retentionDays` (default: 90). Mirrors

package/dist/core/parse.js

@@ -98,16 +98,24 @@ export function parseJsonResponse(raw) {
  * balanced `{ }` or `[ ]` structure in the text and attempts to parse that
  * substring. Returns `undefined` if no valid JSON structure is found.
  *
- * Non-array results are preferred: if a `{…}` object is found first, it is
- * returned immediately. Arrays (`[…]`) are captured as a fallback and
- * returned only when no object was found.
+ * Shape preference is controlled by {@link ParseEmbeddedJsonOptions.expect}:
+ * - `"any"` (default): non-array results are preferred — a `{…}` object found
+ *   first is returned immediately; arrays (`[…]`) are a fallback.
+ * - `"array"`: only top-level arrays are returned. The direct parse is
+ *   accepted only if it is an array, and the scanner returns the first
+ *   balanced `[…]` while skipping `{…}` openers entirely.
  */
-export function parseEmbeddedJsonResponse(raw) {
+export function parseEmbeddedJsonResponse(raw, options) {
+    const expectArray = options?.expect === "array";
     const direct = parseJsonResponse(raw);
-    if (direct !== undefined)
+    if (direct !== undefined && (!expectArray || Array.isArray(direct)))
         return direct;
     const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
     let arrayFallback;
+    // Scan only *top-level* balanced structures: once a `{…}`/`[…]` is matched we
+    // jump `start` past its closing bracket rather than re-scanning its interior.
+    // This keeps array mode from salvaging an array *nested inside* a leading
+    // object (e.g. the `entities` array of a bare `{entities,relations}` object).
     for (let start = 0; start < text.length; start++) {
         const opener = text[start];
         if (opener !== "{" && opener !== "[")
@@ -116,6 +124,7 @@ export function parseEmbeddedJsonResponse(raw) {
         let depth = 0;
         let inString = false;
         let escaped = false;
+        let end = -1;
         for (let i = start; i < text.length; i++) {
             const ch = text[i];
             if (inString) {
@@ -139,20 +148,31 @@ export function parseEmbeddedJsonResponse(raw) {
             if (ch === closer) {
                 depth -= 1;
                 if (depth === 0) {
-                    try {
-                        const parsed = JSON.parse(text.slice(start, i + 1));
-                        if (!Array.isArray(parsed)) {
-                            return parsed;
-                        }
-                        arrayFallback ??= parsed;
-                        break;
-                    }
-                    catch {
-                        break;
-                    }
+                    end = i;
+                    break;
                 }
             }
         }
+        if (end === -1)
+            continue; // never balanced — let the next opener try
+        try {
+            const parsed = JSON.parse(text.slice(start, end + 1));
+            if (Array.isArray(parsed)) {
+                // First valid array wins in array mode; in "any" mode it is the
+                // fallback returned only if no object is found.
+                if (expectArray)
+                    return parsed;
+                arrayFallback ??= parsed;
+            }
+            else if (!expectArray) {
+                return parsed;
+            }
+            // Skip past this balanced structure so we don't descend into it.
+            start = end;
+        }
+        catch {
+            // Malformed candidate — advance one char and try the next opener.
+        }
     }
     return arrayFallback;
 }