akm-cli 0.9.0-beta.5 → 0.9.0-beta.50

package/dist/indexer/search/ranking.js

@@ -20,6 +20,7 @@ export function normalizeFtsScores(results) {
 export function combineSearchScores(options) {
     const FTS_WEIGHT = 0.7;
     const VEC_WEIGHT = 0.3;
+    const excludeTypeSet = options.excludeTypes && options.excludeTypes.length > 0 ? new Set(options.excludeTypes) : null;
     const scored = [];
     const seenIds = new Set();
     for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
@@ -42,6 +43,9 @@ export function combineSearchScores(options) {
             continue;
         if (options.typeFilter && found.entry.type !== options.typeFilter)
             continue;
+        // #627 — drop vector-only neighbors whose type is excluded on the default path.
+        if (excludeTypeSet?.has(found.entry.type))
+            continue;
         scored.push({
             id,
             entry: found.entry,

package/dist/indexer/search/search-source.js

@@ -5,13 +5,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
-import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
+import { resolveSourceProviderFactory, resolveSourceProviders } from "../../sources/provider-factory.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
 import "../../sources/providers/index.js";
 import { warn } from "../../core/warn.js";
-import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../../sources/providers/git.js";
-import { ensureWebsiteMirror } from "../../sources/website-ingest.js";
 // Legacy "context-hub" / "github" type aliases are normalized to "git" at
 // config-load time (see src/config.ts), so this set only contains the canonical
 // type.
@@ -261,31 +259,19 @@ function isValidDirectory(dir) {
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
-    const entries = getSources(cfg);
-    for (const entry of entries) {
-        if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
+    // Polymorphic refresh: walk every enabled source through its registered
+    // provider and call `sync()`. Every cache-backed kind (git, website, npm)
+    // refreshes the same way — a bad source warns and is skipped without
+    // aborting the others. The git content/-subdir layout convention stays in
+    // resolveEntryContentDir.
+    for (const provider of resolveSourceProviders(cfg)) {
+        if (!provider.sync)
             continue;
         try {
-            const repo = parseGitRepoUrl(entry.url);
-            const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, {
-                requireRepoDir: true,
-                writable: entry.writable === true,
-                force,
-            });
-        }
-        catch (err) {
-            warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    for (const entry of entries) {
-        if (entry.type !== "website" || !entry.url || entry.enabled === false)
-            continue;
-        try {
-            await ensureWebsiteMirror(entry, { requireStashDir: true, force });
+            await provider.sync({ force });
         }
         catch (err) {
-            warn(`Warning: failed to refresh website stash for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            warn(`Warning: failed to refresh ${provider.kind} source "${provider.name}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }

package/dist/indexer/search/semantic-status.js

@@ -4,8 +4,12 @@
 import fs from "node:fs";
 import { writeFileAtomic } from "../../core/common.js";
 import { getCacheDir, getSemanticStatusPath } from "../../core/paths.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../../llm/embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL } from "../../llm/embedders/local.js";
 export function deriveSemanticProviderFingerprint(embedding) {
+    if (isDeterministicEmbedEnabled()) {
+        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
+    }
     if (embedding?.endpoint) {
         return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;
     }

package/dist/indexer/walk/matchers.js

@@ -78,6 +78,15 @@ const DIR_TYPE_MAP = [
         type: "session",
         test: (ext) => ext === ".md",
     },
+    {
+        // Durable stash-level facts live under `facts/<category>/<name>.md`.
+        // classifyByDirectory walks every ancestor dir, so nested category
+        // subdirs still match. Without this entry a fact file would fall through
+        // to classifyBySmartMd and be mistyped as `knowledge`.
+        dir: "facts",
+        type: "fact",
+        test: (ext) => ext === ".md",
+    },
 ];
 const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
 // Files that should never be treated as the typed asset for the surrounding

package/dist/integrations/agent/config.js

@@ -1,9 +1,7 @@
 // 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 { VALID_HARNESS_IDS } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
 import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
 /**
  * Default hard timeout for an agent CLI (60s — matches the value used in
@@ -41,7 +39,12 @@ export function resolveAgentProfile(name, overrides) {
         stdio: base.stdio,
         env: base.env,
         envPassthrough: base.envPassthrough,
-        timeoutMs: base.timeoutMs,
+        // Honor a user-configured `profiles.agent.<name>.timeoutMs` override; fall
+        // back to the built-in profile's value. (Previously always used base, so
+        // the documented config override was silently ignored — callers had to pass
+        // a CLI flag like `--timeout-ms`.) runAgent (spawn.ts) reads profile.timeoutMs
+        // when no per-call timeout is supplied, so this makes the config knob work.
+        timeoutMs: overrides.timeoutMs ?? base.timeoutMs,
         parseOutput: base.parseOutput,
         ...(sdkMode ? { sdkMode: true } : {}),
         model: overrides.model ?? base.model,
@@ -134,53 +137,3 @@ export function listResolvedAgentProfiles(config) {
     }
     return resolved;
 }
-/**
- * Parse the v2 `profiles.agent` map (AgentProfileConfigV2 shape with required
- * `platform` field). Returns a map of profile name → AgentProfileConfigV2.
- */
-export function parseAgentProfilesMapV2(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return undefined;
-    const out = {};
-    // Derives from the canonical harness-id source of truth (#565).
-    const VALID_PLATFORMS = VALID_HARNESS_IDS;
-    for (const [name, raw] of Object.entries(value)) {
-        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-            warn(`[akm] Ignoring profiles.agent["${name}"]: expected an object.`);
-            continue;
-        }
-        const obj = raw;
-        if (!VALID_PLATFORMS.includes(obj.platform)) {
-            warn(`[akm] Ignoring profiles.agent["${name}"]: missing or invalid "platform" (must be one of: ${VALID_PLATFORMS.join(", ")}).`);
-            continue;
-        }
-        const profile = {
-            platform: obj.platform,
-        };
-        if (typeof obj.bin === "string" && obj.bin.trim())
-            profile.bin = obj.bin.trim();
-        if (Array.isArray(obj.args) && obj.args.every((a) => typeof a === "string")) {
-            profile.args = obj.args;
-        }
-        if (typeof obj.workspace === "string" && obj.workspace.trim())
-            profile.workspace = obj.workspace.trim();
-        if (typeof obj.model === "string" && obj.model.trim())
-            profile.model = obj.model.trim();
-        out[name] = profile;
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-/**
- * Stub kept for source-compat with callers that previously used the v1 agent
- * config parser. After 0.8.0 there is no separate `agent` block to parse — the
- * loaded `AkmConfig` already carries the agent data on `profiles.agent` and
- * `defaults.agent`. This function is a no-op alias for those callers.
- *
- * @deprecated v0.8.0 — the unified `AkmConfig` IS the agent config. Use the
- * profile/defaults accessors above instead.
- */
-export function parseAgentConfig(_value) {
-    // No-op: there is no separate agent block in 0.8.0. Callers should pass
-    // their loaded `AkmConfig` directly to `requireAgentProfile` etc.
-    return undefined;
-}

package/dist/integrations/agent/index.js

@@ -1,26 +1,10 @@
 // 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/.
-/**
- * Internal entry point for the `agent` integration. CLI-only project — no
- * public exports map. Other akm modules import from this barrel for the
- * sake of grouping imports.
- *
- * Surface:
- *   • Types: AgentProfile, AgentConfig, AgentRunResult, AgentFailureReason.
- *   • Profiles: getBuiltinAgentProfile, listBuiltinAgentProfiles, BUILTIN_AGENT_PROFILE_NAMES.
- *   • Config: parseAgentConfig, resolveProfileFromConfig, requireAgentProfile, listResolvedAgentProfiles, listAgentProfileNames.
- *   • Spawn: runAgent. Builders: getCommandBuilder, AgentCommandBuilder, AgentDispatchRequest — platform-specific argv construction.
- *   • Detection: detectAgentCliProfiles, pickDefaultAgentProfile, defaultWhich.
- */
-// The OpenCode SDK runner moved to its harness directory in #564
-// (`harnesses/opencode-sdk/`). Re-exported here so existing `agent/index`
-// import sites keep working.
-export { runAgentSdk } from "../harnesses/opencode-sdk/index.js";
 export { getCommandBuilder } from "./builders.js";
-export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config.js";
+export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config.js";
 export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
 export { listBuiltinModelAliases, resolveModel } from "./model-aliases.js";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
-export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, stripJsonFences, } from "./prompts.js";
+export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "./prompts.js";
 export { runAgent } from "./spawn.js";

package/dist/integrations/agent/prompts.js

@@ -26,6 +26,7 @@
  * during validation. We carry it through if the agent supplies it.
  */
 import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { authoringRulesForType, DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, requiresDescription, } from "../../core/authoring-rules.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
@@ -43,6 +44,7 @@ const TYPE_HINTS = {
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
     env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>` (the safe path — values never reach stdout/your context); do NOT run `akm env export` and read its output, as that prints values. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
+    fact: "fact assets are durable stash-level facts (personal/team/project details, coding conventions, stash-meta). Frontmatter SHOULD include `description` and a `category` (personal|team|project|convention|meta); set `pinned: true` only for the small always-injected core. Keep each fact short, high-signal, and self-contained — it is durable context, not an episodic note.",
 };
 function hintForType(type) {
     return TYPE_HINTS[type] ?? `assets of type "${type}" — produce sensible markdown with optional frontmatter.`;
@@ -109,6 +111,30 @@ export function extractDraftConfidence(stdout) {
         return undefined;
     return value;
 }
+/**
+ * Whether the source asset content has a non-empty `description:` key in its
+ * YAML frontmatter. Used by {@link buildReflectPrompt} (#636) to decide whether
+ * to inject the synthesize-a-description instruction. Uses an inline regex to
+ * avoid pulling the full YAML parser into the prompt module (mirrors the
+ * existing inline frontmatter handling here).
+ */
+function sourceHasNonEmptyDescription(assetContent) {
+    if (!assetContent)
+        return false;
+    const fmMatch = assetContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!fmMatch)
+        return false;
+    const fmBlock = fmMatch[1] ?? "";
+    // Match a top-level `description:` line and capture its inline value.
+    const descMatch = fmBlock.match(/^description\s*:\s*(.*)$/m);
+    if (!descMatch)
+        return false;
+    const value = (descMatch[1] ?? "")
+        .trim()
+        .replace(/^['"]|['"]$/g, "")
+        .trim();
+    return value.length > 0;
+}
 /**
  * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
  * existing asset (plus any negative feedback / lint findings) and propose
@@ -155,6 +181,34 @@ export function buildReflectPrompt(input) {
         // ref is set but no feedback — explicitly constrain scope to schema compliance
         sections.push("No usage feedback recorded. Limit your proposal to schema and structural improvements only: missing required frontmatter fields, unclear `when_to_use`, ambiguous description, or broken formatting. Do not speculate about runtime weaknesses you have not observed.");
     }
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const resolvedType = input.type ?? (input.ref?.includes(":") ? input.ref.split(":")[0] : "");
+        const authoringRules = resolvedType ? authoringRulesForType(resolvedType) : "";
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+        // #636 — synthesize-a-description instruction. Many source assets (notably
+        // scraped docs: `source`/`title`/`scraped`) carry frontmatter but NO
+        // `description`. Reflect echoes the source frontmatter, so the proposal
+        // inherits the missing description and the promote-time validator
+        // (isValidDescription, 20–400 chars) rejects it. The fix is at GENERATION
+        // time: when the source lacks a non-empty `description` and the type
+        // requires one, tell the model — unmissably — that it MUST author a valid
+        // `description`. (The validator/promote path is NOT changed: it must never
+        // fabricate content to pass itself.)
+        if (resolvedType && requiresDescription(resolvedType) && !sourceHasNonEmptyDescription(input.assetContent)) {
+            sections.push([
+                "REQUIRED — synthesize a `description` (the source asset has none):",
+                `- The source frontmatter does NOT include a non-empty \`description\`, but a ${resolvedType} asset REQUIRES one or the proposal will be rejected at promote time.`,
+                `- You MUST author a valid \`description\` in the proposal frontmatter: ${DESCRIPTION_MIN_CHARS}–${DESCRIPTION_MAX_CHARS} characters of plain-prose sentence summarizing what this asset is about.`,
+                '- Synthesize it from the asset\'s `title:` frontmatter, its first `# Heading`, or the opening body sentence. Do NOT copy a bare heading fragment (e.g. "Overview", "Named Page", "Key Insight") and do NOT emit a truncated phrase that ends on `:`/`;`/`,` or a hanging connector word.',
+            ].join("\n"));
+        }
+    }
     if (input.assetContent?.trim()) {
         // Cap at 12 000 chars to stay well under OS ARG_MAX when the prompt is
         // passed as a CLI argument to opencode/claude. Large assets (wiki snapshots,
@@ -288,6 +342,16 @@ export function buildProposePrompt(input) {
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const authoringRules = authoringRulesForType(input.type);
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     sections.push("Produce a single proposal that, if accepted, would land as the asset described above.");
     sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
@@ -304,6 +368,16 @@ export function buildSchemaRepairPrompt(input) {
         `while preserving all existing content.`);
     sections.push(`Target ref: ${input.ref}`);
     sections.push(`Schema requirements for ${input.type} assets: ${hintForType(input.type)}`);
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const authoringRules = authoringRulesForType(input.type);
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     const CONTENT_CAP = 3000;
     const body = input.assetContent.trimEnd();
     const truncated = body.length > CONTENT_CAP;
@@ -370,11 +444,3 @@ export function parseAgentProposalPayload(stdout) {
     }
     return out;
 }
-/**
- * Strip `\`\`\`json … \`\`\`` fences and `<think>…</think>` reasoning blocks
- * from agent output. Thin wrapper around `core/parse` helpers, kept exported
- * for backward compatibility (re-exported from `integrations/agent/index.ts`).
- */
-export function stripJsonFences(text) {
-    return stripCodeFences(stripThinkBlocks(text));
-}

package/dist/integrations/agent/runner-dispatch.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * X3 — the ONE dispatch seam for the {@link RunnerSpec} tagged union.
+ *
+ * The improve slice dispatches a `RunnerSpec` (`llm | agent | sdk`) in several
+ * places (`reflect.ts`, `proposal/drain.ts`, …). Before this module each site
+ * re-rolled the identical 3-arm switch and re-declared its own per-kind test
+ * seams (`chat`, `runAgentFn`, `runSdkFn`). `executeRunner` collapses that into
+ * one switch + one {@link RunnerSeams} object.
+ *
+ * Scoping (behavior-preserving):
+ *   - The `agent` and `sdk` arms are byte-identical across call sites: invoke
+ *     the profile runner (`runAgent` / `runOpencodeSdk`) with the per-call
+ *     `RunAgentOptions` the caller passes. Those default runners live here so
+ *     callers stop importing `runAgent` / `runOpencodeSdk` for dispatch. The
+ *     `opts` (incl. any `timeoutMs`) is constructed by the caller and passed
+ *     through unchanged, so each site keeps its exact option set.
+ *   - The `llm` arm is irreducibly caller-specific (reflect wraps
+ *     `runReflectViaLlm`, which returns reflect's iteration shape; drain wraps a
+ *     plain `chatCompletion`). It is therefore a REQUIRED seam — there is no
+ *     default `llm` handler — so neither caller's bespoke behavior is changed.
+ *   - The `assertNever` exhaustiveness arm is kept so a 4th `RunnerSpec` kind is
+ *     a compile error here instead of a silent runtime fall-through.
+ *
+ * The return type is {@link AgentRunResult} so a later `callStructured` layer
+ * (X2) can wrap `executeRunner` without changing this contract.
+ */
+import { assertNever } from "../../core/assert.js";
+import { runOpencodeSdk } from "../harnesses/opencode-sdk/index.js";
+import { runAgent } from "./spawn.js";
+/**
+ * Dispatch a {@link RunnerSpec} to its runner and return the raw
+ * {@link AgentRunResult}. `opts` is the {@link RunAgentOptions} for the profile
+ * (`agent` / `sdk`) arms; it is passed through unchanged so each caller keeps
+ * its exact option set (incl. any `timeoutMs` the caller chose to apply).
+ */
+export async function executeRunner(spec, prompt, opts, seams = {}) {
+    switch (spec.kind) {
+        case "llm": {
+            if (!seams.llm) {
+                throw new Error("executeRunner: an `llm` runner requires a `seams.llm` handler (no default LLM dispatch).");
+            }
+            return seams.llm(spec, prompt);
+        }
+        case "agent": {
+            const run = seams.runAgent ?? runAgent;
+            return run(spec.profile, prompt, opts);
+        }
+        case "sdk": {
+            const run = seams.runSdk ?? runOpencodeSdk;
+            return run(spec.profile, prompt, opts);
+        }
+        default:
+            // Exhaustiveness arm: a 4th RunnerSpec kind becomes a compile error here.
+            return assertNever(spec);
+    }
+}

package/dist/integrations/harnesses/claude/session-log.js

@@ -107,6 +107,16 @@ export class ClaudeCodeProvider {
     isAvailable() {
         return fs.existsSync(claudeProjectsDir());
     }
+    /**
+     * Directory holding Claude Code's per-project session JSONL files
+     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
+     * when the directory does not exist on this machine. See {@link
+     * SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const dir = claudeProjectsDir();
+        return fs.existsSync(dir) ? [dir] : [];
+    }
     *readEvents(input) {
         try {
             for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {
@@ -298,7 +308,7 @@ export class ClaudeCodeProvider {
                 const full = path.join(dir, entry.name);
                 if (entry.isDirectory())
                     yield* this.#walkJsonl(full);
-                else if (entry.name.endsWith(".jsonl"))
+                else if (entry.name.endsWith(".jsonl") && entry.name !== "journal.jsonl")
                     yield full;
             }
         }

package/dist/integrations/harnesses/index.js

@@ -60,9 +60,8 @@ const HARNESS_BY_ANY_ID = (() => {
 })();
 /**
  * Canonical, ordered list of valid harness / platform ids. The Zod
- * `AgentPlatformSchema` enum, the `AgentProfileConfigV2` platform union,
- * `parseAgentProfilesMapV2`'s membership check, and setup's `DetectedHarness`
- * union all derive from this so they cannot drift.
+ * `AgentPlatformSchema` enum, the `AgentProfileConfig` platform union, and
+ * setup's `DetectedHarness` union all derive from this so they cannot drift.
  */
 export const VALID_HARNESS_IDS = Object.freeze(HARNESS_REGISTRY.map((h) => h.id));
 /** Harnesses that expose readable native session logs. */

package/dist/integrations/harnesses/opencode/session-log.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { openDatabase } from "../../../storage/database.js";
 import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
 function getOpenCodeBaseDir() {
     if (process.platform === "darwin") {
@@ -12,20 +13,49 @@ function getOpenCodeBaseDir() {
     return path.join(os.homedir(), ".local", "share", "opencode");
 }
 /**
- * Opencode storage layout (observed 2026-05):
- *   <base>/storage/session/<projectId>/<sessionId>.json    — metadata
- *   <base>/storage/message/<sessionId>/<messageId>.json    — one per message
+ * Opencode storage layouts:
+ *
+ *   SQLite (current, observed 2026-06): `<base>/opencode.db` — a Drizzle-managed
+ *   database with `session` / `message` / `part` tables. Message text lives in
+ *   `part` rows (`data` JSON, `type: "text"`); `message.data` holds role/timing.
+ *   This is the layout current opencode builds write; it is preferred whenever
+ *   `opencode.db` exists.
+ *
+ *   JSON files (legacy, observed 2026-05): `<base>/storage/session/<projectId>/
+ *   <sessionId>.json` (metadata) + `<base>/storage/message/<sessionId>/
+ *   <messageId>.json` (one per message). Read only when `opencode.db` is absent.
  *
  * Older builds wrote logs directly into `<base>/log/` and `<base>/*.log`;
  * those are still scanned by {@link OpenCodeProvider.readEvents} for
  * backward compatibility with the existing failure-pattern aggregator.
  */
+/** Filename of opencode's SQLite session store, relative to its base dir. */
+const OPENCODE_DB_FILENAME = "opencode.db";
 export class OpenCodeProvider {
     name = "opencode";
     #baseDir = getOpenCodeBaseDir();
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /** Absolute path to opencode's SQLite store under `base`. */
+    #dbPath(base) {
+        return path.join(base, OPENCODE_DB_FILENAME);
+    }
+    /**
+     * Directories/files opencode writes session data under. Returns the base dir
+     * when the SQLite store (`opencode.db`) exists, the legacy JSON session root
+     * (`<base>/storage/session`) when present, or both during a migration overlap.
+     * Empty when neither exists. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const roots = [];
+        if (fs.existsSync(this.#dbPath(this.#baseDir)))
+            roots.push(this.#baseDir);
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        if (fs.existsSync(sessionRoot))
+            roots.push(sessionRoot);
+        return roots;
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without
@@ -82,6 +112,9 @@ export class OpenCodeProvider {
     listSessions(input = {}) {
         const base = input.location ?? this.#baseDir;
         const sinceMs = input.sinceMs ?? 0;
+        const dbPath = this.#dbPath(base);
+        if (fs.existsSync(dbPath))
+            return this.#listSessionsFromDb(dbPath, sinceMs);
         const sessionRoot = path.join(base, "storage", "session");
         if (!fs.existsSync(sessionRoot))
             return [];
@@ -142,6 +175,8 @@ export class OpenCodeProvider {
         return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
     }
     readSession(ref) {
+        if (path.basename(ref.filePath) === OPENCODE_DB_FILENAME)
+            return this.#readSessionFromDb(ref);
         let meta = {};
         try {
             meta = JSON.parse(fs.readFileSync(ref.filePath, "utf8"));
@@ -199,6 +234,141 @@ export class OpenCodeProvider {
             inlineRefs,
         };
     }
+    /**
+     * List sessions from the SQLite store. `filePath` on each summary is the
+     * `opencode.db` path so {@link readSession} can route back to the DB reader.
+     * Returns `[]` (never throws) when the DB is unreadable or lacks the expected
+     * schema — callers treat a missing harness as "no sessions".
+     */
+    #listSessionsFromDb(dbPath, sinceMs) {
+        let db;
+        try {
+            db = openDatabase(dbPath, { readonly: true, create: false });
+        }
+        catch {
+            return [];
+        }
+        try {
+            const rows = db
+                .prepare("SELECT id, title, directory, time_created, time_updated FROM session WHERE time_updated >= ? ORDER BY time_updated DESC")
+                .all(sinceMs);
+            return rows.map((r) => {
+                const startedAt = typeof r.time_created === "number" ? r.time_created : undefined;
+                const endedAt = typeof r.time_updated === "number" ? r.time_updated : undefined;
+                const title = typeof r.title === "string" && r.title.length > 0 ? r.title : undefined;
+                const projectHint = typeof r.directory === "string" && r.directory.length > 0 ? r.directory : undefined;
+                return {
+                    harness: this.name,
+                    sessionId: r.id,
+                    filePath: dbPath,
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {}),
+                    ...(projectHint ? { projectHint } : {}),
+                    ...(title ? { title } : {}),
+                };
+            });
+        }
+        catch {
+            // Missing `session` table / unexpected schema — treat as no sessions.
+            return [];
+        }
+        finally {
+            db.close();
+        }
+    }
+    /**
+     * Read one session from the SQLite store. Message text lives in `part` rows
+     * (`type: "text"`); `message.data` carries role + timing. One event per
+     * message, text-parts concatenated in time order. Returns empty events
+     * (never throws) when the DB is unreadable.
+     */
+    #readSessionFromDb(ref) {
+        const emptyRef = { harness: this.name, sessionId: ref.sessionId, filePath: ref.filePath };
+        let db;
+        try {
+            db = openDatabase(ref.filePath, { readonly: true, create: false });
+        }
+        catch {
+            return { ref: emptyRef, events: [], inlineRefs: [] };
+        }
+        try {
+            const meta = db
+                .prepare("SELECT title, directory, time_created, time_updated FROM session WHERE id = ?")
+                .get(ref.sessionId);
+            const startedAt = typeof meta?.time_created === "number" ? meta.time_created : undefined;
+            const endedAt = typeof meta?.time_updated === "number" ? meta.time_updated : undefined;
+            const title = typeof meta?.title === "string" && meta.title.length > 0 ? meta.title : undefined;
+            const projectHint = typeof meta?.directory === "string" && meta.directory.length > 0 ? meta.directory : undefined;
+            const messages = db
+                .prepare("SELECT id, data, time_created FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC")
+                .all(ref.sessionId);
+            const parts = db
+                .prepare("SELECT message_id, data FROM part WHERE session_id = ? ORDER BY time_created ASC, id ASC")
+                .all(ref.sessionId);
+            // Group text-part bodies by their parent message.
+            const textByMessage = new Map();
+            for (const part of parts) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(part.data);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed?.type !== "text")
+                    continue;
+                const text = parsed.text;
+                if (typeof text !== "string" || text.length < 1)
+                    continue;
+                const bucket = textByMessage.get(part.message_id) ?? [];
+                bucket.push(text);
+                textByMessage.set(part.message_id, bucket);
+            }
+            const events = [];
+            const inlineRefs = [];
+            for (const message of messages) {
+                let mdata = {};
+                try {
+                    mdata = JSON.parse(message.data);
+                }
+                catch {
+                    // role/timing unavailable — fall through with defaults
+                }
+                const role = typeof mdata.role === "string" ? mdata.role : "unknown";
+                const mtime = mdata.time?.created;
+                const ts = typeof mtime === "number"
+                    ? mtime
+                    : typeof message.time_created === "number"
+                        ? message.time_created
+                        : undefined;
+                const text = (textByMessage.get(message.id) ?? []).join("\n").trim();
+                if (text.length < 1)
+                    continue;
+                events.push({ harness: this.name, text, ts, sessionId: ref.sessionId, role, filePath: ref.filePath });
+                inlineRefs.push(...extractInlineRefMentions(text, ts));
+            }
+            events.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+            return {
+                ref: {
+                    harness: this.name,
+                    sessionId: ref.sessionId,
+                    filePath: ref.filePath,
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {}),
+                    ...(projectHint ? { projectHint } : {}),
+                    ...(title ? { title } : {}),
+                },
+                events,
+                inlineRefs,
+            };
+        }
+        catch {
+            return { ref: emptyRef, events: [], inlineRefs: [] };
+        }
+        finally {
+            db.close();
+        }
+    }
     /**
      * Derive opencode base dir from a session metadata file path so a caller
      * passing a custom `--location` can still find the message dir.