agentikit 0.0.12 → 0.0.14

package/dist/{src/embedder.js → embedder.js}

@@ -60,16 +60,71 @@ export async function embed(text, embeddingConfig) {
     }
     return embedLocal(text);
 }
+// ── Batch embedding ─────────────────────────────────────────────────────────
+/**
+ * Generate embeddings for multiple texts in batch.
+ * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
+ * Falls back to sequential embedding for local transformer pipeline.
+ */
+export async function embedBatch(texts, embeddingConfig) {
+    if (texts.length === 0)
+        return [];
+    if (embeddingConfig) {
+        return embedRemoteBatch(texts, embeddingConfig);
+    }
+    // Local transformer: process sequentially (pipeline handles one at a time)
+    const results = [];
+    for (const text of texts) {
+        results.push(await embedLocal(text));
+    }
+    return results;
+}
+async function embedRemoteBatch(texts, config) {
+    const BATCH_SIZE = 100;
+    const results = [];
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+        const batch = texts.slice(i, i + BATCH_SIZE);
+        const body = {
+            input: batch,
+            model: config.model,
+        };
+        if (config.dimension) {
+            body.dimensions = config.dimension;
+        }
+        const response = await fetchWithTimeout(config.endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const respBody = await response.text().catch(() => "");
+            throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
+        }
+        const json = (await response.json());
+        if (!json.data || json.data.length !== batch.length) {
+            throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}`);
+        }
+        results.push(...json.data.map((d) => d.embedding));
+    }
+    return results;
+}
 // ── Similarity ──────────────────────────────────────────────────────────────
 export function cosineSimilarity(a, b) {
     const len = Math.min(a.length, b.length);
     if (len === 0)
         return 0;
-    let dot = 0;
+    let dot = 0, magA = 0, magB = 0;
     for (let i = 0; i < len; i++) {
         dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
     }
-    return dot;
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
 }
 // ── Availability check ──────────────────────────────────────────────────────
 export async function isEmbeddingAvailable(embeddingConfig) {

package/dist/file-context.js

@@ -0,0 +1,158 @@
+/**
+ * Flexible asset resolution system.
+ *
+ * Provides a rich FileContext built once per file during walking, plus a
+ * matcher/renderer registry that decouples asset classification from rendering.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter";
+import { toPosix } from "./common";
+/**
+ * Build a FileContext from a stash root and an absolute file path.
+ *
+ * Path-derived fields are computed eagerly. The content, frontmatter, and
+ * stat getters use lazy caching so the file is only read from disk when
+ * (and if) a matcher or renderer actually needs it.
+ */
+export function buildFileContext(stashRoot, absPath) {
+    const relPath = toPosix(path.relative(stashRoot, absPath));
+    const ext = path.extname(absPath).toLowerCase();
+    const fileName = path.basename(absPath);
+    const parentDirAbs = path.dirname(absPath);
+    const parentDir = path.basename(parentDirAbs);
+    // Compute ancestor directory segments from the POSIX relPath's directory portion.
+    // For "tools/azure/deploy/run.sh" the dir portion is "tools/azure/deploy"
+    // which splits into ["tools", "azure", "deploy"].
+    const relDir = toPosix(path.dirname(relPath));
+    const ancestorDirs = relDir === "." ? [] : relDir.split("/").filter((seg) => seg.length > 0);
+    // Lazy caches
+    let cachedContent;
+    let cachedFrontmatter;
+    let frontmatterComputed = false;
+    let cachedStat;
+    return {
+        absPath,
+        relPath,
+        ext,
+        fileName,
+        parentDir,
+        parentDirAbs,
+        ancestorDirs,
+        stashRoot,
+        content() {
+            if (cachedContent === undefined) {
+                cachedContent = fs.readFileSync(absPath, "utf8");
+            }
+            return cachedContent;
+        },
+        frontmatter() {
+            if (!frontmatterComputed) {
+                const raw = this.content();
+                const parsed = parseFrontmatter(raw);
+                cachedFrontmatter =
+                    Object.keys(parsed.data).length > 0 ? parsed.data : null;
+                frontmatterComputed = true;
+            }
+            return cachedFrontmatter;
+        },
+        stat() {
+            if (cachedStat === undefined) {
+                cachedStat = fs.statSync(absPath);
+            }
+            return cachedStat;
+        },
+    };
+}
+// ── Registry ─────────────────────────────────────────────────────────────────
+/** Ordered list of registered matchers. Later registrations win ties. */
+const matchers = [];
+/** Renderer lookup by name. */
+const renderers = new Map();
+let builtinsInitialized = false;
+/**
+ * Ensure that built-in matchers and renderers are registered.
+ * Called lazily on first use of runMatchers/getRenderer.
+ */
+function ensureBuiltinsRegistered() {
+    if (builtinsInitialized)
+        return;
+    builtinsInitialized = true;
+    // Side-effect imports that register matchers/renderers at module load
+    require("./matchers");
+    require("./renderers");
+}
+/**
+ * Register an AssetMatcher.
+ *
+ * Matchers are evaluated in registration order. When two matchers produce
+ * the same specificity score, the one registered later wins.
+ */
+export function registerMatcher(matcher) {
+    matchers.push(matcher);
+}
+/**
+ * Register an AssetRenderer.
+ *
+ * If a renderer with the same name already exists it is silently replaced.
+ */
+export function registerRenderer(renderer) {
+    renderers.set(renderer.name, renderer);
+}
+/**
+ * Look up a renderer by name.
+ */
+export function getRenderer(name) {
+    ensureBuiltinsRegistered();
+    return renderers.get(name);
+}
+/**
+ * Return all registered renderers (snapshot, safe to iterate).
+ */
+export function getAllRenderers() {
+    ensureBuiltinsRegistered();
+    return Array.from(renderers.values());
+}
+/**
+ * Run every registered matcher against a FileContext and return the
+ * highest-specificity result.
+ *
+ * Resolution rules:
+ * 1. Every matcher is invoked; null returns are discarded.
+ * 2. Results are ranked by specificity (descending).
+ * 3. Ties are broken by registration order: the matcher registered later wins
+ *    (this lets user-registered matchers override built-in ones).
+ * 4. Returns null when no matcher claims the file.
+ */
+export function runMatchers(ctx) {
+    ensureBuiltinsRegistered();
+    // Collect (result, registrationIndex) pairs from all matchers.
+    const hits = [];
+    for (let i = 0; i < matchers.length; i++) {
+        const result = matchers[i](ctx);
+        if (result !== null) {
+            hits.push({ result, index: i });
+        }
+    }
+    if (hits.length === 0)
+        return null;
+    // Sort by specificity descending, then by registration index descending (later wins ties).
+    hits.sort((a, b) => {
+        const specDiff = b.result.specificity - a.result.specificity;
+        if (specDiff !== 0)
+            return specDiff;
+        return b.index - a.index;
+    });
+    return hits[0].result;
+}
+/**
+ * Build a RenderContext by merging a FileContext with its winning MatchResult
+ * and the list of stash search paths.
+ */
+export function buildRenderContext(ctx, match, stashDirs) {
+    return {
+        ...ctx,
+        matchResult: match,
+        stashDirs,
+    };
+}

package/dist/{src/handlers → handlers}/command-handler.js

@@ -14,6 +14,8 @@ export const commandHandler = {
             path: input.path,
             description: toStringOrUndefined(parsedMd.data.description),
             template: parsedMd.content,
+            modelHint: parsedMd.data.model,
+            agent: toStringOrUndefined(parsedMd.data.agent),
         };
     },
     defaultUsageGuide: [

package/dist/{src/handlers → handlers}/index.js

@@ -15,9 +15,3 @@ registerAssetType(commandHandler);
 registerAssetType(agentHandler);
 registerAssetType(knowledgeHandler);
 registerAssetType(scriptHandler);
-export { toolHandler } from "./tool-handler";
-export { skillHandler } from "./skill-handler";
-export { commandHandler } from "./command-handler";
-export { agentHandler } from "./agent-handler";
-export { knowledgeHandler } from "./knowledge-handler";
-export { scriptHandler } from "./script-handler";

package/dist/{src/indexer.js → indexer.js}

@@ -4,7 +4,7 @@ import { resolveStashDir } from "./common";
 import { ASSET_TYPES, TYPE_DIRS, deriveCanonicalAssetName } from "./asset-spec";
 import { loadStashFile, writeStashFile, generateMetadata, } from "./metadata";
 import { walkStash } from "./walker";
-import { openDatabase, closeDatabase, getDbPath, getMeta, setMeta, upsertEntry, deleteEntriesByDir, rebuildFts, upsertEmbedding, getEntriesByDir, getEntryCount, isVecAvailable, DB_VERSION, } from "./db";
+import { openDatabase, closeDatabase, getDbPath, getMeta, setMeta, upsertEntry, deleteEntriesByDir, rebuildFts, upsertEmbedding, getEntriesByDir, getEntryCount, isVecAvailable, warnIfVecMissing, DB_VERSION, } from "./db";
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function agentikitIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
@@ -26,14 +26,19 @@ export async function agentikitIndex(options) {
         const builtAtMs = isIncremental ? new Date(prevBuiltAt).getTime() : 0;
         if (options?.full || !isIncremental) {
             // Wipe all entries for full rebuild or stashDir change
-            db.exec("DELETE FROM entries");
-            db.exec("DELETE FROM entries_fts");
-            if (isVecAvailable()) {
+            // Delete from child tables first to respect foreign key constraints
+            try {
+                db.exec("DELETE FROM embeddings");
+            }
+            catch { /* ignore */ }
+            if (isVecAvailable(db)) {
                 try {
                     db.exec("DELETE FROM entries_vec");
                 }
                 catch { /* ignore */ }
             }
+            db.exec("DELETE FROM entries_fts");
+            db.exec("DELETE FROM entries");
         }
         const tWalkStart = Date.now();
         // Walk stash dirs and index entries
@@ -54,6 +59,8 @@ export async function agentikitIndex(options) {
         setMeta(db, "stashDirs", JSON.stringify(allStashDirs));
         setMeta(db, "hasEmbeddings", hasEmbeddings ? "1" : "0");
         const totalEntries = getEntryCount(db);
+        // Warn on every index run if using JS fallback with many entries
+        warnIfVecMissing(db);
         const tEnd = Date.now();
         return {
             stashDir,
@@ -117,6 +124,20 @@ function indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs) {
                             stash = migration.stash;
                             writeStashFile(dirPath, stash);
                         }
+                        // Check for files on disk that aren't covered by existing .stash.json entries.
+                        // This handles the case where new files are added after the initial index.
+                        const coveredFiles = new Set(stash.entries
+                            .map((e) => e.entry)
+                            .filter((e) => !!e));
+                        const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
+                        if (uncoveredFiles.length > 0) {
+                            const generated = generateMetadata(dirPath, assetType, uncoveredFiles, typeRoot);
+                            if (generated.entries.length > 0) {
+                                stash = { entries: [...stash.entries, ...generated.entries] };
+                                writeStashFile(dirPath, stash);
+                                generatedCount += generated.entries.length;
+                            }
+                        }
                     }
                     if (!stash) {
                         // Generate metadata heuristically
@@ -166,14 +187,17 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     }
 }
 async function generateEmbeddingsForDb(db, config) {
-    if (!config.semanticSearch || !isVecAvailable())
+    if (!config.semanticSearch)
         return false;
     try {
-        const { embed } = await import("./embedder.js");
+        const { embedBatch } = await import("./embedder.js");
         const allEntries = getAllEntriesForEmbedding(db);
-        for (const { id, searchText } of allEntries) {
-            const embedding = await embed(searchText, config.embedding);
-            upsertEmbedding(db, id, embedding);
+        if (allEntries.length === 0)
+            return true;
+        const texts = allEntries.map((e) => e.searchText);
+        const embeddings = await embedBatch(texts, config.embedding);
+        for (let i = 0; i < allEntries.length; i++) {
+            upsertEmbedding(db, allEntries[i].id, embeddings[i]);
         }
         return true;
     }
@@ -187,7 +211,7 @@ function getAllEntriesForEmbedding(db) {
     return db
         .prepare(`
       SELECT e.id, e.search_text AS searchText FROM entries e
-      WHERE NOT EXISTS (SELECT 1 FROM entries_vec v WHERE v.id = e.id)
+      WHERE NOT EXISTS (SELECT 1 FROM embeddings b WHERE b.id = e.id)
     `)
         .all();
 }

package/dist/init.js

@@ -0,0 +1,43 @@
+/**
+ * Agentikit initialization logic.
+ *
+ * Creates the working stash directory structure, persists the stashDir
+ * in config.json, and ensures ripgrep is available.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "./common";
+import { ensureRg } from "./ripgrep-install";
+import { loadConfig, saveConfig, getConfigPath } from "./config";
+import { getDefaultStashDir, getBinDir } from "./paths";
+export async function agentikitInit(options) {
+    const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
+    let created = false;
+    if (!fs.existsSync(stashDir)) {
+        fs.mkdirSync(stashDir, { recursive: true });
+        created = true;
+    }
+    for (const sub of Object.values(TYPE_DIRS)) {
+        const subDir = path.join(stashDir, sub);
+        if (!fs.existsSync(subDir)) {
+            fs.mkdirSync(subDir, { recursive: true });
+        }
+    }
+    // Persist stashDir in config.json
+    const configPath = getConfigPath();
+    const existing = loadConfig();
+    if (!existing.stashDir || existing.stashDir !== stashDir) {
+        saveConfig({ ...existing, stashDir });
+    }
+    // Ensure ripgrep is available (install to cache/bin if needed)
+    let ripgrep;
+    try {
+        const binDir = getBinDir();
+        const rgResult = ensureRg(binDir);
+        ripgrep = rgResult;
+    }
+    catch {
+        // Non-fatal: ripgrep is optional, search works without it
+    }
+    return { stashDir, created, configPath, ripgrep };
+}

package/dist/lockfile.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getConfigDir } from "./config";
+// ── Paths ───────────────────────────────────────────────────────────────────
+function getLockfilePath() {
+    return path.join(getConfigDir(), "stash.lock");
+}
+// ── Read / Write ────────────────────────────────────────────────────────────
+export function readLockfile() {
+    const lockfilePath = getLockfilePath();
+    try {
+        const raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter(isValidLockfileEntry);
+    }
+    catch {
+        return [];
+    }
+}
+export function writeLockfile(entries) {
+    const lockfilePath = getLockfilePath();
+    const dir = path.dirname(lockfilePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = lockfilePath + `.tmp.${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(entries, null, 2) + "\n", "utf8");
+        fs.renameSync(tmpPath, lockfilePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* ignore cleanup failure */ }
+        throw err;
+    }
+}
+export function upsertLockEntry(entry) {
+    const entries = readLockfile();
+    const withoutExisting = entries.filter((e) => e.id !== entry.id);
+    writeLockfile([...withoutExisting, entry]);
+}
+export function removeLockEntry(id) {
+    const entries = readLockfile();
+    writeLockfile(entries.filter((e) => e.id !== id));
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function isValidLockfileEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const obj = value;
+    return (typeof obj.id === "string" && obj.id !== "" &&
+        typeof obj.source === "string" && ["npm", "github", "git", "local"].includes(obj.source) &&
+        typeof obj.ref === "string" && obj.ref !== "");
+}

