akm-cli 0.9.0-beta.2 → 0.9.0-beta.26

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

@@ -133,24 +133,188 @@ export const ImproveProcessConfigSchema = z
     // consolidation pass skips entirely (emits `pool_below_min_size`). 0 disables
     // the guard. Only meaningful on the `consolidate` process. Default 500.
     minPoolSize: z.number().int().min(0).optional(),
+    // Consolidate process: deterministic near-duplicate dedup pre-pass (#617).
+    // A cheap, no-LLM fast path that collapses obvious duplicates (`.derived`
+    // origin pairs + content twins) before the LLM consolidation. Default OFF
+    // — when absent the consolidate pass behaves byte-identically to today.
+    // `cosineThreshold` is a strict floor in [0, 1] (default 0.97) for the
+    // optional embedding-similarity match; exact normalized content-hash
+    // equality always collapses regardless of the threshold. Only meaningful
+    // on the `consolidate` process.
+    dedup: z
+        .object({
+        enabled: z.boolean().optional(),
+        cosineThreshold: z.number().min(0).max(1).optional(),
+        // WS-3a: maximum pool size for the O(n²) cosine-similarity twin compare.
+        // Only the first `cosineCandidateLimit` memories are cosine-compared;
+        // exact-hash matches still run over the full pool. Default 500. Raise
+        // with care — cost is O(n²).
+        cosineCandidateLimit: z.number().int().positive().optional(),
+    })
+        .strict()
+        .optional(),
+    // Consolidate process: judged-state cache (#581). When enabled, a memory
+    // whose current content hash equals its cached judged hash is SKIPPED from
+    // the LLM pool (judged-unchanged → no re-judge), letting one run sweep the
+    // whole corpus at O(changed/new) cost instead of narrowing to a recent
+    // time-window slice. Default OFF — when absent the consolidate pass behaves
+    // byte-identically to today (the incrementalSince path is unaffected). Only
+    // meaningful on the `consolidate` process.
+    judgedCache: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     qualityGate: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     contradictionDetection: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     // Extract process config (only meaningful for extract process)
     defaultSince: z.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
+    // Extract process: minimum raw session size (pre-filter inputCount) below
+    // which the extract LLM call is skipped (#595/#596). 0 disables the gate.
+    // Absent = default 10 (skip only truly empty sessions). Only meaningful
+    // on the `extract` process.
+    minContentChars: z.number().int().min(0).optional(),
     maxChunkSize: z.number().int().min(1).max(50).optional(),
+    // Consolidate process: narrow candidate pool to memories modified within
+    // this duration window plus their graph neighbours. Only meaningful on
+    // the `consolidate` process. Absent = full-pool sweep.
+    incrementalSince: z.string().optional(),
+    // Consolidate process: hard cap on memories processed per pass.
+    // Reflect/distill: max refs processed (same as profile-level `limit`).
+    limit: positiveInt.optional(),
+    // Consolidate process: graph neighbours per changed memory during
+    // incremental consolidation. Default 5. Only meaningful with incrementalSince.
+    neighborsPerChanged: z.number().int().min(1).optional(),
+    // Distill process: skip distill entirely when reflect produced zero planned refs.
+    requirePlannedRefs: z.boolean().optional(),
+    // proactiveMaintenance process (Layer 2): staleness gate + rotation cooldown
+    // in days (default 30). Only meaningful on `proactiveMaintenance`.
+    dueDays: z.number().int().min(0).optional(),
+    // proactiveMaintenance process: top-N bound per run (default 25). Alias for
+    // `limit`; `maxPerRun` wins when both are set.
+    maxPerRun: positiveInt.optional(),
+    // MemoryInference process: minimum pending memory count to run the pass.
+    minPendingCount: z.number().int().min(0).optional(),
     // Extract process: minimum number of new (unseen, in-window) candidate
     // sessions below which the extract pass skips entirely (emits an
     // `improve_skipped` event with `reason: "below_min_new_sessions"`). 0
     // disables the guard. Only meaningful on the `extract` process. Default 0
     // (disabled) so existing behaviour is preserved; only opted-in profiles set it.
     minNewSessions: z.number().int().min(0).optional(),
