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

package/dist/indexer/search/ranking-contributors.js

@@ -9,6 +9,9 @@ const TYPE_BOOST = {
     agent: 0.3,
     script: 0.2,
     knowledge: 0.22,
+    // Facts are authoritative, durable declarations about the stash — rank them
+    // alongside knowledge so they surface reliably when relevant.
+    fact: 0.22,
     memory: -0.02,
 };
 const MAX_BOOST_SUM = 3.0;
@@ -206,6 +209,24 @@ const lessonStrengthContributor = {
         return Math.min(0.3, 0.06 * strength);
     },
 };
+/**
+ * Pinned-fact boost.
+ *
+ * Facts marked `pinned: true` form the small always-injected "core context"
+ * (see docs/design/fact-asset-type.md). The fact metadata contributor records
+ * a `pinned` search hint; here we give those facts a modest additive boost so
+ * the core outranks ordinary facts on otherwise-equal queries. Capped small so
+ * it cannot overpower an exact-name match.
+ */
+const pinnedFactRankingContributor = {
+    name: "pinned-fact-ranking",
+    appliesTo(item) {
+        return item.entry.type === "fact" && (item.entry.searchHints?.includes("pinned") ?? false);
+    },
+    adjust() {
+        return 0.15;
+    },
+};
 /**
  * Blend ratio for scoped vs. global utility signals.
  *
@@ -310,6 +331,7 @@ export const defaultRankingContributors = [
     graphRankingContributor,
     captureModeRankingContributor,
     lessonStrengthContributor,
+    pinnedFactRankingContributor,
     projectContextRankingContributor,
 ];
 export const defaultUtilityRankingContributors = [utilityRankingContributor];

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

@@ -10,8 +10,6 @@ import { resolveSourceProviderFactory } from "../../sources/provider-factory.js"
 // 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,32 @@ 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 entry of getSources(cfg)) {
+        if (entry.enabled === false)
+            continue;
+        const factory = resolveSourceProviderFactory(entry.type);
+        if (!factory)
             continue;
+        let provider;
         try {
-            const repo = parseGitRepoUrl(entry.url);
-            const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, {
-                requireRepoDir: true,
-                writable: entry.writable === true,
-                force,
-            });
+            provider = factory(entry);
         }
         catch (err) {
-            warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            warn(`Warning: failed to construct ${entry.type} source provider for "${entry.name ?? entry.url ?? entry.path}": ${err instanceof Error ? err.message : String(err)}`);
+            continue;
         }
-    }
-    for (const entry of entries) {
-        if (entry.type !== "website" || !entry.url || entry.enabled === false)
+        if (!provider.sync)
             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
@@ -41,8 +42,9 @@ const TYPE_HINTS = {
     memory: "memory assets are short factual notes the user wants persisted across sessions. Frontmatter usually includes `description`.",
     workflow: "workflow assets are markdown describing a multi-step process. Include `# <Title>` and ordered `## Step N` sections.",
     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.",
+    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>`; prefer `--clean` in agent contexts so the child starts from a minimal inherited environment. AKM itself does not print values, but the child command can print its environment, so do not run `env`, `printenv`, shell tracing, or similar diagnostics when secrets are in scope. 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. */