akm-cli 0.9.12 → 0.9.14-beta.1

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

@@ -27,6 +27,7 @@ import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../
 import { warnOnce } from "../warn.js";
 import { AkmConfigBaseSchema, EngineConfigSchema, listTopLevelConfigKeys } from "./config-schema.js";
 import { deepMergeConfig } from "./deep-merge.js";
+import { isApiKeyReference } from "./schema/primitives.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -214,9 +215,12 @@ export function configSet(config, dotted, raw) {
     const parsed = path[0] === "engines" && path.length === 2
         ? EngineConfigSchema.safeParse(value)
         : symbolicApiKey
-            ? /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(raw)
+            ? isApiKeyReference(raw)
                 ? { success: true, data: value }
-                : { success: false, error: { issues: [{ path: [], message: `apiKey must be $VAR or \${VAR}` }] } }
+                : {
+                    success: false,
+                    error: { issues: [{ path: [], message: "apiKey must be $VAR, ${VAR}, or secret://<name>" }] },
+                }
             : isUnknownKey
                 ? { success: true, data: value }
                 : schema.safeParse(candidate);
@@ -297,7 +301,7 @@ function rejectLiteralApiKeyInWholeObjectSet(path, raw, dotted) {
     }
     if (!isRecord(parsed) || typeof parsed.apiKey !== "string")
         return;
-    if (/^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(parsed.apiKey))
+    if (isApiKeyReference(parsed.apiKey))
         return;
     throw new UsageError(`apiKey cannot be persisted in config; export ${recipeForApiKey([...path, "apiKey"], `${dotted}.apiKey`)} instead. (key: ${dotted}.apiKey)`, "INVALID_FLAG_VALUE", "Storing API keys in config.json leaks them through backups, logs, and version control. " +
         "Use the corresponding environment variable. AKM reads it at request time.");

package/dist/core/config/config.js

@@ -12,6 +12,7 @@ import { bundlesToSourceEntries } from "./config-sources.js";
 import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig } from "./deep-merge.js";
 import { migrateLegacySourceShape } from "./legacy-source-shape-shim.js";
+import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
 import { warn, warnOnce } from "../warn.js";
