akm-cli 0.8.7 → 0.8.14

package/dist/core/{config-walker.js → config/config-walker.js}

@@ -21,8 +21,8 @@
  *   - z.record(...)        → JSON-parse value, validate
  */
 import { z } from "zod";
-import { AkmConfigBaseSchema, listTopLevelConfigKeys } from "./config-schema";
-import { UsageError } from "./errors";
+import { UsageError } from "../errors.js";
+import { AkmConfigBaseSchema, listTopLevelConfigKeys } from "./config-schema.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.

package/dist/core/{config.js → config/config.js}

@@ -3,13 +3,15 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "./config-io";
-import { CURRENT_CONFIG_VERSION, compareConfigVersion, migrateConfigShape } from "./config-migration";
-import { AkmConfigSchema } from "./config-schema";
-import { ConfigError } from "./errors";
-export { stripJsonComments } from "./config-io";
-import { getCacheDir, getConfigPath } from "./paths";
-import { warn } from "./warn";
+import { ConfigError } from "../errors.js";
+import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "./config-io.js";
+import { CURRENT_CONFIG_VERSION, compareConfigVersion, migrateConfigShape } from "./config-migration.js";
+import { AkmConfigSchema } from "./config-schema.js";
+export { stripJsonComments } from "./config-io.js";
+import { getCacheDir, getConfigPath } from "../paths.js";
+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.
@@ -409,7 +411,7 @@ export function getIndexPassConfig(config, passName) {
     return entry;
 }
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
-export { parseSourceSpec, resolveConfiguredSources } from "./config-sources";
+export { parseSourceSpec, resolveConfiguredSources } from "./config-sources.js";
 /**
  * Merge a partial user-config override onto a base config. Used by
  * {@link loadUserConfig} (DEFAULT_CONFIG + on-disk) and {@link updateConfig}

package/dist/core/env-secret-ref.js

@@ -0,0 +1,90 @@
+// 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/.
+/**
+ * Shared ref-resolution helpers for the `env` and `secret` command families
+ * (WS6). These were duplicated/co-located inline in `src/cli.ts`; hoisting them
+ * here lets `src/commands/env/env-cli.ts` and `src/commands/env/secret-cli.ts` import a
+ * single copy of the parse/resolve/make + path-traversal-guard logic (the WS6
+ * "env traversal-guard copies 5 → 1" KPI). Behaviour is byte-identical to the
+ * inline forms: env/secret VALUES are never read or surfaced here — these
+ * helpers only resolve refs to absolute paths and guard against directory
+ * traversal.
+ */
+import path from "node:path";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
+import { parseAssetRef } from "./asset/asset-ref.js";
+import { resolveAssetPathFromName } from "./asset/asset-spec.js";
+import { isWithin } from "./common.js";
+import { loadConfig } from "./config/config.js";
+import { NotFoundError, UsageError } from "./errors.js";
+export function parseEnvRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `env:${ref}`);
+}
+export function findEnvSource(origin) {
+    const sources = resolveSourceEntries(undefined, loadConfig());
+    if (sources.length === 0) {
+        throw new UsageError("No stashes configured. Run `akm init` to create your working stash.");
+    }
+    if (!origin || origin === "local")
+        return sources[0];
+    const named = sources.find((source) => source.registryId === origin);
+    if (!named) {
+        throw new NotFoundError(`Source not found for origin: ${origin}`);
+    }
+    return named;
+}
+export function makeEnvRef(name, source) {
+    return source?.registryId ? `${source.registryId}//env:${name}` : `env:${name}`;
+}
+/**
+ * Resolve an env ref to an absolute `.env` path. Accepts `env:` and
+ * `environment:` (alias) refs as well as bare names. The path is returned even
+ * when the file does not yet exist (so `create` writes under `env/`).
+ */
+export function resolveEnvPath(ref) {
+    const parsed = parseEnvRef(ref);
+    if (parsed.type !== "env") {
+        throw new UsageError(`Expected an env ref (env:<name>); got "${ref}".`);
+    }
+    const source = findEnvSource(parsed.origin);
+    const envRoot = path.join(source.path, "env");
+    const envPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the env directory.
+    // validateName already rejects traversal patterns like "../../foo", but an
+    // absolute-path override or symlink-based attack could still escape without
+    // this second check.
+    if (!isWithin(envPath, envRoot)) {
+        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+    }
+    return { name: parsed.name, absPath: envPath, source, parsedRef: parsed, dir: "env" };
+}
+export function parseSecretRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `secret:${ref}`);
+}
+export function makeSecretRef(name, source) {
+    return source?.registryId ? `${source.registryId}//secret:${name}` : `secret:${name}`;
+}
+export function resolveSecretPath(ref, 
+// Create-only (`secret set`): enforce a flat ref name and apply `--path` as
+// the subdirectory. Lookup callers omit this so nested refs keep resolving.
+create) {
+    const parsed = parseSecretRef(ref);
+    if (parsed.type !== "secret") {
+        throw new UsageError(`Expected a secret ref (secret:<name>); got "${ref}".`);
+    }
+    if (create) {
+        assertFlatAssetName(parsed.name);
+        parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
+    }
+    // Source resolution is identical for every asset type; reuse the env helper.
+    const source = findEnvSource(parsed.origin);
+    const typeRoot = path.join(source.path, "secrets");
+    const absPath = resolveAssetPathFromName("secret", typeRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
+    }
+    return { name: parsed.name, absPath, source };
+}