+    // Extract process: cap on NEW sessions processed (LLM-called) per run; the
+    // rest roll to the next run (still unseen). 0 disables. Absent = default 25.
+    maxSessionsPerRun: z.number().int().min(0).optional(),
     // #561 — index agent sessions as a searchable `session` asset (extract
     // process). Absent = on-when-an-LLM-is-available (fail-open when offline).
     indexSessions: z.boolean().optional(),
     // #561 — minimum session duration in minutes for session indexing. 0
     // disables the gate. Absent = default 5. Only meaningful on `extract`.
     minSessionDuration: z.number().min(0).optional(),
+    // Consolidate process: fallback p90 wall-clock time per consolidation chunk
+    // in seconds, used for cold-start budget estimation when no telemetry
+    // history exists. The actual p90 is derived from observed run durations
+    // once sufficient history accumulates; this value is only used on the very
+    // first run. Default 30 s. Only meaningful on the `consolidate` process.
+    p90ChunkSecondsDefault: z.number().finite().positive().optional(),
+    // WS-3b: Homeostatic demotion (step 0a). Before any LLM merge, demote
+    // retrievalSalience for stale/low-value assets so the merge pool is bounded
+    // and high-SNR. Demotion is state.db-only (file content untouched);
+    // re-promotable on re-retrieval. Default OFF. Only meaningful on the
+    // `consolidate` process.
+    homeostaticDemotion: z
+        .object({
+        enabled: z.boolean().optional(),
+        // Minimum days since last retrieval to consider an asset stale (default 30).
+        staleDays: z.number().int().min(0).optional(),
+        // Demotion factor: multiply retrievalSalience by this when stale (default 0.5).
+        demotionFactor: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Schema-similarity gate (step 0b). At intake, if a new candidate's
+    // body embedding is within epsilon of an existing derived-layer lesson/knowledge
+    // node, mark it schema-consistent and lower its priority. Default OFF.
+    // Only meaningful on the `consolidate` and `extract` processes.
+    schemaSimilarity: z
+        .object({
+        enabled: z.boolean().optional(),
+        // Epsilon: cosine similarity threshold above which a candidate is schema-consistent
+        // (default 0.85 — looser than dedup's 0.97 since we want to catch conceptual overlap).
+        epsilon: z.number().min(0).max(1).optional(),
+        // Multiplicative factor applied to candidate confidence when schema-consistent.
+        // Default 0.5 — halves the confidence so schema-consistent candidates are less likely
+        // to pass the quality gate and create redundant stash entries.
+        confidencePenalty: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Hot-probation intake buffer (step 0c, #604). New system-generated
+    // extractions enter captureMode: hot-probation and spend ONE consolidation
+    // cycle in probation. Dedup + quality second-pass runs before promotion.
+    // Default OFF. Only meaningful on the `extract` process.
+    hotProbation: z
+        .object({
+        enabled: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Anti-collapse guards (step 8). Prevents the consolidation pipeline
+    // from collapsing too aggressively and losing diversity.
+    //   - maxGeneration: refuse to merge two assets both above this generation (default 2).
+    //   - lexicalDiversityCheck: low n-gram diversity ⇒ raise merge threshold.
+    //   - randomClusterFraction: occasional random (non-similar) cluster in pool (default 0.05).
+    // Default OFF. Only meaningful on the `consolidate` process.
+    antiCollapse: z
+        .object({
+        enabled: z.boolean().optional(),
+        maxGeneration: z.number().int().min(1).optional(),
+        lexicalDiversityCheck: z.boolean().optional(),
+        randomClusterFraction: z.number().min(0).max(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: CLS (Complementary Learning System) interleaving (step 9).
+    // distill/memoryInference prompts include embedding-retrieved existing adjacent
+    // lessons/knowledge to prevent catastrophic interference with prior generalizations.
+    // Default OFF. Only meaningful on `distill` and `memoryInference` processes.
+    cls: z
+        .object({
+        enabled: z.boolean().optional(),
+        // Number of adjacent lessons/knowledge to include in prompts (default 3).
+        adjacentCount: z.number().int().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    // WS-3b: Distill→source fidelity check (step 10). After a distill proposal,
+    // check it against its cited source memories; a contradiction flag forces
+    // human review. Default OFF. Only meaningful on `distill` process.
+    fidelityCheck: z
+        .object({
+        enabled: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
+    // #609 — recombine process: minimum related-memory cluster size before an
+    // LLM generalization call. Default 3. Only meaningful on `recombine`.
+    minClusterSize: z.number().int().min(2).optional(),
+    // #609 — recombine process: hard cap on clusters processed per run (one
+    // bounded LLM call each). Default 5. Only meaningful on `recombine`.
+    maxClustersPerRun: positiveInt.optional(),
+    // #609 — recombine process: relatedness signal used to form clusters
+    // (tags | graph | both). Clustering is by relatedness, never embedding
+    // similarity. Default "tags". Only meaningful on `recombine`.
+    relatednessSource: z.enum(["tags", "graph", "both"]).optional(),
+    // #609 — recombine process: consecutive re-inductions required before a
+    // hypothesis is promoted to a lesson. Default 2. Only meaningful on
+    // `recombine`.
+    confirmThreshold: z.number().int().min(1).optional(),
+    // #615 — procedural process: minimum number of distinct assets sharing the
+    // same successful normalized ordered-action sequence before it is compiled
+    // into a workflow proposal. Default 3. Only meaningful on `procedural`.
+    minRecurrence: z.number().int().min(2).optional(),
+    // #615 — procedural process: hard cap on workflow proposals emitted per run
+    // (one bounded LLM call each). Default 3. Only meaningful on `procedural`.
+    maxProposalsPerRun: positiveInt.optional(),
+    // #615 — procedural process: asset type a compiled sequence is emitted as.
+    // Reserved; v1 always emits "workflow". Only meaningful on `procedural`.
+    emitAs: z.enum(["workflow", "skill"]).optional(),
     // Triage process config (only meaningful for the `triage` process)
     applyMode: z.enum(["queue", "promote"]).optional(),
     policy: z.string().min(1).optional(),
@@ -176,6 +340,9 @@ const ImproveProfileProcessesSchema = z
     graphExtraction: ImproveProcessConfigSchema.optional(),
     validation: ImproveProcessConfigSchema.optional(),
     triage: ImproveProcessConfigSchema.optional(),
+    proactiveMaintenance: ImproveProcessConfigSchema.optional(),
+    recombine: ImproveProcessConfigSchema.optional(),
+    procedural: ImproveProcessConfigSchema.optional(),
 })
     .passthrough()
     .superRefine((val, ctx) => {
@@ -199,6 +366,9 @@ const ImproveProfileProcessesSchema = z
         "validation",
         "extract",
         "triage",
+        "proactiveMaintenance",
+        "recombine",
+        "procedural",
     ]);
     for (const k of Object.keys(raw)) {
         if (!allowed.has(k)) {
@@ -216,6 +386,12 @@ export const ImproveProfileConfigSchema = z
     processes: ImproveProfileProcessesSchema.optional(),
     autoAccept: nonNegativeNumber.optional(),
     limit: positiveInt.optional(),
+    // #614 — symmetric valence weighting in the eligibility sort. When true,
+    // the attention term becomes |valence| MAGNITUDE so BOTH strong positive
+    // and strong negative feedback drive attention (utility stays dominant) and
+    // strong-signed assets are routed to a fix/reinforce lane. DEFAULT OFF —
+    // false/absent preserves the legacy negative-only ranking byte-for-byte.
+    symmetricValence: z.boolean().optional(),
     sync: z
         .object({
         enabled: z.boolean().optional(),
@@ -332,6 +508,7 @@ const SearchGraphBoostSchema = z
 export const SearchConfigSchema = z
     .object({
     minScore: nonNegativeNumber.optional(),
+    defaultExcludeTypes: z.array(nonEmptyString).optional(),
     curateRerank: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     graphBoost: SearchGraphBoostSchema.optional(),
 })
@@ -350,10 +527,74 @@ const ImproveUtilityDecaySchema = z
     feedbackStabilityBoost: z.number().finite().min(1).optional(),
 })
     .strict();
+// #612 / WS-4 — auto-accept gate calibration + bounded, opt-in per-phase
+// threshold auto-tune. DEFAULT OFF: when absent (or `autoTune: false`) no
+// tuning occurs, so the gate behaves byte-identically to today.
+// WS-4 adds: per-phase persistence (state.db) + auto-tune ceiling default 85.
+const ImproveCalibrationSchema = z
+    .object({
+    /** Master switch for the bounded threshold auto-tune. Default false (parity). */
+    autoTune: z.boolean().optional(),
+    /** Lower bound (0-100) the tuned threshold may never drop below. */
+    minThreshold: z.number().int().min(0).max(100).optional(),
+    /**
+     * Upper bound (0-100) the tuned threshold may never rise above.
+     * WS-4 default: 85 (prevents gate converging to pure exploitation).
+     */
+    maxThreshold: z.number().int().min(0).max(100).optional(),
+    /** Maximum adjustment magnitude (points) applied in one tune step. */
+    maxStep: positiveInt.optional(),
+    /** Minimum acted-on sample count required before any adjustment. */
+    minSamples: nonNegativeNumber.optional(),
+    /** Target realized accept rate in [0, 1]. Default 0.9. */
+    targetAcceptRate: z.number().finite().min(0).max(1).optional(),
+})
+    .strict();
+// WS-4 — exploration budget: a fixed fraction of proposals accepted per run
+// regardless of confidence. DEFAULT OFF.
+const ImproveExplorationSchema = z
+    .object({
+    /**
+     * Enable the exploration budget lane. Default false (parity).
+     * When true, a fraction of proposals are accepted regardless of confidence.
+     */
+    enabled: z.boolean().optional(),
+    /**
+     * Fraction of proposals per run to accept as exploration [0, 1].
+     * Default 0.05 (5%). Clamped to [0, 1] at read time.
+     */
+    budgetFraction: z.number().finite().min(0).max(1).optional(),
+})
+    .strict();
+const ImproveSalienceSchema = z
+    .object({
+    /**
+     * WS-2 Part-V gate: enable the outcome-weight term in the salience projection.
+     * Default false (parity — WS-1 weights w_e=0.30, w_r=0.70 until Part-V confirms
+     * no regression). Set to true after running scripts/akm-eval + health report.
+     */
+    outcomeWeightEnabled: z.boolean().optional(),
+    /**
+     * Minimum encoding salience score [0, 1] for a zero-feedback asset to be
+     * admitted to the high-salience improve lane (#608).
+     * Default 0.75. Set to 1.0 to disable the lane entirely.
+     */
+    salienceThreshold: z.number().min(0).max(1).optional(),
+    /**
+     * Per-run additive replay budget (#610). Up to this many top-salience refs are
+     * revisited even with no reactive signal and regardless of cooldown. Additive
+     * on top of --limit. Default 0 = no replay.
+     */
+    replayBudget: z.number().int().min(0).optional(),
+})
+    .strict();
 export const ImproveConfigSchema = z
     .object({
     utilityDecay: ImproveUtilityDecaySchema.optional(),
     eventRetentionDays: nonNegativeNumber.optional(),
+    calibration: ImproveCalibrationSchema.optional(),
+    exploration: ImproveExplorationSchema.optional(),
+    salience: ImproveSalienceSchema.optional(),
 })
     .strict();
 // ── Index / per-pass ────────────────────────────────────────────────────────

package/dist/core/config/config.js

@@ -249,8 +249,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

package/dist/core/logs-db.js

@@ -0,0 +1,305 @@
+// 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 { applyStandardPragmas } from "../storage/sqlite-pragmas.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. foreignKeys:false preserves this
+    // opener's historical behaviour — logs.db has never enforced foreign keys.
+    applyStandardPragmas(db, { dataDir: dir, foreignKeys: false });
+    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

@@ -215,6 +215,9 @@ export function getDataDir(env = process.env, platform = process.platform) {
 export function getDbPath() {
     return path.join(getDataDir(), "index.db");
 }
+export function getIndexWriterLockPath() {
+    return path.join(getDataDir(), "index.db.write.lock");
+}
 export function getWorkflowDbPath() {
     return path.join(getDataDir(), "workflow.db");
 }