@@ -299,7 +300,7 @@ export function sanitizeConfigForWrite(config) {
     const stripped = [];
     if (config.embedding?.apiKey !== undefined) {
         const apiKey = config.embedding.apiKey;
-        if (isEnvReference(apiKey)) {
+        if (isApiKeyReference(apiKey)) {
             // Preserve reference verbatim — not a secret.
             sanitized.embedding = { ...config.embedding };
         }
@@ -316,7 +317,7 @@ export function sanitizeConfigForWrite(config) {
     if (config.engines) {
         const engines = {};
         for (const [name, engine] of Object.entries(config.engines)) {
-            if (engine.kind !== "llm" || engine.apiKey === undefined || isEnvReference(engine.apiKey)) {
+            if (engine.kind !== "llm" || engine.apiKey === undefined || isApiKeyReference(engine.apiKey)) {
                 engines[name] = { ...engine };
                 continue;
             }
@@ -345,19 +346,15 @@ export function sanitizeConfigForWrite(config) {
     }
     return sanitized;
 }
-/** Matches the only 0.9 symbolic secret forms: `${VAR}` or `$VAR`. */
-function isEnvReference(value) {
-    return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value);
-}
 export function updateConfig(partial) {
     return mutateConfig((current) => deepMergeConfig(current, partial)).config;
 }
-// ── Helpers ─────────────────────────────────────────────────────────────────
 /**
- * Resolve a single secret value by expanding `${VAR}` / `$VAR` references
- * against `process.env`. Use this at apiKey /
- * authorization-header consumption sites (LLM client, embedder, agent SDK
- * runner) — NOT on the load path. Non-string inputs pass through unchanged.
+ * Resolve a single secret value: expand `${VAR}` / `$VAR` against
+ * `process.env`, or look up `secret://<name>` via `resolveFromStore`. Use this
+ * at apiKey / authorization-header consumption sites (LLM client, embedder,
+ * agent SDK runner) — NOT on the load path. Non-string inputs pass through
+ * unchanged.
  *
  * Returns the input unchanged when no substitution markers are present, so
  * literal API key strings (already-resolved secrets) are zero-cost.
@@ -365,12 +362,24 @@ export function updateConfig(partial) {
  * Other config string values (URLs, endpoints, model names, prompts) are
  * preserved verbatim on read — only fields explicitly routed through this
  * helper are expanded.
+ *
+ * A `secret://<name>` value that fails to resolve throws `ConfigError`
+ * (naming the ref, never the secret) rather than silently sending an unusable
+ * credential.
  */
-export function resolveSecret(value) {
+export function resolveSecret(value, resolveFromStore) {
     if (value === undefined)
         return undefined;
     if (typeof value !== "string")
         return value;
+    const storeRef = SECRET_STORE_REFERENCE_PATTERN.exec(value)?.[1];
+    if (storeRef !== undefined) {
+        const resolved = resolveFromStore?.(storeRef) ?? null;
+        if (resolved === null) {
+            throw new ConfigError(`Secret store reference "${value}" did not resolve to a stored value.`, "SECRET_REFERENCE_UNRESOLVED");
+        }
+        return resolved;
+    }
     if (!value.includes("$"))
         return value;
     return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {

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

@@ -28,15 +28,21 @@ export const httpUrl = z.string().refine((v) => v.startsWith("http://") || v.sta
 });
 const ENGINE_NAME_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 export const ENV_REFERENCE_PATTERN = /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+/** `secret://<name>` — an apiKey reference into the akm secret store, resolved via `resolveSecretFromStore`. */
+export const SECRET_STORE_REFERENCE_PATTERN = /^secret:\/\/(.+)$/;
 export const engineName = z
     .string()
     .max(63)
     .regex(ENGINE_NAME_PATTERN, "names must be lowercase kebab-case and must not begin with reserved akm-");
+/** The two symbolic apiKey forms akm accepts: an env-var reference or a secret-store reference. Never matches a literal key. */
+export function isApiKeyReference(value) {
+    return ENV_REFERENCE_PATTERN.test(value) || SECRET_STORE_REFERENCE_PATTERN.test(value);
+}
 export function symbolicOrWarnApiKey(label) {
     return z.string().superRefine((value) => {
-        if (ENV_REFERENCE_PATTERN.test(value))
+        if (isApiKeyReference(value))
             return;
-        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR} reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) — see docs/reference/data-and-telemetry.md.`);
+        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR}/secret:// reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) or \`secret://<name>\` (with \`akm secret set <name> ...\`) — see docs/reference/data-and-telemetry.md.`);
     });
 }
 export const chatCompletionsEndpoint = z.string().superRefine((value, ctx) => {

package/dist/core/errors.js

@@ -17,6 +17,7 @@ const CONFIG_HINTS = {
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
     EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
+    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the name after `secret://` matches, or run `akm secret set <name> <value>` to store it.",
 };
 // Code-review finding: COMPOSITION_INVALID covers several unrelated causes
 // (a rejected with:, a multi-job source, a composition cycle/depth/size
@@ -76,6 +77,7 @@ const USAGE_HINTS = {
     WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — a frozen plan this akm cannot execute is not re-executable in place.",
     // P3b (docs/plans/specs/p3b-child-executor.md §4.3).
     WORKFLOW_OUTPUT_INVALID: "Check each `outputs:` entry's `from:` against the step artifact it names, and its `schema:` against the value that step actually promotes.",
+    RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

package/dist/core/lexical-score.js

@@ -0,0 +1,25 @@
+// 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/.
+/** Dependency-safe fixed FTS5 calibration shared by storage and ranking. */
+const SCORE_FLOOR = 0.3;
+const PARENT_CEILING = 0.8;
+// Fragment BM25 is from a distinct FTS population. Its separately calibrated
+// ceiling is an explicit evidence policy, not a cross-table comparability claim:
+// when a body fragment independently proves the query, retain that actionable
+// selector beside the same parent's length-penalized whole-body row. Metadata
+// and cross-fragment conjunctions cannot enter this population.
+const FRAGMENT_CEILING = 0.8;
+const BM25_REFERENCE = 0.000001;
+const LOG_SHAPE = 3;
+export function stableFtsScore(bm25Score, population = "parent") {
+    const ceiling = population === "fragment" ? FRAGMENT_CEILING : PARENT_CEILING;
+    if (bm25Score === Number.NEGATIVE_INFINITY)
+        return ceiling;
+    if (!Number.isFinite(bm25Score) || bm25Score >= 0)
+        return SCORE_FLOOR;
+    const scaled = Math.log1p(-bm25Score / BM25_REFERENCE);
+    if (!Number.isFinite(scaled))
+        return ceiling;
+    return SCORE_FLOOR + (ceiling - SCORE_FLOOR) * (scaled / (scaled + LOG_SHAPE));
+}

package/dist/core/type-presentation.js

@@ -51,20 +51,41 @@ function buildWorkflowAction(ref) {
  * see the file header.
  */
 export const TYPE_PRESENTATION = {
-    skill: { label: "Skill", renderer: "skill-md", action: (ref) => `akm show ${ref} -> follow the instructions` },
+    skill: {
+        label: "Skill",
+        renderer: "skill-md",
+        action: (ref) => `akm show ${ref} -> follow the instructions`,
+        fragmentRef: false,
+    },
     command: {
         label: "Command",
         renderer: "command-md",
         action: (ref) => `akm show ${ref} -> fill placeholders and dispatch`,
+        fragmentRef: false,
+    },
+    agent: {
+        label: "Agent",
+        renderer: "agent-md",
+        action: (ref) => `akm show ${ref} -> dispatch with full prompt`,
+        fragmentRef: false,
     },
-    agent: { label: "Agent", renderer: "agent-md", action: (ref) => `akm show ${ref} -> dispatch with full prompt` },
     knowledge: {
         label: "Knowledge",
         renderer: "knowledge-md",
         action: (ref) => `akm show ${ref} -> read reference material`,
     },
-    workflow: { label: "Workflow", renderer: "workflow-md", action: (ref) => buildWorkflowAction(ref) },
-    script: { label: "Script", renderer: "script-source", action: (ref) => `akm show ${ref} -> execute the run command` },
+    workflow: {
+        label: "Workflow",
+        renderer: "workflow-md",
+        action: (ref) => buildWorkflowAction(ref),
+        fragmentRef: false,
+    },
+    script: {
+        label: "Script",
+        renderer: "script-source",
+        action: (ref) => `akm show ${ref} -> execute the run command`,
+        fragmentRef: false,
+    },
     memory: { label: "Memory", renderer: "memory-md", action: (ref) => `akm show ${ref} -> recall context` },
     env: {
         label: "Env",
@@ -85,6 +106,7 @@ export const TYPE_PRESENTATION = {
         label: "Task",
         renderer: "task-yaml",
         action: (ref) => `akm show ${ref} -> inspect; akm task run <id> -> run now; edit the file + akm task sync -> unschedule`,
+        fragmentRef: false,
     },
     session: {
         label: "Session",
@@ -105,6 +127,7 @@ export const TYPE_PRESENTATION = {
         label: "Instruction",
         renderer: "knowledge-md",
         action: (ref) => `akm show ${ref} -> read the project instructions`,
+        fragmentRef: false,
     },
 };
 /** Generic fallback for a type outside {@link KNOWN_TYPES} — never `undefined`, never a throw. */
@@ -120,6 +143,15 @@ export function presentationFor(type) {
         return TYPE_PRESENTATION[type];
     return DEFAULT_PRESENTATION;
 }
+/**
+ * A missing declaration means a read-like reference or foreign type can expose
+ * a safe selector. Built-in executable and instruction-bearing types opt out
+ * explicitly above: their search match can be a fragment, but the advertised
+ * action needs the parent canonical ref and its complete context.
+ */
+export function allowsFragmentRef(type) {
+    return presentationFor(type).fragmentRef !== false;
+}
 export const defaultRendererRegistry = {
     rendererNameFor(type) {
         return presentationFor(type).renderer;

package/dist/indexer/index-written-assets.js

@@ -31,6 +31,7 @@ import { closeDatabase, openExistingDatabase } from "../storage/repositories/ind
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
+import { getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { buildFileContext } from "./walk/file-context.js";
@@ -158,6 +159,9 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                         let entryWithSize = entry;
                         try {
                             entryWithSize = { ...entry, fileSize: fs.statSync(file).size };
+                            if (hasMarkdownFragmentContent(entry)) {
+                                setMarkdownFragmentContent(entryWithSize, getMarkdownFragmentContent(entry));
+                            }
                         }
                         catch {
                             // stat raced a delete — index without the size, like the full walk does.

package/dist/indexer/indexer.js

@@ -31,7 +31,7 @@ import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
-import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
+import { getMarkdownFragmentContent, hasMarkdownFragmentContent, isEnrichmentComplete, isWorkflowSkipWarning, setMarkdownFragmentContent, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
@@ -1504,7 +1504,10 @@ export function createEnrichmentDeadline(timeoutMs, totalEntries) {
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function attachFileSize(entry, entryPath) {
     try {
-        return { ...entry, fileSize: fs.statSync(entryPath).size };
+        const sized = { ...entry, fileSize: fs.statSync(entryPath).size };
+        if (hasMarkdownFragmentContent(entry))
+            setMarkdownFragmentContent(sized, getMarkdownFragmentContent(entry));
+        return sized;
     }
     catch {
         return entry;

package/dist/indexer/passes/metadata.js

@@ -1179,6 +1179,67 @@ export function projectMarkdownContent(body, truncationInfo) {
         truncationInfo.truncated = text.length > MARKDOWN_CONTENT_MAX_CHARS;
     return truncateUnicodeSafe(text, MARKDOWN_CONTENT_MAX_CHARS);
 }
+// Fragment text is intentionally not an IndexDocument field. IndexDocument is
+// an adapter/search payload boundary; this is an internal, derived index input
+// that is persisted separately by the entries repository for deterministic FTS
+// rebuilds. The WeakMap follows the already-read document through recognition
+// without making safe body bytes observable through public payloads.
+const markdownFragmentContentByEntry = new WeakMap();
+const markdownFragmentProjectionEntries = new WeakSet();
+export function setMarkdownFragmentContent(entry, content) {
+    markdownFragmentProjectionEntries.add(entry);
+    if (content)
+        markdownFragmentContentByEntry.set(entry, content);
+}
+export function getMarkdownFragmentContent(entry) {
+    return markdownFragmentContentByEntry.get(entry);
+}
+export function hasMarkdownFragmentContent(entry) {
+    return markdownFragmentProjectionEntries.has(entry);
+}
+/**
+ * Produce a safe, structure-preserving projection for fragment indexing.
+ * Excluded source lines are retained as blank lines so fragment locations map
+ * exactly to authored line numbers. This must be called from both indexing and
+ * `show`; it deliberately never performs a storage-layer file reread.
+ */
+export function projectMarkdownFragmentContent(raw) {
+    const lines = raw.split(/\r?\n/);
+    const parsed = parseFrontmatter(raw);
+    const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
+    const projected = lines.map(() => "");
+    let fence;
+    const htmlComment = { inComment: false };
+    for (let index = start; index < lines.length; index++) {
+        const rawLine = lines[index];
+        if (fence) {
+            if (isMarkdownFenceClosing(rawLine, fence))
+                fence = undefined;
+            continue;
+        }
+        if (!htmlComment.inComment) {
+            const opening = parseMarkdownFenceOpening(rawLine);
+            if (opening) {
+                fence = opening;
+                continue;
+            }
+        }
+        let safe = stripMarkdownHtmlComments(rawLine, htmlComment);
+        const opening = parseMarkdownFenceOpening(safe.trim());
+        if (opening) {
+            fence = opening;
+            continue;
+        }
+        // Reference link destinations and standalone HTML are not retrieval
+        // evidence and can contain credential-bearing URLs.
+        if (/^\s*\[[^\]]+\]:\s*\S+/.test(safe) || /^\s*<[^>]+>\s*$/.test(safe))
+            continue;
+        safe = stripMarkdownLinkDestinations(safe).replace(/<[^>]+>/g, " ");
+        projected[index] = safe.replace(/[ \t]+$/g, "");
+    }
+    const text = projected.join("\n");
+    return text.trim() ? text : undefined;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 /**
  * Priorities 1-2 of the metadata pipeline — package.json (P1), `.md`
@@ -1220,7 +1281,9 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
         applyProvenanceFrontmatter(entry, parsed.data);
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
-        if (entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content)) {
+        const safeForFragments = entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content);
+        setMarkdownFragmentContent(entry, safeForFragments ? projectMarkdownFragmentContent(content) : undefined);
+        if (safeForFragments) {
             const truncationInfo = { truncated: false };
             const contentProjection = projectMarkdownContent(parsed.content, truncationInfo);
             if (contentProjection) {

package/dist/indexer/scan/doc-to-entry.js

@@ -34,6 +34,7 @@
  * Pure, type-only imports (no cycle participation).
  */
 import path from "node:path";
+import { getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../passes/metadata.js";
 /**
  * Reconstruct the `IndexDocument` an `IndexDocument` was mapped from. First-class
  * IndexDocument members and the `documentJson`-carried extras are both restored;
@@ -60,6 +61,8 @@ export function indexDocumentToStashEntry(doc) {
         entry.content = doc.content;
     if (doc.contentTruncated !== undefined)
         entry.contentTruncated = doc.contentTruncated;
+    if (hasMarkdownFragmentContent(doc))
+        setMarkdownFragmentContent(entry, getMarkdownFragmentContent(doc));
     if (doc.ownsPresentation !== undefined)
         entry.ownsPresentation = doc.ownsPresentation;
     if (doc.updated !== undefined)

package/dist/indexer/scan/drain-dir.js

@@ -30,7 +30,7 @@ import path from "node:path";
 import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
 import { compareCodePoints } from "../../core/common.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
-import { resolveUniqueWorkflowSource, WorkflowSourceRejectionError, workflowNameForSourcePath, } from "../../workflows/source-files.js";
+import { resolveWorkflowSourceDomains, workflowNameForSourcePath } from "../../workflows/source-files.js";
 import { compileWorkflowSource } from "../../workflows/source-ir/compile.js";
 import { buildMetadataSkipWarning } from "../passes/metadata.js";
 import { buildFileContext } from "../walk/file-context.js";
@@ -53,32 +53,41 @@ export function drainDirDocuments(adapter, component, fileContexts) {
     const conceptIdByFile = new Map();
     const rejectedPaths = new Set();
     const rejectedConceptIds = new Set();
-    const workflowLookups = new Map();
-    for (const file of fileContexts) {
+    // A full directory drain may contain both peer workflow formats for one
+    // canonical ref.  Ownership arbitration must happen *before* recognition:
+    // otherwise both documents reach the persistence fold and SQLite's final
+    // row is determined by the walk/readdir order.  Resolve exactly the paths
+    // this drain owns, so a full scan retains only the deterministic `.md`
+    // winner while a targeted one-file reindex deliberately keeps its written
+    // source and therefore marks an existing peer row stale for read fallback.
+    const workflowOwnerPathByCanonicalName = new Map(resolveWorkflowSourceDomains(component.root, adapter.id, fileContexts.map((file) => file.absPath))
+        .filter((resolution) => resolution.source !== undefined)
+        .map((resolution) => [resolution.canonicalName, path.resolve(resolution.source.path)]));
+    const invalidWorkflowOwnerNames = new Set();
+    const orderedFileContexts = [...fileContexts].sort((left, right) => {
+        const leftName = workflowNameForSourcePath(component.root, adapter.id, left.absPath);
+        const rightName = workflowNameForSourcePath(component.root, adapter.id, right.absPath);
+        const leftOwner = leftName !== undefined &&
+            workflowOwnerPathByCanonicalName.get(canonicalizeWorkflowName(leftName)) === path.resolve(left.absPath);
+        const rightOwner = rightName !== undefined &&
+            workflowOwnerPathByCanonicalName.get(canonicalizeWorkflowName(rightName)) === path.resolve(right.absPath);
+        if (leftOwner !== rightOwner)
+            return leftOwner ? -1 : 1;
+        return compareCodePoints(left.absPath, right.absPath);
+    });
+    for (const file of orderedFileContexts) {
+        if (rejectedPaths.has(file.absPath))
+            continue;
         const workflowName = workflowNameForSourcePath(component.root, adapter.id, file.absPath);
         if (workflowName !== undefined) {
             const canonicalName = canonicalizeWorkflowName(workflowName);
-            if (!workflowLookups.has(canonicalName))
-                workflowLookups.set(canonicalName, workflowName);
-        }
-    }
-    for (const [canonicalName, workflowName] of [...workflowLookups].sort(([left], [right]) => compareCodePoints(left, right))) {
-        try {
-            resolveUniqueWorkflowSource(component.root, adapter.id, workflowName);
-        }
-        catch (error) {
-            if (!(error instanceof WorkflowSourceRejectionError))
-                throw error;
-            rejectedConceptIds.add(adapter.id === "akm" ? `workflows/${canonicalName}` : canonicalName);
-            for (const relativePath of error.sourcePaths) {
-                rejectedPaths.add(path.join(component.root, relativePath));
+            const ownerPath = workflowOwnerPathByCanonicalName.get(canonicalName);
+            if (ownerPath !== undefined &&
+                ownerPath !== path.resolve(file.absPath) &&
+                !invalidWorkflowOwnerNames.has(canonicalName)) {
+                continue;
             }
-            warnings.push(error.message);
         }
-    }
-    for (const file of fileContexts) {
-        if (rejectedPaths.has(file.absPath))
-            continue;
         const doc = adapter.recognize(component, file);
         if (doc === null)
             continue;
@@ -92,6 +101,8 @@ export function drainDirDocuments(adapter, component, fileContexts) {
         const dropWarning = handleWorkflowDoc(doc, file, component.root);
         if (dropWarning !== null) {
             warnings.push(dropWarning);
+            if (workflowName !== undefined)
+                invalidWorkflowOwnerNames.add(canonicalizeWorkflowName(workflowName));
             continue;
         }
         if (doc.hash !== undefined)

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

@@ -17,10 +17,11 @@ 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 { compareCodePoints } from "../../core/common.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 { allowsFragmentRef, defaultRendererRegistry } from "../../core/type-presentation.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";
@@ -186,13 +187,47 @@ export async function searchLocal(input) {
 }
 // ── Database search ─────────────────────────────────────────────────────────
 /**
- * Keep one deterministic ranking order before stable path deduplication. Exact
- * names survive the public score ceiling, while raw contributor differences
- * are quantized so utility-recency epsilon cannot reorder visible ties.
+ * Keep public scores in [0, 1] without flattening every boosted result to the
+ * same hard-clamped value. The ranking pipeline deliberately keeps its raw
+ * score for deterministic ordering before stable path deduplication; this
+ * monotone display projection preserves that order and leaves visible
+ * separation for graph, type, and project-context signals.
  */
+function displaySearchScore(score) {
+    return 1 - Math.exp(-Math.max(0, score));
+}
+/**
+ * A final deterministic key for genuinely tied candidates.  It deliberately
+ * excludes the asset name, filename, path, durable ref, and SQLite id: callers
+ * such as the memory-pack adapter generate each of those from an opaque source
+ * id, so using one here makes an otherwise equal search depend on that id.
+ *
+ * The normal AKM Markdown adapter keeps an H1 title in `content`; strip that
+ * one synthetic title too, because the adapter may derive it from the opaque
+ * filename.  Identical remaining bodies are semantically indistinguishable at
+ * this ranking stage and intentionally continue to the existing name/path
+ * fallback for repeatable local presentation.
+ */
+function asciiCaseFold(value) {
+    // SQLite's built-in lower() folds ASCII only unless a build opts into ICU.
+    // Keep this key deliberately in that portable shared subset instead of
+    // introducing locale-dependent JavaScript ordering for non-ASCII content.
+    return value.replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32));
+}
+/** The portable byte-level title/body rule mirrored in index-fts-repository. */
+export function canonicalContentTieKey(entry) {
+    const content = entry.content ?? "";
+    const newline = content.startsWith("# ") ? content.indexOf("\n") : -1;
+    // SQLite uses ltrim(value, char(13) || char(10) || ' ') after an exact '# '
+    // title and trim(value, ' ') otherwise. Keep exactly that deliberately
+    // narrow byte contract; do not use locale or Unicode-whitespace helpers.
+    const body = newline >= 0 ? content.slice(newline + 1).replace(/^[\r\n ]+/, "") : content;
+    const source = (body || entry.description || "").replace(/^ +| +$/g, "");
+    return Buffer.from(asciiCaseFold(source), "utf8").toString("hex");
+}
 function buildSearchResultComparator(query) {
     const queryTokens = buildLexicalQueryPlan(query).tokens.map((token) => token.toLowerCase());
-    const displayScore = (score) => Math.round(Math.min(1, Math.max(0, score)) * 10000) / 10000;
+    const displayScore = (score) => Math.round(displaySearchScore(score) * 10000) / 10000;
     const stableRankScore = (score) => Math.round(score * 10000) / 10000;
     return (a, b) => {
         const aNameTier = lexicalNameMatchTier(a.entry, queryTokens);
@@ -208,11 +243,28 @@ function buildSearchResultComparator(query) {
         const rawScoreDiff = stableRankScore(b.score) - stableRankScore(a.score);
         if (rawScoreDiff !== 0)
             return rawScoreDiff;
+        // Ceiling values are intentionally allowed to demote visibility, but not
+        // to erase relevance. Prefer the score before a relaxed body-only ceiling;
+        // a later belief-state ceiling has its own minScore handoff and must not
+        // overwrite this ordering evidence. Belief-only ceilings fall back to
+        // their `preCeilingScore`.
+        const preCeilingRelevance = (item) => item.preRelaxedCeilingScore ?? item.preCeilingScore ?? item.score;
+        const ceilingDiff = stableRankScore(preCeilingRelevance(b)) - stableRankScore(preCeilingRelevance(a));
+        if (ceilingDiff !== 0)
+            return ceilingDiff;
         const nameDiff = bNameTier - aNameTier;
         if (nameDiff !== 0)
             return nameDiff;
         const typeDiff = typeBoostFor(b.entry.type) - typeBoostFor(a.entry.type);
-        return typeDiff || a.filePath.localeCompare(b.filePath);
+        if (typeDiff !== 0)
+            return typeDiff;
+        // Keep opaque generated IDs out of the final relevance tie-break.  This
+        // runs only after every ranking contributor (including the #940 preserved
+        // pre-ceiling evidence), exact-name, and type comparison has tied.
+        const contentDiff = compareCodePoints(canonicalContentTieKey(a.entry), canonicalContentTieKey(b.entry));
+        if (contentDiff !== 0)
+            return contentDiff;
+        return a.filePath.localeCompare(b.filePath);
     };
 }
 async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false, disableProjectContext = false, disableScopedUtility = false) {
@@ -279,8 +331,9 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     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
-    // (FTS 0.7, vector 0.3) for well-differentiated combined scores.
+    // Stable bounded BM25 transform + cosine similarity with weighted addition
+    // (FTS 0.7, vector 0.3). The lexical transform is per-row, so widening the
+    // candidate set cannot alter a pre-existing row's base score.
     const ftsScoreMap = normalizeFtsScores(ftsResults);
     // Build embedding score map (cosine similarities already 0-1)
     const embedScoreMap = new Map();
@@ -400,11 +453,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const selected = beliefFiltered.slice(0, limit);
     const hits = await Promise.all(selected.map((ranked) => {
         const { entry, filePath, score, rankingMode, utilityBoosted } = ranked;
-        // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop above can
-        // exceed 1.0 (this was a pre-existing breach that #207's graph boost
-        // — up to ~1.05 additive contribution — made detectable); clamp here
-        // so the score handed to buildDbHit always satisfies the spec.
-        const finalScore = Math.min(1, Math.max(0, score));
+        // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop deliberately
+        // remains raw for ranking, then takes a monotone bounded projection at
+        // the public boundary so contributors do not collapse into hard-clamped
+        // ties.
+        const finalScore = displaySearchScore(score);
         return buildDbHit({
             entry,
             path: filePath,
@@ -413,6 +466,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             query,
             rankingMode,
             lexicalMatch: ranked.lexicalMatch,
+            fragmentId: ranked.fragmentId,
             defaultStashDir: stashDir,
             allSourceDirs,
             sources,
@@ -728,7 +782,11 @@ export async function buildDbHit(input) {
         (source && path.resolve(source.path) === path.resolve(input.defaultStashDir)
             ? (input.bundleId ?? undefined)
             : undefined);
-    const ref = resolveSearchHitRef(input.entry, input, defaultBundleId);
+    const parentRef = resolveSearchHitRef(input.entry, input, defaultBundleId);
+    // Fragments prove lexical relevance, but executable assets must retain the
+    // parent ref consumed by their advertised action (for example workflow run).
+    // The central type-presentation contract opts those types out explicitly.
+    const ref = input.fragmentId && allowsFragmentRef(input.entry.type) ? `${parentRef}#${input.fragmentId}` : parentRef;
     const editable = isEditable(absolutePath, input.config, input.sources);
     const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
     const hit = {