package/dist/core/errors.js

@@ -34,8 +34,16 @@ const NOT_FOUND_HINTS = {
     WORKFLOW_NOT_FOUND: "Run `akm workflow list --active` to see runs.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
 };
+/**
+ * Base class for all akm-thrown, classified errors. Carries the `kind`
+ * discriminant consumed by the CLI exit-code classifier. Errors that are NOT
+ * instances of `AkmError` are treated as genuinely unexpected (INTERNAL).
+ */
+export class AkmError extends Error {
+}
 /** Raised when configuration or environment is invalid or missing. */
-export class ConfigError extends Error {
+export class ConfigError extends AkmError {
+    kind = "config";
     code;
     _hint;
     constructor(msg, code = "INVALID_CONFIG_FILE", hint) {
@@ -51,7 +59,8 @@ export class ConfigError extends Error {
     }
 }
 /** Raised when the user supplies invalid arguments or input. */
-export class UsageError extends Error {
+export class UsageError extends AkmError {
+    kind = "usage";
     code;
     _hint;
     constructor(msg, code = "INVALID_FLAG_VALUE", hint) {
@@ -67,7 +76,8 @@ export class UsageError extends Error {
     }
 }
 /** Raised when a requested resource (asset, entry, file) is not found. */
-export class NotFoundError extends Error {
+export class NotFoundError extends AkmError {
+    kind = "not-found";
     code;
     _hint;
     constructor(msg, code = "ASSET_NOT_FOUND", hint) {

package/dist/core/events.js

@@ -1,11 +1,34 @@
 // 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/.
+/**
+ * Append-only events stream — backed by state.db (#204, Phase 3).
+ *
+ * Every mutating CLI verb funnels through `appendEvent` so external
+ * observers (sync, replication, audit, dashboards) can react to stash
+ * changes. Events are stored in the `events` table in `state.db`
+ * (SQLite, WAL mode) instead of a flat `events.jsonl` file.
+ *
+ * The helper is the only thing in akm that writes to the events table. It
+ * accepts an injectable `dbPath` (via `EventsContext`) so tests can pin a
+ * tmpdir without any global mutation.
+ *
+ * Format (each EventEnvelope):
+ *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
+ *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
+ *
+ * - `id` is a monotonic SQLite AUTOINCREMENT rowid. Callers can persist it
+ *   as a durable cursor for `--since` resumption (replaces the old byte-offset
+ *   cursor). The public API still surfaces this as `nextOffset` (an opaque
+ *   number) for backward compatibility with callers that stored byte-offset
+ *   cursors.
+ * - `ts` is ISO-8601 (UTC, millisecond precision).
+ */
 import path from "node:path";
-import { rethrowIfTestIsolationError } from "./errors";
-import { getDataDir } from "./paths";
-import { insertEvent, openStateDatabase, readStateEvents } from "./state-db";
-import { error } from "./warn";
+import { rethrowIfTestIsolationError } from "./errors.js";
+import { getDataDir } from "./paths.js";
+import { insertEvent, openStateDatabase, readStateEvents } from "./state-db.js";
+import { error } from "./warn.js";
 /**
  * Legacy events.jsonl path — used only by the migration script
  * (`scripts/migrate-storage.ts`) to import existing event history into

package/dist/core/file-lock.js

@@ -2,7 +2,7 @@
 // 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/.
 import fs from "node:fs";
-import { isProcessAlive } from "./common";
+import { isProcessAlive } from "./common.js";
 /**
  * Atomically create a sentinel at `lockPath` with `payload` as the body.
  * Returns true if we now own the lock, false if a sentinel already

package/dist/core/improve-types.js

@@ -0,0 +1,48 @@
+// 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/.
+import { assertNever } from "./assert.js";
+/**
+ * Map an {@link ImproveActionMode} to its coarse audit bucket. Single source of
+ * truth shared by `state-db.ts#computeImproveRunMetrics` and
+ * `improve.ts#emitImproveCompletedEvent` so the aggregate accepted/rejected/
+ * error counts can never disagree between the persisted `metrics_json` and the
+ * emitted `improve_completed` event.
+ *
+ * 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.
+ * - `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.
+ *
+ * The `default: assertNever(mode)` arm makes any future union variant a
+ * compile-time error here, forcing an explicit bucket choice.
+ */
+export function classifyImproveAction(mode) {
+    switch (mode) {
+        case "reflect":
+        case "distill":
+        case "memory-inference":
+        case "graph-extraction":
+            return "accepted";
+        case "reflect-cooldown":
+        case "reflect-skipped":
+        case "distill-skipped":
+        case "reflect-guard-rejected":
+            return "rejected";
+        case "reflect-failed":
+        case "error":
+            return "error";
+        case "memory-prune":
+            return "noop";
+        default:
+            return assertNever(mode);
+    }
+}

package/dist/core/lesson-lint.js

@@ -23,8 +23,8 @@
  * without dragging in the rest of the runtime.
  */
 import fs from "node:fs";
-import { UsageError } from "./errors";
-import { parseFrontmatter } from "./frontmatter";
+import { parseFrontmatter } from "./asset/frontmatter.js";
+import { UsageError } from "./errors.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }

package/dist/core/logs-db.js

@@ -0,0 +1,304 @@
+// 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/.
+/**
+ * logs.db — Dedicated SQLite database for task/run log lines (#579).
+ *
+ * Replaces grep-the-flat-file consumption of `<cacheDir>/tasks/logs/<id>/<ts>.log`
+ * with structured, indexed rows: `{ts, task_id, run_id, stream, level, line}`.
+ * The strategic direction (stop scattering data across files/folders) means
+ * every NEW log consumer queries this database; the per-run text file written
+ * by the task runner is retained only as a transitional tail for humans —
+ * see docs/technical/logs-audit.md for the full producer audit.
+ *
+ * ## Why a separate database from state.db
+ *
+ * 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}.
+ *
+ * ## run_id
+ *
+ * state.db's `task_history` identifies a run by the unique pair
+ * `(task_id, started_at)` (see migration 002 in state-db.ts). logs.db encodes
+ * that pair as a single string — {@link buildTaskRunId} — so log rows can be
+ * joined back to their history row:
+ *
+ *   l.run_id = th.task_id || '@' || th.started_at
+ *
+ * ## Schema evolution
+ *
+ * Same migration-safety contract as state.db: append-only `MIGRATIONS` applied
+ * through the shared runner in src/storage/engines/sqlite-migrations.ts.
+ *
+ * @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 { getDataDir } from "./paths.js";
+import { getStateDbPath } from "./state-db.js";
+// ── Path helper ──────────────────────────────────────────────────────────────
+/**
+ * Default path: `<dataDir>/logs.db` — alongside state.db so cooperating
+ * processes sharing a data root automatically share the same logs database
+ * (same `AKM_DATA_DIR` / XDG env-isolation as {@link getStateDbPath}).
+ */
+export function getLogsDbPath() {
+    return path.join(getDataDir(), "logs.db");
+}
+// ── Database open ────────────────────────────────────────────────────────────
+/**
+ * Open (and initialise / migrate) the logs database.
+ *
+ * @param dbPath - Override the database file path (tests pass a tmpdir path).
+ *
+ * PRAGMA rationale:
+ *
+ *   journal_mode = WAL
+ *     Readers never block writers and vice-versa; crashes are safe (the WAL is
+ *     replayed on next open). Required because the task runner writes log rows
+ *     while `akm health` may be reading them.
+ *
+ *   busy_timeout = 30000
+ *     Log writes happen at the end of scheduled task runs, which can pile up
+ *     (cron fan-out). 30 s of retry absorbs a slow concurrent writer instead of
+ *     surfacing SQLITE_BUSY and dropping log lines.
+ */
+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;
+}
+// ── Migrations ───────────────────────────────────────────────────────────────
+/**
+ * All migrations in application order. APPEND only — never insert in the
+ * middle or reorder. Same contract as state.db's MIGRATIONS array.
+ */
+const MIGRATIONS = [
+    // ── Migration 001 — task_logs ───────────────────────────────────────────────
+    //
+    // One row per log line emitted by a task run.
+    //
+    // Indexed (query) columns:
+    //   ts       TEXT — ISO-8601 UTC; range queries ("logs in the last hour").
+    //   task_id  TEXT — task identifier; per-task log views.
+    //   run_id   TEXT — buildTaskRunId(task_id, started_at); per-run log views
+    //                   and the join key back to state.db task_history.
+    //
+    // Non-indexed columns:
+    //   stream   TEXT — 'stdout' | 'stderr'; which pipe the line came from.
+    //   level    TEXT — 'info' | 'warn' | 'error'; runner-assigned severity
+    //                   ('info' for captured stdout, 'error' for stderr and
+    //                   failure diagnostics).
+    //   line     TEXT — the log line itself (no trailing newline).
+    //
+    // ADD COLUMN extension points (future migrations):
+    //   ALTER TABLE task_logs ADD COLUMN seq INTEGER DEFAULT NULL;
+    //   ALTER TABLE task_logs ADD COLUMN source TEXT DEFAULT NULL;
+    //
+    // TTL: rows where ts < NOW() - retention can be deleted by purgeOldTaskLogs().
+    // No automatic deletion occurs here.
+    {
+        id: "001-task-logs",
+        up: `
+      CREATE TABLE IF NOT EXISTS task_logs (
+        id      INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts      TEXT    NOT NULL,
+        task_id TEXT    NOT NULL,
+        run_id  TEXT    NOT NULL,
+        stream  TEXT    NOT NULL DEFAULT 'stdout',
+        level   TEXT    NOT NULL DEFAULT 'info',
+        line    TEXT    NOT NULL
+      );
+
+      -- Query patterns:
+      --   SELECT … WHERE ts >= ? AND ts <= ?   → idx_task_logs_ts (purge, windows)
+      --   SELECT … WHERE task_id = ?           → idx_task_logs_task_id
+      --   SELECT … WHERE run_id = ?            → idx_task_logs_run_id (per-run tail)
+      CREATE INDEX IF NOT EXISTS idx_task_logs_ts      ON task_logs(ts);
+      CREATE INDEX IF NOT EXISTS idx_task_logs_task_id ON task_logs(task_id);
+      CREATE INDEX IF NOT EXISTS idx_task_logs_run_id  ON task_logs(run_id);
+    `,
+    },
+];
+/**
+ * Apply every pending migration. Called automatically by
+ * {@link openLogsDatabase}; exported for the same test seams state-db exposes.
+ */
+export function runMigrations(db) {
+    runSqliteMigrations(db, MIGRATIONS);
+}
+// ── run_id ───────────────────────────────────────────────────────────────────
+/**
+ * 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}.
+ */
+export function buildTaskRunId(taskId, startedAtIso) {
+    return `${taskId}@${startedAtIso}`;
+}
+/**
+ * Insert a batch of log lines for one task run in a single transaction.
+ * Returns the number of rows inserted. Lines are stored in array order
+ * (ascending rowid), so reading back `ORDER BY id` reproduces emission order.
+ *
+ * Errors propagate — the task runner wraps this in its own best-effort
+ * handling (mirroring `appendHistory`) so an unwritable logs.db never fails
+ * a task run.
+ */
+export function insertTaskLogLines(db, input) {
+    if (input.lines.length === 0)
+        return 0;
+    const stmt = db.prepare(`INSERT INTO task_logs (ts, task_id, run_id, stream, level, line)
+     VALUES (?, ?, ?, ?, ?, ?)`);
+    db.transaction(() => {
+        for (const entry of input.lines) {
+            stmt.run(input.ts, input.taskId, input.runId, entry.stream ?? "stdout", entry.level ?? "info", entry.line);
+        }
+    })();
+    return input.lines.length;
+}
+/**
+ * Read log lines matching the filter, in emission order (ascending id).
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function queryTaskLogs(db, options = {}) {
+    const conditions = [];
+    const params = [];
+    if (options.taskId) {
+        conditions.push("task_id = ?");
+        params.push(options.taskId);
+    }
+    if (options.runId) {
+        conditions.push("run_id = ?");
+        params.push(options.runId);
+    }
+    if (options.stream) {
+        conditions.push("stream = ?");
+        params.push(options.stream);
+    }
+    if (options.since) {
+        conditions.push("ts >= ?");
+        params.push(options.since);
+    }
+    if (options.until) {
+        conditions.push("ts < ?");
+        params.push(options.until);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = options.limit !== undefined && options.limit >= 0 ? ` LIMIT ${Math.floor(options.limit)}` : "";
+    return db
+        .prepare(`SELECT id, ts, task_id, run_id, stream, level, line FROM task_logs ${where} ORDER BY id ASC${limit}`)
+        .all(...params);
+}
+/**
+ * Bulk membership check: which of `runIds` have at least one log row?
+ * Used by `akm health` to compute the log-backing rate from the database
+ * instead of `fs.existsSync` over scattered files. Chunked to stay under
+ * SQLite's bound-parameter ceiling.
+ */
+export function getLoggedRunIds(db, runIds) {
+    const out = new Set();
+    if (runIds.length === 0)
+        return out;
+    const CHUNK = 500;
+    for (let i = 0; i < runIds.length; i += CHUNK) {
+        const chunk = runIds.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT DISTINCT run_id FROM task_logs WHERE run_id IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows)
+            out.add(row.run_id);
+    }
+    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
+ * `purgeOldEvents` / `purgeOldImproveRuns` in state-db.ts — same default, same
+ * return shape (rows deleted), same disabled-when-non-positive semantics.
+ * Wired into the improve maintenance pass alongside the state.db purges.
+ */
+export function purgeOldTaskLogs(db, retentionDays = 90) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return 0;
+    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
+    const result = db.prepare("DELETE FROM task_logs WHERE ts < ?").run(cutoff);
+    const changes = result.changes ?? 0;
+    return typeof changes === "bigint" ? Number(changes) : changes;
+}

package/dist/core/paths.js

@@ -10,8 +10,8 @@
  */
 import os from "node:os";
 import path from "node:path";
-import { IS_WINDOWS } from "./common";
-import { ConfigError } from "./errors";
+import { IS_WINDOWS } from "./common.js";
+import { ConfigError } from "./errors.js";
 /**
  * Returns true when the current process appears to be running under
  * `bun test` (either via the BUN_TEST sentinel Bun sets on the test

package/dist/core/ripgrep/install.js

@@ -4,8 +4,8 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "../common";
-import { RG_BINARY, resolveRg } from "./resolve";
+import { IS_WINDOWS } from "../common.js";
+import { RG_BINARY, resolveRg } from "./resolve.js";
 /**
  * Platform and architecture detection for ripgrep binary downloads.
  */

package/dist/core/ripgrep/resolve.js

@@ -3,8 +3,8 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { IS_WINDOWS } from "../common";
-import { getBinDir } from "../paths";
+import { IS_WINDOWS } from "../common.js";
+import { getBinDir } from "../paths.js";
 export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
 function canExecute(filePath) {
     if (!fs.existsSync(filePath))