package/dist/matchers.js

@@ -0,0 +1,157 @@
+/**
+ * Built-in asset matchers for the agentikit file classification system.
+ *
+ * Four matchers are registered at module load time, each at a different
+ * specificity level. Extension and content determine type; directories are
+ * optional specificity boosts, not requirements.
+ *
+ * - `extensionMatcher` (3) -- classifies any file by extension alone.
+ *   Ensures every known file type is discoverable regardless of directory.
+ * - `directoryMatcher` (10) -- boosts specificity when the first ancestor
+ *   directory matches a known type name (e.g. `scripts/`, `agents/`).
+ * - `parentDirHintMatcher` (15) -- boosts specificity based on the
+ *   immediate parent directory name.
+ * - `smartMdMatcher` (20 / 18 / 8 / 5) -- inspects markdown frontmatter
+ *   and body content for agent/command signals; falls back to "knowledge"
+ *   at specificity 5 when no signals are found. Command signals (`agent`
+ *   frontmatter, `$ARGUMENTS`/`$1`-`$3` placeholders) return 18.
+ */
+import { SCRIPT_EXTENSIONS_BROAD } from "./asset-spec";
+import { registerMatcher } from "./file-context";
+// ── extensionMatcher (specificity: 3) ────────────────────────────────────────
+/**
+ * Base-level matcher that classifies files purely by extension.
+ *
+ * This is the foundation of the classification system: every file with a
+ * known extension gets a type, regardless of what directory it lives in.
+ * Higher-specificity matchers (directory, content) can override this.
+ *
+ * .md files are NOT handled here -- smartMdMatcher provides richer
+ * classification for markdown via frontmatter inspection.
+ */
+export function extensionMatcher(ctx) {
+    // SKILL.md is a skill regardless of location
+    if (ctx.fileName === "SKILL.md") {
+        return { type: "skill", specificity: 3, renderer: "skill-md" };
+    }
+    // Known script extensions (excluding .md, handled by smartMdMatcher)
+    if (SCRIPT_EXTENSIONS_BROAD.has(ctx.ext)) {
+        return { type: "script", specificity: 3, renderer: "script-source" };
+    }
+    return null;
+}
+// ── directoryMatcher (specificity: 10) ──────────────────────────────────────
+/**
+ * Directory-based matcher that boosts specificity when the first ancestor
+ * directory segment from the stash root matches a known type name.
+ *
+ * Accepts ALL known script extensions in both `tools/` and `scripts/`
+ * directories -- the distinction is purely organizational.
+ */
+export function directoryMatcher(ctx) {
+    const topDir = ctx.ancestorDirs[0];
+    if (!topDir)
+        return null;
+    const ext = ctx.ext;
+    if ((topDir === "tools" || topDir === "scripts") && SCRIPT_EXTENSIONS_BROAD.has(ext)) {
+        return { type: "script", specificity: 10, renderer: "script-source" };
+    }
+    if (topDir === "skills" && ctx.fileName === "SKILL.md") {
+        return { type: "skill", specificity: 10, renderer: "skill-md" };
+    }
+    if (topDir === "commands" && ext === ".md") {
+        return { type: "command", specificity: 10, renderer: "command-md" };
+    }
+    if (topDir === "agents" && ext === ".md") {
+        return { type: "agent", specificity: 10, renderer: "agent-md" };
+    }
+    if (topDir === "knowledge" && ext === ".md") {
+        return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
+    }
+    return null;
+}
+// ── parentDirHintMatcher (specificity: 15) ──────────────────────────────────
+/**
+ * Uses the immediate parent directory name as a hint. More specific than
+ * the ancestor-based directory matcher because the file might be nested
+ * several levels deep, yet its immediate parent can still carry strong
+ * naming conventions (e.g. `my-project/agents/planning.md`).
+ *
+ * Accepts ALL known script extensions in both `tools/` and `scripts/`.
+ */
+export function parentDirHintMatcher(ctx) {
+    const { parentDir, ext, fileName } = ctx;
+    if ((parentDir === "tools" || parentDir === "scripts") && SCRIPT_EXTENSIONS_BROAD.has(ext)) {
+        return { type: "script", specificity: 15, renderer: "script-source" };
+    }
+    if (parentDir === "skills" && fileName === "SKILL.md") {
+        return { type: "skill", specificity: 15, renderer: "skill-md" };
+    }
+    if (parentDir === "agents" && ext === ".md") {
+        return { type: "agent", specificity: 15, renderer: "agent-md" };
+    }
+    if (parentDir === "commands" && ext === ".md") {
+        return { type: "command", specificity: 15, renderer: "command-md" };
+    }
+    if (parentDir === "knowledge" && ext === ".md") {
+        return { type: "knowledge", specificity: 15, renderer: "knowledge-md" };
+    }
+    return null;
+}
+// ── smartMdMatcher (specificity: 20 / 18 / 8 / 5) ──────────────────────────
+/** Pattern that matches OpenCode command placeholders in markdown body. */
+const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+/**
+ * Content-based matcher for `.md` files. Inspects frontmatter keys and body
+ * content to classify markdown as agent, command, or knowledge.
+ *
+ * Specificity levels:
+ *   20 -- agent-exclusive signals (`tools`, `toolPolicy`)
+ *   18 -- command content signals (`agent` frontmatter, `$ARGUMENTS`/`$1`-`$3`)
+ *    8 -- weak agent signal (`model` alone)
+ *    5 -- knowledge fallback (any unclassified `.md`)
+ *
+ * Command signals at 18 override directory hints (10/15) because the content
+ * unambiguously identifies a command template. Agent-exclusive signals at 20
+ * still win over command signals when both are present.
+ */
+export function smartMdMatcher(ctx) {
+    if (ctx.ext !== ".md")
+        return null;
+    const fm = ctx.frontmatter();
+    if (fm) {
+        // Agent-exclusive indicators: toolPolicy or tools
+        // These return high specificity (20) to override everything else.
+        if ("toolPolicy" in fm || "tools" in fm) {
+            return { type: "agent", specificity: 20, renderer: "agent-md" };
+        }
+        // Command signal: `agent` frontmatter key names a dispatch target.
+        // This is an OpenCode convention specific to commands.
+        if ("agent" in fm) {
+            return { type: "command", specificity: 18, renderer: "command-md" };
+        }
+    }
+    // Command signal: body contains $ARGUMENTS or $1/$2/$3 placeholders.
+    // These are definitively command template patterns (OpenCode convention).
+    const body = ctx.content();
+    if (COMMAND_PLACEHOLDER_RE.test(body)) {
+        return { type: "command", specificity: 18, renderer: "command-md" };
+    }
+    if (fm) {
+        // model alone is a weaker agent signal (specificity 8) -- it can appear
+        // on commands too (OpenCode convention). Directory hints (10/15) win
+        // when the file lives in commands/, but model still classifies an .md
+        // as agent when no directory hint is present.
+        if ("model" in fm) {
+            return { type: "agent", specificity: 8, renderer: "agent-md" };
+        }
+    }
+    // Weak fallback: any .md file is assumed to be knowledge
+    return { type: "knowledge", specificity: 5, renderer: "knowledge-md" };
+}
+// ── Registration ────────────────────────────────────────────────────────────
+// Order matters: later registrations win ties at the same specificity.
+registerMatcher(extensionMatcher);
+registerMatcher(directoryMatcher);
+registerMatcher(parentDirHintMatcher);
+registerMatcher(smartMdMatcher);

