akm-cli 0.9.1 → 0.9.2-alpha.1

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

@@ -1,14 +1,27 @@
 // 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/.
+/**
+ * Database-backed (SQLite + FTS5/vector) source search implementation.
+ *
+ * Extracted from source-search.ts to break the circular import:
+ *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
+ *
+ * source-search.ts imports this module for the `searchLocal` export.
+ * sources/providers/filesystem.ts also imports `searchLocal` from here.
+ *
+ * Renamed from `local-search.ts` to signal that this is the DB-layer search
+ * implementation, not a "local vs. remote" distinction.
+ */
 import path from "node:path";
 import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { displayRef } from "../../core/asset/resolve-ref.js";
 import { classifyPathAccess } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
+import { systemErrorCode } from "../../core/system-error.js";
 import { defaultRendererRegistry } from "../../core/type-presentation.js";
-import { warn } from "../../core/warn.js";
+import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
@@ -188,7 +201,9 @@ export async function searchLocal(input) {
         const staleHint = buildStaleIndexHint(db);
         if (staleHint)
             warnings.push(staleHint);
-        const { hits, embedMs, rankMs, usedSemantic } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes, disableProjectContext, disableScopedUtility);
+        const { hits, embedMs, rankMs, mode, semanticWarning } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes, disableProjectContext, disableScopedUtility);
+        if (semanticWarning)
+            warnings.push(semanticWarning);
         return {
             hits,
             tip: hits.length === 0 ? emptyResultTip(query) : undefined,
@@ -197,7 +212,7 @@ export async function searchLocal(input) {
             rankMs,
             // Report the mode the search ACTUALLY used, carried explicitly from the
             // vector scorer — not inferred from elapsed embedding milliseconds.
-            mode: usedSemantic ? "semantic" : "keyword",
+            mode,
         };
     }
     finally {
@@ -246,7 +261,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
                 conceptIdPrefix: refPrefix.conceptIdPrefix,
                 ...(refPrefix.bundle !== undefined ? { bundle: refPrefix.bundle } : {}),
             })),
-            usedSemantic: false,
+            mode: "keyword",
         };
     }
     // Empty queries — including ones that sanitize down to no searchable FTS
@@ -260,23 +275,13 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
                 typeFilter: searchType === "any" ? undefined : searchType,
                 excludeTypes: defaultExcludes,
             })),
-            usedSemantic: false,
+            mode: "keyword",
         };
     }
     // Start the async embedding request without awaiting, then run FTS
     // synchronously while the HTTP/local embedding request is in-flight.
     const typeFilter = searchType === "any" ? undefined : searchType;
-    const tEmbed0 = Date.now();
-    const embeddingPromise = tryVecScores(db, query, limit * 3, config);
-    const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
-    const embeddingScores = await embeddingPromise;
-    const embedMs = Date.now() - tEmbed0;
-    // The vector scorer returns a (possibly empty) Map when the embedding + vector
-    // search actually executed, or null when semantic was not runnable (disabled,
-    // no embeddings, or the embed call threw). This is the AUTHORITATIVE "semantic
-    // mode was used" signal — carried out to telemetry instead of guessing from
-    // elapsed milliseconds (which timed the concurrent FTS work too).
-    const usedSemantic = embeddingScores !== null;
+    const { ftsResults, embeddingScores, embedMs, mode, semanticWarning } = await collectSearchSignals(db, query, limit * 3, typeFilter, defaultExcludes, config);
     const tRank0 = Date.now();
     // ── Score normalization ──────────────────────────────────────────────
     // Normalized BM25 + cosine similarity with weighted addition
@@ -437,7 +442,25 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             db,
         });
     }));
