akm-cli 0.8.7 → 0.8.14

package/dist/indexer/{staleness-detect.js → passes/staleness-detect.js}

@@ -1,19 +1,59 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Staleness-detection pass for `akm improve` (Phase 4A,
+ * `.plans/0.8.0/self-improvement-enhancements-plan.md` lines 132-145).
+ *
+ * Activates the `deprecated` belief-state machinery shipped in Phase 1A
+ * (commit 7b6fffe). Without this pass, nothing in the pipeline ever wrote
+ * `beliefState: deprecated`, so the -0.15 ranking penalty and the
+ * `matchBeliefFilter("historical")` inclusion were dormant.
+ *
+ * Pipeline
+ * --------
+ *   1. Walk every memory under `<stash>/memories/` and select candidates
+ *      whose belief state is NOT already excluded
+ *      ({contradicted, archived, deprecated}) AND whose `lastConfirmedAt`
+ *      is absent or older than the configured threshold (default 90 days).
+ *      Files without `lastConfirmedAt` fall back to file `mtime`.
+ *   2. For each candidate, ask the configured validation-tier LLM
+ *      (`resolveValidationRunner`) whether the candidate is still current
+ *      given the top-K most-similar memories from the stash.
+ *      Strict response contract: `YES\nSUPERSEDED_BY: <ref>` or `NO`.
+ *      Anything else is treated as a parse error and the candidate is skipped.
+ *   3. YES → write `beliefState: "deprecated"`, `supersededBy: [<ref>]`,
+ *      `lastConfirmedAt: <now>`. The supersededBy ref MUST exist in the
+ *      stash (DB lookup); if it doesn't, treat as NO.
+ *      NO → write only `lastConfirmedAt: <now>` (refreshes the staleness
+ *      window). All other frontmatter fields stay untouched.
+ *
+ * Caching
+ * -------
+ * Uses the standard `withLlmCache` wrapper with cacheVariant
+ * `"staleness_detect"`, so re-running the pass on an unchanged file is a
+ * no-op (no LLM call).
+ *
+ * Feature gate
+ * ------------
+ * Default OFF. Enable via `features.index.staleness_detection.enabled` (or
+ * the boolean shorthand `features.index.staleness_detection = true`).
+ * Threshold-days knob lives at
+ * `features.index.staleness_detection.options.thresholdDays` (default 90).
+ */
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { assembleAsset } from "../core/asset-serialize";
-import { concurrentMap } from "../core/concurrent";
-import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
-import { warn } from "../core/warn";
-import { resolveValidationRunner } from "../integrations/agent/runner";
-import { chatCompletion } from "../llm/client";
-import { isProcessEnabled } from "../llm/feature-gate";
-import { findEntryIdByRef } from "./db";
-import { withLlmCache } from "./llm-cache";
-import { walkMarkdownFiles } from "./walker";
+import { assembleAsset } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
+import { concurrentMap } from "../../core/concurrent.js";
+import { warn } from "../../core/warn.js";
+import { resolveValidationRunner, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { chatCompletion } from "../../llm/client.js";
+import { isProcessEnabled } from "../../llm/feature-gate.js";
+import { findEntryIdByRef } from "../db/db.js";
+import { withLlmCache } from "../db/llm-cache.js";
+import { walkMarkdownFiles } from "../walk/walker.js";
 /** Frontmatter keys this pass touches. Constants so a future rename only needs to touch one site. */
 const FM_BELIEF_STATE = "beliefState";
 const FM_SUPERSEDED_BY = "supersededBy";
@@ -30,7 +70,8 @@ const TOP_K_SIMILAR = 5;
  * Top-level entry point. Returns a zero-counters result when the feature is
  * disabled or no validation-tier runner is configured.
  */
-export async function runStalenessDetectionPass(config, sources, signal, db) {
+export async function runStalenessDetectionPass(ctx) {
+    const { config, sources, signal, db } = ctx;
     const start = Date.now();
     const result = {
         considered: 0,
@@ -58,7 +99,7 @@ export async function runStalenessDetectionPass(config, sources, signal, db) {
         result.durationMs = Date.now() - start;
         return result;
     }
-    if (runner.kind !== "llm") {
+    if (!runnerIsLlm(runner)) {
         // MVP scope: only the LLM runner kind is supported. Agent/SDK runners
         // would require a different prompt-dispatch path that is out of scope
         // for the initial Phase 4A implementation.

package/dist/indexer/{db-search.js → search/db-search.js}

@@ -1,22 +1,34 @@
 // 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 fs from "node:fs";
-import { buildActionFromContributors, defaultActionContributors } from "../core/action-contributors";
-import { makeAssetRef } from "../core/asset-ref";
-import { defaultRendererRegistry } from "../core/asset-registry";
-import { getDbPath } from "../core/paths";
-import { warn } from "../core/warn";
-import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getPositiveFeedbackCountsByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
-import { ensureIndex } from "./ensure-index";
-import { collectGraphRelatedHit, computeGraphBoost, loadGraphBoostContext, } from "./graph-boost";
-import { isProposedQuality } from "./metadata";
-import { resolveProjectContext } from "./project-context";
-import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ranking";
-import { enrichSearchHit } from "./search-hit-enrichers";
-import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
-import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
+import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
+import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { defaultRendererRegistry } from "../../core/asset/asset-registry.js";
+import { getDbPath } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
+import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getPositiveFeedbackCountsByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "../db/db.js";
+import { ensureIndex } from "../ensure-index.js";
+import { collectGraphRelatedHit, computeGraphBoost, loadGraphBoostContext, } from "../graph/graph-boost.js";
+import { isProposedQuality } from "../passes/metadata.js";
+import { resolveProjectContext } from "../walk/project-context.js";
+import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ranking.js";
+import { enrichSearchHit } from "./search-hit-enrichers.js";
+import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
+import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status.js";
 export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
     return buildActionFromContributors({ type, ref }, defaultActionContributors(registry)) ?? `akm show ${ref}`;
 }
@@ -358,7 +370,7 @@ async function tryVecScores(db, query, k, config) {
     if (hasEmbeddings !== "1")
         return null;
     try {
-        const { embed } = await import("../llm/embedder.js");
+        const { embed } = await import("../../llm/embedder.js");
         const queryEmbedding = await embed(query, config.embedding);
         const vecResults = searchVec(db, queryEmbedding, k);
         const scores = new Map();

package/dist/indexer/{ranking-contributors.js → search/ranking-contributors.js}

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { computeGraphBoost } from "./graph-boost";
+import { computeGraphBoost } from "../graph/graph-boost.js";
 const TYPE_BOOST = {
     skill: 0.4,
     command: 0.35,

package/dist/indexer/{ranking.js → search/ranking.js}

@@ -1,8 +1,8 @@
 // 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 { getUtilityScoresByIds } from "./db";
-import { applyScoreContributors, applyUtilityContributors } from "./ranking-contributors";
+import { getUtilityScoresByIds } from "../db/db.js";
+import { applyScoreContributors, applyUtilityContributors } from "./ranking-contributors.js";
 export function normalizeFtsScores(results) {
     const ftsScoreMap = new Map();
     if (results.length === 0)

package/dist/indexer/{search-hit-enrichers.js → search/search-hit-enrichers.js}

@@ -1,9 +1,9 @@
 // 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 { makeAssetRef } from "../core/asset-ref";
-import { getDerivedForParent } from "./db";
-import { getRenderer } from "./file-context";
+import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { getDerivedForParent } from "../db/db.js";
+import { getRenderer } from "../walk/file-context.js";
 const rendererSearchHitEnricher = {
     name: "renderer-search-hit-enricher",
     appliesTo(ctx) {

package/dist/indexer/{search-source.js → search/search-source.js}

@@ -3,15 +3,15 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../core/common";
-import { getSources, loadConfig } from "../core/config";
-import { resolveSourceProviderFactory } from "../sources/provider-factory";
+import { resolveStashDir } from "../../core/common.js";
+import { getSources, loadConfig } from "../../core/config/config.js";
+import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
-import "../sources/providers/index";
-import { warn } from "../core/warn";
-import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
-import { ensureWebsiteMirror } from "../sources/website-ingest";
+import "../../sources/providers/index.js";
+import { warn } from "../../core/warn.js";
+import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../../sources/providers/git.js";
+import { ensureWebsiteMirror } from "../../sources/website-ingest.js";
 // Legacy "context-hub" / "github" type aliases are normalized to "git" at
 // config-load time (see src/config.ts), so this set only contains the canonical
 // type.
@@ -108,7 +108,7 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
  * so the caller can skip it.
  *
  * Single source of truth: each provider owns its own path. We instantiate the
- * registered {@link import("../sources/provider").SourceProvider} for the entry
+ * registered {@link import("../../sources/provider.js").SourceProvider} for the entry
  * and call `provider.path()`. This replaces the old per-kind switch ladder
  * (filesystem path / git cache / website cache) that lived here in 0.6.0 —
  * see spec §10 step 4 and §7 "Removed from 0.6.0".

package/dist/indexer/{semantic-status.js → search/semantic-status.js}

@@ -2,9 +2,9 @@
 // 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 fs from "node:fs";
-import { writeFileAtomic } from "../core/common";
-import { getCacheDir, getSemanticStatusPath } from "../core/paths";
-import { DEFAULT_LOCAL_MODEL } from "../llm/embedders/local";
+import { writeFileAtomic } from "../../core/common.js";
+import { getCacheDir, getSemanticStatusPath } from "../../core/paths.js";
+import { DEFAULT_LOCAL_MODEL } from "../../llm/embedders/local.js";
 export function deriveSemanticProviderFingerprint(embedding) {
     if (embedding?.endpoint) {
         return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;

package/dist/indexer/usage/unmigrated-vaults-guard.js

@@ -0,0 +1,94 @@
+// 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/.
+/**
+ * One-time, read-only guard for un-migrated `vaults/` directories (0.9.0).
+ *
+ * Background: 0.8.0 introduced the `env` asset type and a `vaults/` → `env/`
+ * copy migration (run by `akm-migrate-storage`). 0.9.0 removed the `vault`
+ * asset type entirely, and the indexer now unconditionally SKIPS `vaults/`
+ * (see `shouldIndexStashFile` in `metadata.ts`). A user who upgrades straight
+ * to 0.9.0 without ever running the storage migration therefore has the `.env`
+ * data in their `vaults/` directory silently dropped from the index — it was
+ * never copied to `env/`, and `vaults/` is no longer scanned.
+ *
+ * This guard detects exactly that state on a stash and emits ONE clear warning
+ * pointing at `akm-migrate-storage`. It is:
+ *   - Non-destructive: it never reads `.env` contents, never writes, never
+ *     deletes, and never moves anything. It only stats directory entries.
+ *   - Idempotent: the warning is emitted at most once per process per stash
+ *     directory (deduped in-memory).
+ *
+ * It deliberately does NOT auto-run the copy: filesystem mutation + chmod of
+ * secret material stays in the dedicated `akm-migrate-storage` bin, behind the
+ * user's explicit invocation, never as a side effect of a normal `akm` command.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { warn } from "../../core/warn.js";
+/**
+ * Marker filename the `vaults/` → `env/` migration drops inside `vaults/` after
+ * a successful copy. Single source of truth shared with
+ * `scripts/migrate-storage.ts` (which writes it) and this guard (which reads
+ * it). Its presence means the data already lives under `env/` (or was a no-op
+ * fresh install).
+ */
+export const MIGRATED_MARKER = ".migrated";
+/** Stashes already warned about in this process — keyed by absolute stash dir. */
+const warnedStashDirs = new Set();
+/** True when `dir` contains at least one `*.env` / `.env` file (recursively). */
+function hasEnvFilesRecursive(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (hasEnvFilesRecursive(full))
+                return true;
+        }
+        else if (entry.name === ".env" || entry.name.endsWith(".env")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Warn (once) when `<stashDir>/vaults/` holds `.env` data that was never
+ * migrated to `env/`. No-op when there is no `vaults/` dir, when the
+ * `vaults/.migrated` marker is present, or when `vaults/` has no `.env` files.
+ *
+ * @returns `true` when a warning was emitted, `false` otherwise. The return is
+ *   primarily for tests; callers can ignore it.
+ */
+export function warnOnUnmigratedVaults(stashDir) {
+    const resolved = path.resolve(stashDir);
+    if (warnedStashDirs.has(resolved))
+        return false;
+    const vaultsDir = path.join(resolved, "vaults");
+    if (!fs.existsSync(vaultsDir))
+        return false;
+    // The migration writes this marker after a successful copy. Its presence
+    // means the data already lives under env/ (or was a no-op fresh install).
+    if (fs.existsSync(path.join(vaultsDir, MIGRATED_MARKER)))
+        return false;
+    if (!hasEnvFilesRecursive(vaultsDir))
+        return false;
+    // Mark before emitting so a throw in `warn` can't cause a re-warn loop.
+    warnedStashDirs.add(resolved);
+    warn(`[akm] WARNING: found un-migrated secrets in ${vaultsDir}.\n` +
+        `  The 'vault' asset type was removed in 0.9.0 and 'vaults/' is no longer indexed,\n` +
+        `  so this data will NOT appear under 'env:' until you migrate it. Run:\n` +
+        `      akm-migrate-storage --yes\n` +
+        `  This copies 'vaults/' -> 'env/' (non-destructive — your 'vaults/' dir is left intact).\n` +
+        `  See docs/migration/v0.8-to-v0.9.md.`);
+    return true;
+}
+/** Test-only: clear the per-process dedup set. */
+export function _resetUnmigratedVaultsGuardForTests() {
+    warnedStashDirs.clear();
+}

package/dist/indexer/{usage-events.js → usage/usage-events.js}

@@ -54,12 +54,44 @@ export function getUsageEvents(db, filters) {
         conditions.push("source = ?");
         params.push(filters.source);
     }
+    if (filters?.since) {
+        conditions.push("created_at >= ?");
+        params.push(filters.since);
+    }
     const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
     const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
                FROM usage_events ${where}
                ORDER BY id ASC`;
     return db.prepare(sql).all(...params);
 }
+/**
+ * Aggregate positive/negative feedback counts for a single entry.
+ *
+ * Lifted verbatim from `akm feedback` (feedback-cli.ts) where the same
+ * SUM(CASE …) query was hand-rolled inline. Returns plain numbers (NULL SUMs
+ * over an empty set are coalesced to 0) so the result fully materialises before
+ * any owning connection closes.
+ */
+export function countFeedbackSignals(db, entryId) {
+    const counts = db
+        .prepare(`SELECT
+         SUM(CASE WHEN signal = 'positive' THEN 1 ELSE 0 END) AS pos,
+         SUM(CASE WHEN signal = 'negative' THEN 1 ELSE 0 END) AS neg
+       FROM usage_events
+       WHERE event_type = 'feedback' AND entry_id = ?`)
+        .get(entryId);
+    return { pos: counts?.pos ?? 0, neg: counts?.neg ?? 0 };
+}
+/**
+ * Count usage events of a given `event_type`.
+ *
+ * Lifted verbatim from `akm improve` (improve.ts) where the show-event count
+ * was hand-rolled inline to drive the zero-feedback fallback warning.
+ */
+export function countUsageEventsByType(db, eventType) {
+    return db.prepare("SELECT COUNT(*) AS cnt FROM usage_events WHERE event_type = ?").get(eventType)
+        .cnt;
+}
 /**
  * Delete usage events older than the given number of days.
  */

package/dist/indexer/{file-context.js → walk/file-context.js}

@@ -9,8 +9,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { toPosix } from "../core/common";
-import { parseFrontmatter } from "../core/frontmatter";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { toPosix } from "../../core/common.js";
 /**
  * Build a FileContext from a stash root and an absolute file path.
  *
@@ -71,22 +71,17 @@ export function buildFileContext(stashRoot, absPath) {
 const matchers = [];
 /** Renderer lookup by name. */
 const renderers = new Map();
-let builtinsPromise;
 /**
- * Ensure that built-in matchers and renderers are registered.
- * Called lazily on first use of runMatchers/getRenderer.
- * Stores the in-progress promise so parallel callers don't double-register.
+ * Ensure that all built-in indexer contributors are registered.
+ *
+ * Delegates to the single `initIndexer()` composition root (see
+ * `src/indexer/init.ts`). Imported dynamically to keep this a lazy gate and to
+ * avoid a static import cycle (init -> renderers -> file-context). Called on
+ * first use of runMatchers/getRenderer/getAllRenderers; idempotent.
  */
 async function ensureBuiltinsRegistered() {
-    if (!builtinsPromise) {
-        builtinsPromise = (async () => {
-            const { registerBuiltinMatchers } = await import("./matchers.js");
-            const { registerBuiltinRenderers } = await import("../output/renderers.js");
-            registerBuiltinMatchers();
-            registerBuiltinRenderers();
-        })();
-    }
-    return builtinsPromise;
+    const { initIndexer } = await import("../init.js");
+    await initIndexer();
 }
 /**
  * Register an AssetMatcher.

package/dist/indexer/{matchers.js → walk/matchers.js}

@@ -8,10 +8,10 @@
  * one heuristic. The public `*Matcher` exports compose those facts into the
  * `MatchResult` shape expected by the rest of the indexer.
  */
-import { defaultRendererRegistry } from "../core/asset-registry";
-import { SCRIPT_EXTENSIONS } from "../core/asset-spec";
-import { looksLikeWorkflow } from "../workflows/parser";
-import { registerMatcher } from "./file-context";
+import { defaultRendererRegistry } from "../../core/asset/asset-registry.js";
+import { SCRIPT_EXTENSIONS } from "../../core/asset/asset-spec.js";
+import { looksLikeWorkflow } from "../../workflows/parser.js";
+import { registerMatcher } from "./file-context.js";
 // ---------------------------------------------------------------------------
 // Private data
 // ---------------------------------------------------------------------------
@@ -56,11 +56,6 @@ const DIR_TYPE_MAP = [
         type: "env",
         test: (_, fileName) => fileName === ".env" || fileName.endsWith(".env"),
     },
-    {
-        dir: "vaults",
-        type: "vault",
-        test: (_, fileName) => fileName === ".env" || fileName.endsWith(".env"),
-    },
     {
         dir: "secrets",
         type: "secret",
@@ -74,6 +69,15 @@ const DIR_TYPE_MAP = [
         type: "task",
         test: (ext) => ext === ".md",
     },
+    {
+        // #561 — agent session assets live under `sessions/<harness>/<id>.md`.
+        // classifyByDirectory walks every ancestor dir, so a nested file still
+        // matches the `sessions` rule. Without this entry the file falls through
+        // to classifyBySmartMd and is mistyped as `knowledge`.
+        dir: "sessions",
+        type: "session",
+        test: (ext) => ext === ".md",
+    },
 ];
 const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
 // Files that should never be treated as the typed asset for the surrounding

package/dist/indexer/{path-resolver.js → walk/path-resolver.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 { parseAssetRef } from "../core/asset-ref";
-import { resolveAssetPathFromName, TYPE_DIRS } from "../core/asset-spec";
-import { isWithin } from "../core/common";
-import { resolveSourcesForOrigin } from "../registry/origin-resolve";
-import { lookup } from "./indexer";
-import { resolveSourceEntries } from "./search-source";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { isWithin } from "../../core/common.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { lookup } from "../indexer.js";
+import { resolveSourceEntries } from "../search/search-source.js";
 function normalizeRef(ref) {
     return typeof ref === "string" ? parseAssetRef(ref) : ref;
 }

package/dist/indexer/{project-context.js → walk/project-context.js}

@@ -20,7 +20,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { resolveWorkflowScopeAnchor } from "../workflows/scope-key.js";
+import { resolveWorkflowScopeAnchor } from "../../workflows/authoring/scope-key.js";
 // Words that appear in almost every project name and carry no discriminating
 // signal for ranking. Filtered out after token splitting.
 const TOKEN_BLOCKLIST = new Set([

package/dist/indexer/{walker.js → walk/walker.js}

@@ -10,8 +10,9 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { isRelevantAssetFile } from "../core/asset-spec";
-import { buildFileContext } from "./file-context";
+import { isRelevantAssetFile } from "../../core/asset/asset-spec.js";
+import { spawnSync } from "../../runtime.js";
+import { buildFileContext } from "./file-context.js";
 const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
 /**
  * Walk a type root directory and return files grouped by their parent directory.
@@ -80,7 +81,7 @@ function walkStashGit(stashRoot) {
     if (!isInsideGitRepo(stashRoot))
         return null;
     // Get tracked + untracked (non-ignored) files
-    const result = Bun.spawnSync(["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", "."], {
+    const result = spawnSync(["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", "."], {
         cwd: stashRoot,
     });
     // result.success is false if the process exited non-zero OR git was not found

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

@@ -0,0 +1,39 @@
+// 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/.
+/**
+ * Shared agent-command-builder types and helpers (#563).
+ *
+ * Extracted from `agent/builders.ts` so per-harness builders (e.g.
+ * `harnesses/claude/agent-builder.ts`) can depend on the common
+ * types/validation WITHOUT creating an import cycle back through
+ * `builders.ts` (which imports the per-harness builders into its registry).
+ * This module is a dependency-graph LEAF for the builder subsystem.
+ *
+ * Behaviour-preserving: the type shapes and helper bodies are unchanged from
+ * their previous home in `builders.ts`.
+ */
+import { UsageError } from "../../core/errors.js";
+/**
+ * Guard against values that start with `--`, which would be mis-interpreted as
+ * CLI flags by the spawned process when used as flag values (model, systemPrompt).
+ * Bun.spawn uses array argv so there is no shell injection, but a `--`-prefixed
+ * value passed as the argument to `--model` or `--system-prompt` can still
+ * confuse the CLI parser of the target process.
+ */
+export function assertNotFlag(value, field) {
+    if (value?.trimStart().startsWith("--")) {
+        throw new UsageError(`${field} must not start with "--": ${JSON.stringify(value.slice(0, 60))}`, "INVALID_FLAG_VALUE");
+    }
+}
+/**
+ * Normalize a toolPolicy value to a comma-separated string suitable for a
+ * CLI flag. Structured policy objects are JSON-serialized.
+ */
+export function normalizeTools(tools) {
+    if (typeof tools === "string")
+        return tools;
+    if (Array.isArray(tools))
+        return tools.join(",");
+    return JSON.stringify(tools);
+}