package/dist/{src/metadata.js → metadata.js}

@@ -31,7 +31,18 @@ export function loadStashFile(dirPath) {
 }
 export function writeStashFile(dirPath, stash) {
     const filePath = stashFilePath(dirPath);
-    fs.writeFileSync(filePath, JSON.stringify(stash, null, 2) + "\n", "utf8");
+    const tmpPath = filePath + `.tmp.${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(stash, null, 2) + "\n", "utf8");
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* ignore cleanup failure */ }
+        throw err;
+    }
 }
 export function validateStashEntry(entry) {
     if (typeof entry !== "object" || entry === null)

package/dist/{src/origin-resolve.js → origin-resolve.js}

@@ -5,21 +5,22 @@ import { parseRegistryRef } from "./registry-resolve";
  * sources, return the subset of sources to search.
  *
  * Resolution order:
- *   1. undefined   → all sources (working → mounted → installed)
- *   2. "local"     → working stash only
- *   3. exact match → installed source whose registryId matches verbatim
+ *   1. undefined   → all sources
+ *   2. "local"     → primary stash only (first entry)
+ *   3. exact match → source whose registryId matches verbatim
  *   4. parsed match → parse origin as a registry ref, match by parsed ID
- *   5. path match  → mounted source whose path matches
+ *   5. path match  → source whose resolved path matches the origin
  *   6. empty       → indicates a remote/uninstalled origin (caller decides)
  */
 export function resolveSourcesForOrigin(origin, allSources) {
     if (!origin)
         return allSources;
+    // "local" means the primary stash (first entry)
     if (origin === "local") {
-        return allSources.filter((s) => s.kind === "working");
+        return allSources.length > 0 ? [allSources[0]] : [];
     }
     // Exact registryId match (e.g. origin is "npm:@scope/pkg")
-    const byExactId = allSources.filter((s) => s.kind === "installed" && s.registryId === origin);
+    const byExactId = allSources.filter((s) => s.registryId !== undefined && s.registryId === origin);
     if (byExactId.length > 0)
         return byExactId;
     // Parse origin as a registry ref and match by parsed ID.
@@ -27,16 +28,16 @@ export function resolveSourcesForOrigin(origin, allSources) {
     // "@scope/pkg" matches "npm:@scope/pkg".
     try {
         const parsed = parseRegistryRef(origin);
-        const byParsedId = allSources.filter((s) => s.kind === "installed" && s.registryId === parsed.id);
+        const byParsedId = allSources.filter((s) => s.registryId !== undefined && s.registryId === parsed.id);
         if (byParsedId.length > 0)
             return byParsedId;
     }
     catch {
         // Not a valid registry ref — continue to path matching
     }
-    // Mounted stash by resolved path
+    // Match by resolved path (any source, including installed)
     const resolvedOrigin = path.resolve(origin);
-    const byPath = allSources.filter((s) => s.kind === "mounted" && path.resolve(s.path) === resolvedOrigin);
+    const byPath = allSources.filter((s) => path.resolve(s.path) === resolvedOrigin);
     if (byPath.length > 0)
         return byPath;
     // No match — origin may be remote/uninstalled