-    return { embedMs, rankMs, hits, usedSemantic };
+    return { embedMs, rankMs, hits, mode, semanticWarning };
+}
+async function collectSearchSignals(db, query, candidateLimit, typeFilter, excludeTypes, config) {
+    const startedAt = Date.now();
+    const embeddingPromise = tryVecScores(db, query, candidateLimit, config);
+    const ftsResults = searchFts(db, query, candidateLimit, typeFilter, excludeTypes);
+    const embeddingResult = await embeddingPromise;
+    const mode = embeddingResult.warning
+        ? "fts-fallback"
+        : embeddingResult.scores !== null
+            ? "semantic"
+            : "keyword";
+    return {
+        ftsResults,
+        embeddingScores: embeddingResult.scores,
+        embedMs: Date.now() - startedAt,
+        mode,
+        semanticWarning: embeddingResult.warning,
+    };
 }
 /**
  * The no-hits tip. A query in the retired `<type>:` / `<type>:<prefix>/` browse
@@ -623,10 +646,10 @@ function matchBeliefFilter(beliefState, filter) {
 async function tryVecScores(db, query, k, config) {
     const semanticStatus = getEffectiveSemanticStatus(config, readSemanticStatus());
     if (!isSemanticRuntimeReady(semanticStatus))
-        return null;
+        return { scores: null };
     const hasEmbeddings = getMeta(db, "hasEmbeddings");
     if (hasEmbeddings !== "1")
-        return null;
+        return { scores: null };
     try {
         const { embed } = await import("../../llm/embedder.js");
         const queryEmbedding = await embed(query, config.embedding);
@@ -638,12 +661,64 @@ async function tryVecScores(db, query, k, config) {
             const raw = 1 - (distance * distance) / 2;
             scores.set(id, Number.isFinite(raw) ? Math.max(0, raw) : 0);
         }
-        return scores;
+        return { scores };
     }
     catch (error) {
-        warn("Vector search failed, skipping:", error instanceof Error ? error.message : String(error));
-        return null;
+        return { scores: null, warning: buildVectorFallbackWarning(config, error) };
+    }
+}
+function buildVectorFallbackWarning(config, error) {
+    const endpoint = safeEmbeddingEndpoint(config);
+    const reason = classifyVectorFailure(error);
+    const target = endpoint
+        ? `embedding endpoint ${endpoint}`
+        : config.embedding?.endpoint
+            ? "configured embedding endpoint"
+            : "local embedding model";
+    const unavailable = reason === "connection failed" ? `cannot reach ${target}` : `${target} is unavailable`;
+    return `Vector search unavailable: ${unavailable} (${reason}) — falling back to keyword search.`;
+}
+/**
+ * Name the useful endpoint without ever carrying URL userinfo, query secrets,
+ * or fragments into a warning. Invalid authored values fail closed.
+ */
+function safeEmbeddingEndpoint(config) {
+    const endpoint = config.embedding?.endpoint;
+    if (!endpoint)
+        return undefined;
+    try {
+        const parsed = new URL(normalizeEmbeddingEndpoint(endpoint));
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Map untrusted runtime failures onto a small, non-secret diagnostic set. */
+function classifyVectorFailure(error) {
+    const code = systemErrorCode(error);
+    const message = error instanceof Error ? error.message : "";
+    if (code === "ECONNREFUSED" ||
+        code === "ECONNRESET" ||
+        code === "ENETUNREACH" ||
+        code === "EHOSTUNREACH" ||
+        code === "ENOTFOUND" ||
+        code === "EAI_AGAIN" ||
+        /typo in the url or port|connection (?:refused|failed|reset)|fetch failed/i.test(message)) {
+        return "connection failed";
     }
+    if (code === "ETIMEDOUT" || /timed? out|timeout/i.test(message))
+        return "request timed out";
+    const httpStatus = message.match(/Embedding (?:batch )?request failed \((\d{3})\)/i)?.[1];
+    if (httpStatus)
+        return `HTTP ${httpStatus}`;
+    if (/unexpected embedding response|missing data\[0\]\.embedding/i.test(message))
+        return "invalid embedding response";
+    return "request failed";
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
@@ -703,6 +778,7 @@ export async function buildDbHit(input) {
     await enrichSearchHit(hit, {
         type: input.entry.type,
         stashDir: entryStashDir,
+        bundleId: input.bundleId,
         rendererRegistry,
         db: input.db,
     });

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

@@ -70,7 +70,7 @@ export function buildSearchFields(entry) {
     // folds into the lowest-weight catch-all column — never name/description/
     // tags/hints — so orientation prose is retrievable without outranking
     // structured-field matches. The fold is unconditional on the entry field:
-    // `rebuildFts` rebuilds FTS rows from stored entry_json and must reproduce
+    // `rebuildFts` rebuilds FTS rows from stored document_json and must reproduce
     // the same fields without re-reading config.
     if (entry.bodyOpening)
         contentParts.push(entry.bodyOpening);

package/dist/indexer/search/search-hit-enrichers.js

@@ -53,7 +53,7 @@ export const derivedMemoryEnricher = {
         // column now stores this same conceptId grammar (Group-C item 2 flip — the
         // metadata producer + this consumer move together).
         const parentRef = `memories/${hit.name}`;
-        const derived = getDerivedForParent(ctx.db, parentRef, ctx.stashDir);
+        const derived = getDerivedForParent(ctx.db, parentRef, ctx.bundleId);
         if (!derived)
             return;
         // Swap description / searchHints / tags from the derived child.

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

@@ -3,12 +3,12 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { isSourceWriteActivated } from "../../core/activation-policy.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { bundleComponentConfig, bundlesToSourceEntries, getSources, loadConfig } from "../../core/config/config.js";
 import { resolveGitContentRoot, resolveWritable } from "../../core/write-source.js";
 import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
+import { ensureWebsiteMirror } from "../../sources/snapshot-fetchers/website-ingest.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
 import "../../sources/providers/index.js";
@@ -22,9 +22,8 @@ import { warn } from "../../core/warn.js";
  *   2. The configured `defaultBundle`, after component-root validation.
  *   3. Remaining configured bundles in installation-priority order.
  *
- * Replaces the previous four-pass loop that walked `stashes[]` separately
- * for each provider kind. Disabled entries (`enabled: false`) are filtered
- * after deduplication. Missing configured roots remain in the result so the
+ * Disabled entries (`enabled: false`) are filtered after deduplication.
+ * Missing configured roots remain in the result so the
  * indexer can classify their scan as incomplete instead of mistaking them for
  * removed sources.
  */
@@ -126,8 +125,8 @@ export function resolveEntryContentDir(entry) {
     // and writes agree on where content is); the localRoot is the already-walkable
     // content root (installed sources are extracted to their content dir), so no
     // content/-subdir step is applied. Fall back to the provider path logic when no
-    // lock entry exists (e.g. a git bundle migrated from a `sources[]` url, whose
-    // provider re-derives the mirror path).
+    // lock entry exists (for example while a configured source is being
+    // materialized for the first time).
     const localRoot = lockContentRootFor(entry.name, entry.type);
     if (localRoot != null)
         return localRoot;
@@ -165,14 +164,6 @@ export function resolveEntryContentDir(entry) {
 export function resolveAllStashDirs(overrideStashDir) {
     return resolveSourceEntries(overrideStashDir).map((s) => s.path);
 }
-/**
- * Return the resolved absolute paths of all writable stash sources.
- */
-export function getWritableStashDirs(overrideStashDir, existingConfig) {
-    return resolveSourceEntries(overrideStashDir, existingConfig)
-        .filter((s) => isSourceWriteActivated(s))
-        .map((s) => s.path);
-}
 /**
  * Find which source a file path belongs to.
  *
@@ -263,7 +254,7 @@ export async function ensureSourceCaches(config, options) {
     // 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. NEW shape reads `bundles`; old shape reads sources[].
+    // resolveEntryContentDir. Provider projection comes only from `bundles`.
     //
     // DISTINCTION (deliberately NOT lock-first): refresh derives the PROVIDER's
     // own cache path to git-pull/re-materialize INTO — that derived path is where
@@ -304,7 +295,7 @@ export async function ensureSourceCaches(config, options) {
             continue;
         }
         try {
-            await provider.sync({ force, secrets: options?.secrets });
+            await provider.sync({ force, secrets: options?.secrets, ensureWebsiteMirror });
         }
         catch (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

@@ -6,6 +6,11 @@ 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";
+let semanticStatusMutationForTests;
+/** TEST-ONLY. Inject a semantic-status filesystem publication fault. */
+export function _setSemanticStatusMutationForTests(mutation) {
+    semanticStatusMutationForTests = mutation;
+}
 export function deriveSemanticProviderFingerprint(embedding) {
     if (isDeterministicEmbedEnabled()) {
         return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
@@ -49,11 +54,13 @@ export function readSemanticStatus() {
     return undefined;
 }
 export function writeSemanticStatus(status) {
+    semanticStatusMutationForTests?.("write");
     const dir = getCacheDir();
     fs.mkdirSync(dir, { recursive: true });
     writeFileAtomic(getSemanticStatusPath(), `${JSON.stringify(status, null, 2)}\n`);
 }
 export function clearSemanticStatus() {
+    semanticStatusMutationForTests?.("clear");
     try {
         fs.unlinkSync(getSemanticStatusPath());
     }
@@ -110,7 +117,9 @@ export function classifySemanticFailure(message) {
     if (lower.includes("404") || lower.includes("model not found") || lower.includes("bad request")) {
         return "remote-model";
     }
-    if (lower.includes("transformers") || lower.includes("missing-package")) {
+    if (lower.includes("transformers") ||
+        lower.includes("missing-package") ||
+        lower.includes("local embedding dependency is unavailable")) {
         return "missing-package";
     }
     if (lower.includes("download")) {

package/dist/indexer/usage/show-usage.js

@@ -0,0 +1,105 @@
+// 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 { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { appendEvent, readEvents } from "../../core/events.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { findEntryIdByRef, getEntryById, getEntryIdByFilePath, getItemRefById, } from "../../storage/repositories/index-entries-repository.js";
+import { usageEventAttributionMetadata } from "../search/search-attribution.js";
+import { insertUsageEvent } from "./usage-events.js";
+/** Count prior show events in the current one-hour loop-detection window. */
+export function recentShowCount(ref) {
+    try {
+        return readEvents({
+            type: "show",
+            ref,
+            since: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+        }).events.length;
+    }
+    catch {
+        return 0;
+    }
+}
+function appendShowTrace(ref, type, name) {
+    appendEvent({ eventType: "show", ref, metadata: { type, name } });
+    try {
+        const { events: recentSearches } = readEvents({
+            type: "search",
+            since: new Date(Date.now() - 60_000).toISOString(),
+        });
+        const cutoffMs = Date.now() - 60_000;
+        const matchingSearch = [...recentSearches].reverse().find((event) => {
+            if (!event.ts || new Date(event.ts).getTime() < cutoffMs)
+                return false;
+            const refs = event.metadata?.resultRefs ?? [];
+            return refs.includes(ref);
+        });
+        if (!matchingSearch)
+            return;
+        const resultRefs = matchingSearch.metadata?.resultRefs ?? [];
+        appendEvent({
+            eventType: "select",
+            ref,
+            metadata: {
+                query: matchingSearch.metadata?.query,
+                searchTs: matchingSearch.ts,
+                rankPosition: resultRefs.indexOf(ref),
+            },
+        });
+    }
+    catch {
+        // Selection attribution is best-effort.
+    }
+}
+function insertShowUsage(entryId, entryRef, derivedFrom, eventSource) {
+    withStateDbTelemetry((stateDb) => {
+        insertUsageEvent(stateDb, {
+            event_type: "show",
+            entry_ref: entryRef,
+            entry_id: entryId,
+            metadata: usageEventAttributionMetadata(derivedFrom ? { memoryInference: { exposure: "direct" } } : undefined, entryRef),
+            source: eventSource,
+        });
+    }, TELEMETRY_BUSY_TIMEOUT_MS);
+}
+/** Record a successful show using the already-rendered response identity. */
+export function recordShowUsage(ref, type, name, eventSource = "user", filePath) {
+    const parsed = parseBundleRef(ref);
+    const eventRef = makeBundleRef(parsed.bundle, parsed.conceptId);
+    appendShowTrace(eventRef, type, name);
+    try {
+        withIndexDb((db) => {
+            const entryId = filePath ? getEntryIdByFilePath(db, filePath) : findEntryIdByRef(db, eventRef);
+            if (entryId === undefined)
+                return;
+            const entryRef = getItemRefById(db, entryId);
+            if (!entryRef)
+                return;
+            insertShowUsage(entryId, entryRef, getEntryById(db, entryId)?.entry.derivedFrom, eventSource);
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+    }
+}
+/** Record a nested execution-source read only after dispatch has crossed preflight. */
+export function recordIndexedShowUsage(ref, eventSource = "user") {
+    try {
+        withIndexDb((db) => {
+            const entryId = findEntryIdByRef(db, ref);
+            if (entryId === undefined)
+                return;
+            const indexed = getEntryById(db, entryId);
+            const entryRef = getItemRefById(db, entryId);
+            if (!indexed || !entryRef)
+                return;
+            appendShowTrace(entryRef, indexed.entry.type, indexed.entry.name);
+            insertShowUsage(entryId, entryRef, indexed.entry.derivedFrom, eventSource);
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+    }
+}

package/dist/indexer/usage/usage-events.js

@@ -75,12 +75,17 @@ export function countUsageEventsByType(db, eventType) {
 /**
  * Delete usage events older than the given number of days.
  */
-export function purgeOldUsageEvents(db, retentionDays) {
+export function purgeOldUsageEvents(db, retentionDays, options) {
     if (!Number.isFinite(retentionDays) || retentionDays <= 0)
         return;
     try {
+        const stateSchema = options?.stateSchema;
+        if (stateSchema !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(stateSchema)) {
+            throw new Error("Invalid attached state schema name.");
+        }
+        const usageEvents = stateSchema === undefined ? "usage_events" : `"${stateSchema}".usage_events`;
         const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-        db.prepare("DELETE FROM usage_events WHERE created_at < ?").run(cutoff);
+        db.prepare(`DELETE FROM ${usageEvents} WHERE created_at < ?`).run(cutoff);
     }
     catch {
         /* Table may not exist yet */

package/dist/indexer/walk/matchers.js

@@ -49,7 +49,7 @@ const DIR_TYPE_MAP = [
     {
         dir: "workflows",
         type: "workflow",
-        test: (ext) => ext === ".md",
+        test: (ext) => ext === ".md" || ext === ".yml",
     },
     {
         dir: "memories",
@@ -102,6 +102,13 @@ const DIR_TYPE_MAP = [
     },
 ];
 const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+const SMART_MD_FACTS = {
+    workflow: { type: "workflow", specificity: 19 },
+    toolsAgent: { type: "agent", specificity: 20 },
+    command: { type: "command", specificity: 18 },
+    modelAgent: { type: "agent", specificity: 8 },
+    knowledge: { type: "knowledge", specificity: 5 },
+};
 // Files that should never be treated as the typed asset for the surrounding
 // directory (e.g. `workflows/README.md` is documentation, not a workflow).
 // Lower-cased and matched case-insensitively against `ctx.fileName`. They are
@@ -175,7 +182,7 @@ function classifyBySmartMd(ctx) {
     // body shape would otherwise classify (e.g. step-list inside a project
     // README under workflows/). Fall straight through to `knowledge`.
     if (isTypedDirDocFile(ctx.fileName)) {
-        return { type: "knowledge", specificity: 5 };
+        return SMART_MD_FACTS.knowledge;
     }
     const body = ctx.content();
     const fm = ctx.frontmatter();
@@ -185,33 +192,34 @@ function classifyBySmartMd(ctx) {
     // this only catches a workflow living OUTSIDE `workflows/` that still
     // declares its type explicitly.
     if (fm && fm.type === "workflow") {
-        return { type: "workflow", specificity: 19 };
+        return SMART_MD_FACTS.workflow;
     }
     if (fm) {
         // `tools` is the one authoring key for an agent's tool grant. Recognition
         // covers only the key the renderer honors.
         if ("tools" in fm) {
-            return { type: "agent", specificity: 20 };
+            return SMART_MD_FACTS.toolsAgent;
         }
         if ("agent" in fm) {
-            return { type: "command", specificity: 18 };
+            return SMART_MD_FACTS.command;
         }
     }
     if (COMMAND_PLACEHOLDER_RE.test(body)) {
-        return { type: "command", specificity: 18 };
+        return SMART_MD_FACTS.command;
     }
     if (fm && "model" in fm) {
-        return { type: "agent", specificity: 8 };
+        return SMART_MD_FACTS.modelAgent;
     }
-    return { type: "knowledge", specificity: 5 };
+    return SMART_MD_FACTS.knowledge;
 }
 // ---------------------------------------------------------------------------
 // Adapter: MatchFact → MatchResult
 // ---------------------------------------------------------------------------
 function toMatchResult(ctx, classify) {
     const fact = classify(ctx);
-    if (!fact)
-        return null;
+    return fact ? matchResultForFact(fact) : null;
+}
+function matchResultForFact(fact) {
     // Renderer name resolved via TYPE_PRESENTATION (core leaf), so matchers.ts
     // carries no edge into the taxonomy SCC (chunk-3 cutover enabler).
     // TYPE_PRESENTATION.renderer is the single source of truth for renderer names.
@@ -225,6 +233,28 @@ function toMatchResult(ctx, classify) {
         ...(fact.meta ? { meta: fact.meta } : {}),
     };
 }
+/**
+ * Every smart-Markdown result possible from path fields alone. The actual
+ * classifier above returns only facts from this shared table, so owner
+ * discovery can conservatively model a byte request without reading bytes.
+ */
+export function smartMdPathCandidates(ctx) {
+    if (ctx.ext !== ".md" || ctx.ancestorDirs.includes("secrets"))
+        return [];
+    const facts = isTypedDirDocFile(ctx.fileName)
+        ? [SMART_MD_FACTS.knowledge]
+        : [
+            SMART_MD_FACTS.workflow,
+            SMART_MD_FACTS.toolsAgent,
+            SMART_MD_FACTS.command,
+            SMART_MD_FACTS.modelAgent,
+            SMART_MD_FACTS.knowledge,
+        ];
+    return facts.flatMap((fact) => {
+        const result = matchResultForFact(fact);
+        return result ? [result] : [];
+    });
+}
 // ---------------------------------------------------------------------------
 // Public matchers (API unchanged)
 // ---------------------------------------------------------------------------

package/dist/indexer/walk/path-resolver.js

@@ -8,6 +8,7 @@ import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin } from "../../core/common.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { lookup } from "../indexer.js";
+import { deriveInstallations } from "../installations.js";
 import { resolveSourceEntries } from "../search/search-source.js";
 function normalizeRef(ref) {
     // String inputs use the current `[bundle//]conceptId` grammar.
@@ -65,8 +66,10 @@ function resolveViaDisk(ref, options) {
     }
     const directoryIndexNames = options.directoryIndexNames ?? ["SKILL.md"];
     const preserveDirectNameFallback = options.preserveDirectNameFallback ?? true;
-    for (const source of sources) {
-        if (options.writableDirSet && !options.writableDirSet.has(path.resolve(source.path)))
+    const installations = deriveInstallations(sources);
+    for (const [index, source] of sources.entries()) {
+        const bundleId = installations[index]?.id;
+        if (options.writableBundleIds && (!bundleId || !options.writableBundleIds.has(bundleId)))
             continue;
         const candidates = buildDiskCandidates(source.path, ref, preserveDirectNameFallback);
         for (const candidate of candidates) {

package/dist/indexer/walk/walker.js

@@ -11,6 +11,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isRelevantAssetFile } from "../../core/asset/asset-placement.js";
+import { WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
 import { spawnSync } from "../../runtime.js";
 import { buildFileContext } from "./file-context.js";
 const ALWAYS_SKIP_DIRS = new Set([".git"]);
@@ -128,7 +129,8 @@ function walkStashGit(stashRoot, options) {
             // indexed. The manual walk below already skips symlinks for exactly this
             // reason; the two walkers have to agree regardless of whether the stash
             // happens to sit inside a git repo.
-            if (fs.lstatSync(absPath).isFile()) {
+            const stat = fs.lstatSync(absPath);
+            if (stat.isFile() || (stat.isSymbolicLink() && isOwnedWorkflowSymlink(stashRoot, absPath, options))) {
                 results.push(buildFileContext(stashRoot, absPath));
             }
         }
@@ -219,7 +221,11 @@ function walkStashManual(stashRoot, options) {
                 continue;
             const fullPath = path.join(current, entry.name);
             if (entry.isSymbolicLink()) {
-                // Skip symlinks entirely to prevent potential path traversal outside stashRoot
+                // Native workflow components arbitrate file symlinks explicitly in the
+                // drain before reading them. Directory symlinks remain unfollowed.
+                if (isOwnedWorkflowSymlink(stashRoot, fullPath, options)) {
+                    results.push(buildFileContext(stashRoot, fullPath));
+                }
                 continue;
             }
             if (entry.isDirectory()) {
@@ -235,3 +241,15 @@ function walkStashManual(stashRoot, options) {
     }
     return { files: results, complete };
 }
+function isOwnedWorkflowSymlink(stashRoot, candidatePath, options) {
+    const adapterId = options.workflowSymlinkAdapter;
+    if (!adapterId)
+        return false;
+    const relativePath = path.relative(path.resolve(stashRoot), path.resolve(candidatePath)).replaceAll("\\", "/");
+    if (!relativePath || relativePath.startsWith("../") || path.posix.isAbsolute(relativePath))
+        return false;
+    if (adapterId === "akm" && !relativePath.startsWith("workflows/"))
+        return false;
+    const extension = path.posix.extname(relativePath).toLowerCase();
+    return WORKFLOW_EXTENSIONS.includes(extension);
+}

package/dist/integrations/agent/builder-shared.js

@@ -14,12 +14,9 @@
  * their previous home in `builders.ts`.
  */
 import { UsageError } from "../../core/errors.js";
-import { resolveModel } from "./model-aliases.js";
-/** Resolve a raw dispatch model once, while preserving frozen/lowered models verbatim. */
-export function resolveDispatchModel(request, profile, platform) {
-    if (!request.model || request.modelIsExact)
-        return request.model;
-    return resolveModel(request.model, platform, profile.modelAliases, profile.globalModelAliases);
+/** Models reaching a harness have already crossed the single model-map boundary. */
+export function resolveDispatchModel(request, _profile, _platform) {
+    return request.model;
 }
 /**
  * Guard against values that start with `--`, which would be mis-interpreted as

package/dist/integrations/agent/conversation-fallback.js

@@ -0,0 +1,16 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+export const CONVERSATION_FALLBACK_BEGIN = "<AKM_CONVERSATION_JSON>";
+export const CONVERSATION_FALLBACK_END = "</AKM_CONVERSATION_JSON>";
+/**
+ * Preserve ordered message roles for a one-shot transport with no native
+ * conversation channel. The fixed `{role,content}` projection and UTF-8 byte
+ * length make the embedded JSON unambiguous even when content contains marker
+ * text. The terminal command remains outside the prefix block.
+ */
+export function composeConversationFallbackPrompt(conversation, command) {
+    const json = JSON.stringify(conversation.map((message) => ({ role: message.role, content: message.content })));
+    const byteLength = new TextEncoder().encode(json).byteLength;
+    return `${CONVERSATION_FALLBACK_BEGIN} ${byteLength}\n${json}\n${CONVERSATION_FALLBACK_END}\n\n${command}`;
+}