akm-cli 0.8.3 → 0.9.0-beta.1

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);
+}

package/dist/integrations/agent/builders.js

@@ -12,88 +12,21 @@
  * Adding a new platform: implement `AgentCommandBuilder`, add to
  * `BUILTIN_BUILDERS`. Nothing else changes.
  */
-import { UsageError } from "../../core/errors";
-import { resolveModel } from "./model-aliases";
-// ── Validation helpers ────────────────────────────────────────────────────────
-/**
- * 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.
- */
-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");
-    }
-}
-// ── Tool normalization ────────────────────────────────────────────────────────
-/**
- * Normalize a toolPolicy value to a comma-separated string suitable for a
- * CLI flag. Structured policy objects are JSON-serialized.
- */
-function normalizeTools(tools) {
-    if (typeof tools === "string")
-        return tools;
-    if (Array.isArray(tools))
-        return tools.join(",");
-    return JSON.stringify(tools);
-}
+import { claudeBuilder } from "../harnesses/claude/agent-builder.js";
+import { opencodeBuilder } from "../harnesses/opencode/agent-builder.js";
+// Types + shared validation helpers live in the leaf module `builder-shared.ts`
+// so per-harness builders (harnesses/claude/agent-builder.ts) can depend on them
+// without importing this file back — avoiding an init-order cycle through
+// BUILTIN_BUILDERS (#563). Re-exported here so existing `agent/builders` import
+// sites keep working.
+import { assertNotFlag } from "./builder-shared.js";
+import { resolveModel } from "./model-aliases.js";
+export { assertNotFlag, normalizeTools } from "./builder-shared.js";
 // ── Platform builders ─────────────────────────────────────────────────────────
-/**
- * OpenCode builder.
- * Command shape: opencode run [--system-prompt "..."] [--model <m>] "<prompt>"
- *
- * Tool policy is omitted — opencode manages tool access through its own agent
- * config files, not via CLI flags.
- */
-const opencodeBuilder = {
-    platform: "opencode",
-    build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
-        const args = [...profile.args]; // starts with ["run"]
-        if (req.systemPrompt) {
-            args.push("--system-prompt", req.systemPrompt);
-        }
-        if (req.model) {
-            const resolved = resolveModel(req.model, "opencode", profile.modelAliases);
-            args.push("--model", resolved);
-        }
-        args.push("--");
-        args.push(req.prompt);
-        return { argv: [profile.bin, ...args] };
-    },
-};
-/**
- * Claude Code builder.
- * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
- *
- * --print switches Claude Code to non-interactive captured output mode.
- */
-const claudeBuilder = {
-    platform: "claude",
-    build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
-        const args = [...profile.args];
-        if (req.systemPrompt) {
-            args.push("--system-prompt", req.systemPrompt);
-        }
-        if (req.model) {
-            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
-            args.push("--model", resolved);
-        }
-        if (req.tools) {
-            args.push("--allowedTools", normalizeTools(req.tools));
-        }
-        // --print = non-interactive, outputs to stdout — required for captured mode
-        args.push("--print");
-        args.push("--");
-        args.push(req.prompt);
-        return { argv: [profile.bin, ...args] };
-    },
-};
+// The OpenCode builder was migrated to its harness directory in #564
+// (`harnesses/opencode/agent-builder.ts`) and the Claude Code builder in #563
+// (`harnesses/claude/agent-builder.ts`). Both are imported back into
+// BUILTIN_BUILDERS below so platform routing is unchanged.
 /**
  * Default builder — used for custom profiles and any platform without a
  * dedicated builder. Passes systemPrompt and model via the same flags as

package/dist/integrations/agent/config.js

@@ -1,9 +1,10 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { ConfigError } from "../../core/errors";
-import { warn } from "../../core/warn";
-import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
+import { VALID_HARNESS_IDS } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
 /**
  * Default hard timeout for an agent CLI (60s — matches the value used in
  * `docs/configuration.md`).
@@ -141,7 +142,8 @@ export function parseAgentProfilesMapV2(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const out = {};
-    const VALID_PLATFORMS = ["opencode", "claude", "opencode-sdk"];
+    // Derives from the canonical harness-id source of truth (#565).
+    const VALID_PLATFORMS = VALID_HARNESS_IDS;
     for (const [name, raw] of Object.entries(value)) {
         if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
             warn(`[akm] Ignoring profiles.agent["${name}"]: expected an object.`);

package/dist/integrations/agent/detect.js

@@ -15,7 +15,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { listResolvedAgentProfiles } from "./config";
+import { listResolvedAgentProfiles } from "./config.js";
 /**
  * Default PATH lookup. Walks `process.env.PATH` and returns the first
  * existing executable file. Returns `undefined` when the bin is not on